wortsammler 0.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- data/.gitignore +17 -0
- data/Gemfile +4 -0
- data/LICENSE.txt +22 -0
- data/README.md +131 -0
- data/README.pdf +0 -0
- data/Rakefile +34 -0
- data/bin/wortsammler +4 -0
- data/lib/wortsammler/class.Traceable.md.rb +104 -0
- data/lib/wortsammler/class.Traceable.rb +387 -0
- data/lib/wortsammler/class.proolib.rb +747 -0
- data/lib/wortsammler/class.treetopHelper.rb +117 -0
- data/lib/wortsammler/exe.wortsammler.rb +428 -0
- data/lib/wortsammler/log_helper.rb +8 -0
- data/lib/wortsammler/mdTraceParser.treetop +55 -0
- data/lib/wortsammler/rake_helper.rb +28 -0
- data/lib/wortsammler/version.rb +3 -0
- data/lib/wortsammler.rb +5 -0
- data/pkg/wortsammler-0.0.1.gem +0 -0
- data/resources/default.latex +225 -0
- data/resources/logo.jpg +0 -0
- data/resources/main.md +268 -0
- data/resources/rakefile.rb +5 -0
- data/resources/requirementsSynopsis.graphml +17 -0
- data/resources/sample_the-sample-document.yaml +51 -0
- data/spec/test.graphml +74 -0
- data/spec/traceable_spec.rb +299 -0
- data/spec/wortsammler_spec.rb +168 -0
- data/testresults/wortsammler_testresults.html +408 -0
- data/testresults/wortsammler_testresults.log +59 -0
- data/wortsammler.gemspec +53 -0
- metadata +282 -0
data/.gitignore
ADDED
data/Gemfile
ADDED
data/LICENSE.txt
ADDED
@@ -0,0 +1,22 @@
|
|
1
|
+
Copyright (c) 2013 Bernhard Weichel
|
2
|
+
|
3
|
+
MIT License
|
4
|
+
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining
|
6
|
+
a copy of this software and associated documentation files (the
|
7
|
+
"Software"), to deal in the Software without restriction, including
|
8
|
+
without limitation the rights to use, copy, modify, merge, publish,
|
9
|
+
distribute, sublicense, and/or sell copies of the Software, and to
|
10
|
+
permit persons to whom the Software is furnished to do so, subject to
|
11
|
+
the following conditions:
|
12
|
+
|
13
|
+
The above copyright notice and this permission notice shall be
|
14
|
+
included in all copies or substantial portions of the Software.
|
15
|
+
|
16
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
17
|
+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
18
|
+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
19
|
+
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
20
|
+
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
21
|
+
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
22
|
+
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
data/README.md
ADDED
@@ -0,0 +1,131 @@
|
|
1
|
+
# Wortsammler
|
2
|
+
|
3
|
+
Wortsammler (colloquial German for *word collector*) is an environment
|
4
|
+
to maintain doucmentation in markdown and publish it in various formats
|
5
|
+
for different audiences. It originated in some project specific hacks
|
6
|
+
wrapping around [pandoc][]. But now I refactored it since I use it in
|
7
|
+
more than two projects now and think it might be beneficial for others
|
8
|
+
as well.
|
9
|
+
|
10
|
+
Typical application of Wortsammler is user manuals, project documents,
|
11
|
+
user manuals.
|
12
|
+
|
13
|
+
Particular features of wortsammler are
|
14
|
+
|
15
|
+
- various output formats
|
16
|
+
- support of requirement management
|
17
|
+
- generate documents for different audiences based on single sources
|
18
|
+
- support for snippets
|
19
|
+
- include parts from other PDF files (only for pdf output yet)
|
20
|
+
|
21
|
+
Basically Wortsammler comprises of
|
22
|
+
|
23
|
+
- a directory structure for source document sources
|
24
|
+
- a manifest file to control the publication process
|
25
|
+
- involved input files
|
26
|
+
- expected output formats
|
27
|
+
- expected editions
|
28
|
+
- Requirements tracing (upstream / downstream)
|
29
|
+
|
30
|
+
- a command line tool to produce the doucments (`wortsammler`)
|
31
|
+
|
32
|
+
Wortsammler is built on top of other open source tools, in particular:
|
33
|
+
|
34
|
+
- pandoc
|
35
|
+
- LaTeX
|
36
|
+
- ruby and a bunch of gems
|
37
|
+
|
38
|
+
I did not invent new markdown syntax to implement the features mentioned
|
39
|
+
aforehead. In other words, any wortsammler flavored markdown file should
|
40
|
+
reasonably be processed in standalone pandoc. I implemented particular
|
41
|
+
patterns which are boiled down to either vanilla pandoc markdown or to
|
42
|
+
LaTeX / HTML.
|
43
|
+
|
44
|
+
The features are based on three appraoches:
|
45
|
+
|
46
|
+
1. particular pattern in existing markdown
|
47
|
+
2. embedded HTML/LaTeX
|
48
|
+
3. specific syntax in strikethrouh sections (e.g. ~~ED simple~~)
|
49
|
+
|
50
|
+
## Installation
|
51
|
+
|
52
|
+
$ gem install wortsammler
|
53
|
+
|
54
|
+
In order to use Wortsammler, you need to install the prerequisites:
|
55
|
+
|
56
|
+
- ruby 1.9.3 of course
|
57
|
+
- pandoc 1.9.4.2 or above
|
58
|
+
|
59
|
+
I plan to upgrade to 1.11.1 asap
|
60
|
+
|
61
|
+
- tex, in particular xelatex 3.1415926-2.4-0.9998
|
62
|
+
|
63
|
+
## getting started
|
64
|
+
|
65
|
+
### display the options
|
66
|
+
|
67
|
+
Wortsammler -h
|
68
|
+
|
69
|
+
### process markdown files
|
70
|
+
|
71
|
+
Wortsammler -pi readme.md -o.
|
72
|
+
-- generates readme.pdf
|
73
|
+
|
74
|
+
Wortsammler -pi readme.md -f pdf:docx:html -o.
|
75
|
+
-- generates readme.pdf, readme.html, readme.docx
|
76
|
+
|
77
|
+
Wortsammler -bi readme.md
|
78
|
+
-- beautifies readme.md (normalizes the markdown)
|
79
|
+
|
80
|
+
Wortsammler -bi .
|
81
|
+
-- recursively beautifies all markdown files in the current folder
|
82
|
+
|
83
|
+
### initialize a project
|
84
|
+
|
85
|
+
Wortsammler init <folder>
|
86
|
+
|
87
|
+
This command generates the proposed directory structure, a first
|
88
|
+
document manifest and a rake file to do the processing.
|
89
|
+
|
90
|
+
The rakefile is in `<folder>/30_Sources/ZSUPP_Tools`
|
91
|
+
|
92
|
+
### generate document
|
93
|
+
|
94
|
+
rake -T -- show all rake tasks
|
95
|
+
rake sample -- format the sample document
|
96
|
+
|
97
|
+
## known issues
|
98
|
+
|
99
|
+
- as usual documentation is not complete
|
100
|
+
- requirement collection only works via manifest
|
101
|
+
- some features (in particular referencing) should use pandoc 1.11
|
102
|
+
features
|
103
|
+
- HTML and DOCX styling does not work
|
104
|
+
- It extends `String`
|
105
|
+
- Specific syntax in strikethrough is still processed as one line
|
106
|
+
which is not very robust
|
107
|
+
- as of now the "framework" is hard to use in other applications
|
108
|
+
|
109
|
+
## future plans
|
110
|
+
|
111
|
+
- provide a sublime text package
|
112
|
+
- improve documentation (it is flying around in German and needs to be
|
113
|
+
consolidated)
|
114
|
+
- support epub
|
115
|
+
|
116
|
+
## contributing
|
117
|
+
|
118
|
+
1. play with it
|
119
|
+
2. give feedback to <bernhard.weichel@googlemail.com> and/or create
|
120
|
+
issues
|
121
|
+
3. Fork it
|
122
|
+
4. Create your feature branch (`git checkout -b my-new-feature`)
|
123
|
+
5. Commit your changes (`git commit -am 'Add some feature'`)
|
124
|
+
6. Push to the branch (`git push origin my-new-feature`)
|
125
|
+
7. Create new Pull Request
|
126
|
+
|
127
|
+
## thanks to
|
128
|
+
|
129
|
+
- John Mc Farlane for [pandoc][]
|
130
|
+
|
131
|
+
[pandoc]: http://johnmacfarlane.net/pandoc/
|
data/README.pdf
ADDED
Binary file
|
data/Rakefile
ADDED
@@ -0,0 +1,34 @@
|
|
1
|
+
require "bundler/gem_tasks"
|
2
|
+
require 'rake/clean'
|
3
|
+
require 'rspec/core/rake_task'
|
4
|
+
#require 'ruby-debug'
|
5
|
+
|
6
|
+
CLEAN << "testproject"
|
7
|
+
|
8
|
+
desc "Run specs"
|
9
|
+
RSpec::Core::RakeTask.new do |t|
|
10
|
+
t.pattern = "./spec/**/*_spec.rb" # don't need this, it's default.
|
11
|
+
t.rspec_opts = ['-d -fd -fd --out ./testresults/wortsammler_testresults.log -fh --out ./testresults/wortsammler_testresults.html']
|
12
|
+
# Put spec opts in a file named .rspec in root
|
13
|
+
end
|
14
|
+
|
15
|
+
desc "Generate code coverage"
|
16
|
+
RSpec::Core::RakeTask.new(:coverage) do |t|
|
17
|
+
t.pattern = "./spec/**/*_spec.rb" # don't need this, it's default.
|
18
|
+
t.rcov = true
|
19
|
+
t.rcov_opts = ['--exclude', 'spec']
|
20
|
+
end
|
21
|
+
|
22
|
+
desc "create documentation"
|
23
|
+
task :doc do
|
24
|
+
sh "bin/wortsammler -bi README.md"
|
25
|
+
sh "bin/wortsammler -pi README.md -o ."
|
26
|
+
sh "yard doc"
|
27
|
+
end
|
28
|
+
|
29
|
+
desc "run tests"
|
30
|
+
task :test => [:clean, :spec]
|
31
|
+
|
32
|
+
task :default do
|
33
|
+
rake -T
|
34
|
+
end
|
data/bin/wortsammler
ADDED
@@ -0,0 +1,104 @@
|
|
1
|
+
#
|
2
|
+
# this mixin represents the TeX specific methods of Traceable
|
3
|
+
#
|
4
|
+
#require 'ruby-debug' if not RUBY_PLATFORM=="i386-mingw32"
|
5
|
+
require 'treetop'
|
6
|
+
require File.dirname(__FILE__) + "/class.treetophelper"
|
7
|
+
require File.dirname(__FILE__) + "/class.Traceable"
|
8
|
+
require File.dirname(__FILE__) + "/class.Traceable.md"
|
9
|
+
|
10
|
+
Treetop.load File.dirname(__FILE__) + "/mdTraceParser.treetop"
|
11
|
+
|
12
|
+
|
13
|
+
class TraceableSet
|
14
|
+
|
15
|
+
|
16
|
+
|
17
|
+
# this generates a synopsis of traces in markdown Format
|
18
|
+
# @param [Symbol] selectedCategory the the category of the Traceables
|
19
|
+
# which shall be reported.
|
20
|
+
def reqtraceSynopsis(selectedCategory)
|
21
|
+
all_traces(selectedCategory).
|
22
|
+
sort_by{|x| trace_order_index(x.id) }.
|
23
|
+
map{|t|
|
24
|
+
tidm=t.id.gsub("_","-")
|
25
|
+
|
26
|
+
lContributes=t.contributes_to.
|
27
|
+
# map{|c| cm=c.gsub("_","-"); "[\[#{c}\]](#RT-#{cm})"}
|
28
|
+
map{|c| cm=c.gsub("_","-"); "<a href=\"#RT-#{cm}\">\[#{c}\]</a>"}
|
29
|
+
|
30
|
+
luptraces = [uptrace_ids[t.id]].flatten.compact.map{|x| self[x]}
|
31
|
+
|
32
|
+
luptraces=luptraces.
|
33
|
+
sort_by{|x| trace_order_index(x.id)}.
|
34
|
+
map{|u|
|
35
|
+
um = u.id.gsub("_","-")
|
36
|
+
" - <a href=\"#RT-#{um}\">[#{u.id}]</a> #{u.header_orig}"
|
37
|
+
}
|
38
|
+
|
39
|
+
["- ->[#{t.id}] <!-- --> <a id=\"RT-#{tidm}\"/>**#{t.header_orig}**" +
|
40
|
+
# " (#{t.contributes_to.join(', ')})", "",
|
41
|
+
" (#{lContributes.join(', ')})", "",
|
42
|
+
luptraces
|
43
|
+
].flatten.join("\n")
|
44
|
+
}.join("\n\n")
|
45
|
+
end
|
46
|
+
|
47
|
+
|
48
|
+
# this generates the downstream_tracefile
|
49
|
+
def to_downstream_tracefile(selectedCategory)
|
50
|
+
all_traces(selectedCategory).
|
51
|
+
sort_by{|x| trace_order_index(x.id) }.
|
52
|
+
map{|t|
|
53
|
+
"\n\n[#{t.id}] **#{t.header_orig}** { }()"
|
54
|
+
}.join("\n\n")
|
55
|
+
end
|
56
|
+
|
57
|
+
# this generates the todo - list
|
58
|
+
|
59
|
+
# TODO: add this method
|
60
|
+
|
61
|
+
# this method processes all traces in a particular file
|
62
|
+
# @param [String] mdFile name of the Markdown file which shall
|
63
|
+
# be scanned.
|
64
|
+
def self.processTracesInMdFile(mdFile)
|
65
|
+
|
66
|
+
parser=TraceInMarkdownParser.new
|
67
|
+
parser.consume_all_input = true
|
68
|
+
|
69
|
+
raw_md_code_file=File.open(mdFile)
|
70
|
+
raw_md_code = raw_md_code_file.readlines.join
|
71
|
+
raw_md_code_file.close
|
72
|
+
# print mdFile
|
73
|
+
result = parser.parse(raw_md_code)
|
74
|
+
# print " ... parsed\n" todo: use logger here
|
75
|
+
|
76
|
+
result_set = TraceableSet.new
|
77
|
+
|
78
|
+
if result
|
79
|
+
result.descendant.select{|x| x.getLabel==="trace"}.each{|c|
|
80
|
+
id = c.traceId.payload.text_value
|
81
|
+
uptraces = c.uptraces.payload.text_value
|
82
|
+
header = c.traceHead.payload.text_value
|
83
|
+
bodytext = c.traceBody.payload.text_value
|
84
|
+
uptraces = c.uptraces.payload.text_value
|
85
|
+
# Populate the Traceable entry
|
86
|
+
theTrace = Traceable.new
|
87
|
+
theTrace.info = mdFile
|
88
|
+
theTrace.id = id
|
89
|
+
theTrace.header_orig = header
|
90
|
+
theTrace.body_orig = bodytext
|
91
|
+
theTrace.trace_orig = c.text_value
|
92
|
+
theTrace.contributes_to = uptraces.gsub!(/\s*/, "").split(",")
|
93
|
+
theTrace.category = :SPECIFICATION_ITEM
|
94
|
+
result_set.add(theTrace)
|
95
|
+
}
|
96
|
+
# puts " .... finished"
|
97
|
+
else
|
98
|
+
puts ["","-----------", texFile, parser.failure_reason].join("\n")
|
99
|
+
end
|
100
|
+
result_set
|
101
|
+
end
|
102
|
+
|
103
|
+
|
104
|
+
end
|