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 ADDED
@@ -0,0 +1,17 @@
1
+ *.gem
2
+ *.rbc
3
+ .bundle
4
+ .config
5
+ .yardoc
6
+ Gemfile.lock
7
+ InstalledFiles
8
+ _yardoc
9
+ coverage
10
+ doc/
11
+ lib/bundler/man
12
+ rdoc
13
+ spec/reports
14
+ test/tmp
15
+ test/version_tmp
16
+ tmp
17
+ testproject
data/Gemfile ADDED
@@ -0,0 +1,4 @@
1
+ source 'https://rubygems.org'
2
+
3
+ # Specify your gem's dependencies in wortsammler.gemspec
4
+ gemspec
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,4 @@
1
+ #!/usr/bin/env ruby
2
+ #
3
+ $LOAD_PATH.unshift File.join(File.dirname(__FILE__), "..", "lib")
4
+ require "wortsammler/exe.wortsammler.rb"
@@ -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