hoe-manualgen 0.2.0 → 0.3.0
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.tar.gz.sig +0 -0
- data/ChangeLog +333 -0
- data/History.rdoc +28 -0
- data/Manifest.txt +41 -0
- data/{README.md → README.rdoc} +11 -12
- data/Rakefile +14 -57
- data/data/hoe-manualgen/lib/api-filter.rb +2 -2
- data/data/hoe-manualgen/lib/editorial-filter.rb +16 -16
- data/data/hoe-manualgen/lib/examples-filter.rb +40 -48
- data/data/hoe-manualgen/lib/links-filter.rb +21 -21
- data/data/hoe-manualgen/resources/css/reset.css +112 -0
- data/lib/hoe/manualgen.rb +14 -15
- metadata +60 -83
- metadata.gz.sig +0 -0
- data/History.md +0 -16
data/Rakefile
CHANGED
@@ -1,14 +1,16 @@
|
|
1
1
|
#!/usr/bin/env rake
|
2
2
|
|
3
|
+
require 'pathname'
|
4
|
+
|
3
5
|
begin
|
4
6
|
require 'hoe'
|
5
7
|
rescue LoadError
|
6
|
-
|
8
|
+
abort "This Rakefile requires Hoe (gem install hoe)"
|
7
9
|
end
|
8
10
|
|
9
11
|
require 'rake/clean'
|
10
12
|
|
11
|
-
Hoe.add_include_dirs 'lib'
|
13
|
+
Hoe.add_include_dirs 'lib', 'data/hoe-manualgen'
|
12
14
|
|
13
15
|
Hoe.plugin :mercurial
|
14
16
|
Hoe.plugin :signing
|
@@ -17,71 +19,26 @@ Hoe.plugin :manualgen
|
|
17
19
|
Hoe.plugins.delete :rubyforge
|
18
20
|
|
19
21
|
hoespec = Hoe.spec 'hoe-manualgen' do
|
20
|
-
self.readme_file = 'README.
|
21
|
-
self.history_file = 'History.
|
22
|
+
self.readme_file = 'README.rdoc'
|
23
|
+
self.history_file = 'History.rdoc'
|
24
|
+
self.extra_rdoc_files = FileList[ '*.rdoc', 'data/hoe-manualgen/lib/*.rb' ]
|
22
25
|
|
23
26
|
self.developer 'Michael Granger', 'ged@FaerieMUD.org'
|
24
27
|
|
25
|
-
self.
|
26
|
-
|
27
|
-
|
28
|
-
'rcodetools' => '~> 0.8',
|
29
|
-
}
|
30
|
-
self.extra_dev_deps.push *{
|
31
|
-
'rspec' => '~> 2.4',
|
32
|
-
'tidy-ext' => '~> 0.1',
|
33
|
-
}
|
28
|
+
self.dependency 'hoe', "~> #{Hoe::VERSION[/^\d+\.\d+/]}"
|
29
|
+
self.dependency 'RedCloth', '~> 4.2'
|
30
|
+
self.dependency 'rcodetools', '~> 0.8'
|
34
31
|
|
35
|
-
self.
|
36
|
-
self.spec_extras[:signing_key] = '/Volumes/Keys/ged-private_gem_key.pem'
|
32
|
+
self.dependency 'tidy-ext', '~> 0.1', :developer
|
37
33
|
|
34
|
+
self.manual_lib_dir = Pathname.pwd + 'data/hoe-manualgen/lib'
|
35
|
+
|
36
|
+
self.spec_extras[:licenses] = ["BSD"]
|
38
37
|
self.require_ruby_version( '>=1.8.7' )
|
39
38
|
|
40
39
|
self.hg_sign_tags = true if self.respond_to?( :hg_sign_tags= )
|
41
|
-
|
42
|
-
self.extra_rdoc_files += Dir.glob( 'data/hoe-manualgen/lib/*.rb' )
|
43
40
|
self.rdoc_locations << "deveiate:/usr/local/www/public/code/#{remote_rdoc_dir}"
|
44
41
|
end
|
45
42
|
|
46
43
|
ENV['VERSION'] ||= hoespec.spec.version.to_s
|
47
44
|
|
48
|
-
begin
|
49
|
-
include Hoe::MercurialHelpers
|
50
|
-
|
51
|
-
### Task: prerelease
|
52
|
-
desc "Append the package build number to package versions"
|
53
|
-
task :pre do
|
54
|
-
rev = get_numeric_rev()
|
55
|
-
trace "Current rev is: %p" % [ rev ]
|
56
|
-
hoespec.spec.version.version << "pre#{rev}"
|
57
|
-
Rake::Task[:gem].clear
|
58
|
-
|
59
|
-
Gem::PackageTask.new( hoespec.spec ) do |pkg|
|
60
|
-
pkg.need_zip = true
|
61
|
-
pkg.need_tar = true
|
62
|
-
end
|
63
|
-
end
|
64
|
-
|
65
|
-
### Make the ChangeLog update if the repo has changed since it was last built
|
66
|
-
file '.hg/branch'
|
67
|
-
file 'ChangeLog' => '.hg/branch' do |task|
|
68
|
-
$stderr.puts "Updating the changelog..."
|
69
|
-
content = make_changelog()
|
70
|
-
File.open( task.name, 'w', 0644 ) do |fh|
|
71
|
-
fh.print( content )
|
72
|
-
end
|
73
|
-
end
|
74
|
-
|
75
|
-
# Rebuild the ChangeLog immediately before release
|
76
|
-
task :prerelease => 'ChangeLog'
|
77
|
-
|
78
|
-
rescue NameError => err
|
79
|
-
task :no_hg_helpers do
|
80
|
-
fail "Couldn't define the :pre task: %s: %s" % [ err.class.name, err.message ]
|
81
|
-
end
|
82
|
-
|
83
|
-
task :pre => :no_hg_helpers
|
84
|
-
task 'ChangeLog' => :no_hg_helpers
|
85
|
-
|
86
|
-
end
|
87
|
-
|
@@ -29,7 +29,7 @@ class Hoe::ManualGen::APIFilter < Hoe::ManualGen::PageFilter
|
|
29
29
|
<\?
|
30
30
|
api # Instruction Target
|
31
31
|
\s+
|
32
|
-
(?:"
|
32
|
+
(?:"
|
33
33
|
(.*?) # Optional link text [$1]
|
34
34
|
":)?
|
35
35
|
(.*?) # Class name [$2]
|
@@ -71,7 +71,7 @@ class Hoe::ManualGen::APIFilter < Hoe::ManualGen::PageFilter
|
|
71
71
|
return %{<a href="%s%s">%s</a>} % [
|
72
72
|
classuri,
|
73
73
|
make_anchor( methodname ),
|
74
|
-
link_text || (classname + methodname || '')
|
74
|
+
link_text || (classname + (methodname || ''))
|
75
75
|
]
|
76
76
|
else
|
77
77
|
link_text ||= classname
|
@@ -1,24 +1,24 @@
|
|
1
|
-
#!/usr/bin/ruby
|
2
|
-
#
|
1
|
+
#!/usr/bin/ruby
|
2
|
+
#
|
3
3
|
# A manual filter to highlight content that needs editorial help.
|
4
|
-
#
|
4
|
+
#
|
5
5
|
# Authors:
|
6
6
|
# * Michael Granger <ged@FaerieMUD.org>
|
7
|
-
#
|
8
|
-
#
|
7
|
+
#
|
8
|
+
#
|
9
9
|
|
10
10
|
|
11
11
|
|
12
12
|
### A filter for making editorial marks in manual content.
|
13
|
-
###
|
13
|
+
###
|
14
14
|
### Editorial marks are XML processing instructions. There are several available types of
|
15
15
|
### marks:
|
16
16
|
###
|
17
17
|
### <?ed "This is an editor's note." ?>
|
18
18
|
### <?ed verify:"this content needs checking or verification" ?>
|
19
|
-
###
|
19
|
+
###
|
20
20
|
class Hoe::ManualGen::EditorialFilter < Hoe::ManualGen::PageFilter
|
21
|
-
|
21
|
+
|
22
22
|
# PI ::= '<?' PITarget (S (Char* - (Char* '?>' Char*)))? '?>'
|
23
23
|
LinkPI = %r{
|
24
24
|
<\?
|
@@ -26,14 +26,14 @@ class Hoe::ManualGen::EditorialFilter < Hoe::ManualGen::PageFilter
|
|
26
26
|
\s+
|
27
27
|
(\w+?) # type of editorial mark [$1]
|
28
28
|
:? # optional colon
|
29
|
-
"
|
29
|
+
"
|
30
30
|
(.*?) # content that should be edited [$2]
|
31
31
|
"
|
32
32
|
\s*
|
33
33
|
\?>
|
34
34
|
}x
|
35
|
-
|
36
|
-
|
35
|
+
|
36
|
+
|
37
37
|
######
|
38
38
|
public
|
39
39
|
######
|
@@ -44,16 +44,16 @@ class Hoe::ManualGen::EditorialFilter < Hoe::ManualGen::PageFilter
|
|
44
44
|
# Grab the tag values
|
45
45
|
mark_type = $1
|
46
46
|
content = $2
|
47
|
-
|
47
|
+
|
48
48
|
self.generate_mark( page, mark_type, content )
|
49
49
|
end
|
50
50
|
end
|
51
|
-
|
52
|
-
|
51
|
+
|
52
|
+
|
53
53
|
### Create an HTML fragment from the parsed LinkPI.
|
54
54
|
def generate_mark( current_page, mark_type, content )
|
55
55
|
return "%%(editorial %s-mark)%s%%" % [ mark_type, content ]
|
56
56
|
end
|
57
|
-
|
58
|
-
|
57
|
+
|
58
|
+
|
59
59
|
end
|
@@ -1,11 +1,12 @@
|
|
1
|
-
#!/usr/bin/ruby
|
2
|
-
#
|
1
|
+
#!/usr/bin/ruby
|
2
|
+
#encoding: utf-8
|
3
|
+
#
|
3
4
|
# A collection of standard filters for the manual generation tasklib.
|
4
|
-
#
|
5
|
+
#
|
5
6
|
# Authors:
|
6
7
|
# Michael Granger <ged@FaerieMUD.org>
|
7
|
-
#
|
8
|
-
#
|
8
|
+
#
|
9
|
+
#
|
9
10
|
|
10
11
|
# Dependencies deferred until #initialize
|
11
12
|
|
@@ -13,7 +14,7 @@
|
|
13
14
|
|
14
15
|
### A filter for inline example code or command-line sessions -- does
|
15
16
|
### syntax-checking for some languages and captioning.
|
16
|
-
###
|
17
|
+
###
|
17
18
|
### Examples are enclosed in XML processing instructions like so:
|
18
19
|
###
|
19
20
|
### <?example {language: ruby, testable: true, caption: "A fine example"} ?>
|
@@ -24,7 +25,7 @@
|
|
24
25
|
### This will be pulled out into a preformatted section in the HTML,
|
25
26
|
### highlighted as Ruby source, checked for valid syntax, and annotated with
|
26
27
|
### the specified caption. Valid keys in the example PI are:
|
27
|
-
###
|
28
|
+
###
|
28
29
|
### language::
|
29
30
|
### Specifies which (machine) language the example is in.
|
30
31
|
### testable::
|
@@ -33,7 +34,7 @@
|
|
33
34
|
### caption::
|
34
35
|
### A small blurb to put below the pulled-out example in the HTML.
|
35
36
|
class Hoe::ManualGen::ExamplesFilter < Hoe::ManualGen::PageFilter
|
36
|
-
|
37
|
+
|
37
38
|
DEFAULTS = {
|
38
39
|
:language => :ruby,
|
39
40
|
:line_numbers => :inline,
|
@@ -56,31 +57,22 @@ class Hoe::ManualGen::ExamplesFilter < Hoe::ManualGen::PageFilter
|
|
56
57
|
)?
|
57
58
|
\?>
|
58
59
|
}x
|
59
|
-
|
60
|
+
|
60
61
|
EndPI = %r{ <\? end (?: \s+ example )? \s* \?> }x
|
61
62
|
|
62
63
|
|
63
64
|
### Defer loading of dependenies until the filter is loaded
|
64
65
|
def initialize( *args )
|
65
|
-
|
66
|
-
|
67
|
-
|
68
|
-
|
69
|
-
|
70
|
-
|
71
|
-
|
72
|
-
require 'erb'
|
73
|
-
rescue LoadError => err
|
74
|
-
unless Object.const_defined?( :Gem )
|
75
|
-
require 'rubygems'
|
76
|
-
retry
|
77
|
-
end
|
78
|
-
|
79
|
-
raise
|
80
|
-
end
|
66
|
+
require 'pathname'
|
67
|
+
require 'strscan'
|
68
|
+
require 'yaml'
|
69
|
+
require 'rcodetools/xmpfilter'
|
70
|
+
require 'digest/md5'
|
71
|
+
require 'tmpdir'
|
72
|
+
require 'erb'
|
81
73
|
end
|
82
|
-
|
83
|
-
|
74
|
+
|
75
|
+
|
84
76
|
######
|
85
77
|
public
|
86
78
|
######
|
@@ -88,15 +80,15 @@ class Hoe::ManualGen::ExamplesFilter < Hoe::ManualGen::PageFilter
|
|
88
80
|
### Process the given +source+ for <?example ... ?> processing-instructions, calling out
|
89
81
|
def process( source, page, metadata )
|
90
82
|
scanner = StringScanner.new( source )
|
91
|
-
|
83
|
+
|
92
84
|
buffer = ''
|
93
85
|
until scanner.eos?
|
94
86
|
startpos = scanner.pos
|
95
|
-
|
87
|
+
|
96
88
|
# If we find an example
|
97
89
|
if scanner.skip_until( ExamplePI )
|
98
90
|
contents = ''
|
99
|
-
|
91
|
+
|
100
92
|
# Append the interstitial content to the buffer
|
101
93
|
if ( scanner.pos - startpos > scanner.matched.length )
|
102
94
|
offset = scanner.pos - scanner.matched.length - 1
|
@@ -106,13 +98,13 @@ class Hoe::ManualGen::ExamplesFilter < Hoe::ManualGen::PageFilter
|
|
106
98
|
# Append everything up to it to the buffer and save the contents of
|
107
99
|
# the tag
|
108
100
|
params = scanner[1]
|
109
|
-
|
101
|
+
|
110
102
|
# Now find the end of the example or complain
|
111
103
|
contentpos = scanner.pos
|
112
104
|
scanner.skip_until( EndPI ) or
|
113
|
-
raise "Unterminated example at line %d" %
|
105
|
+
raise "Unterminated example at line %d" %
|
114
106
|
[ scanner.string[0..scanner.pos].count("\n") ]
|
115
|
-
|
107
|
+
|
116
108
|
# Now build the example and append to the buffer
|
117
109
|
if ( scanner.pos - contentpos > scanner.matched.length )
|
118
110
|
offset = scanner.pos - scanner.matched.length - 1
|
@@ -128,11 +120,11 @@ class Hoe::ManualGen::ExamplesFilter < Hoe::ManualGen::PageFilter
|
|
128
120
|
end
|
129
121
|
buffer << scanner.rest
|
130
122
|
scanner.terminate
|
131
|
-
|
123
|
+
|
132
124
|
return buffer
|
133
125
|
end
|
134
|
-
|
135
|
-
|
126
|
+
|
127
|
+
|
136
128
|
### Filter out 'example' macros, doing syntax highlighting, and running
|
137
129
|
### 'testable' examples through a validation process appropriate to the
|
138
130
|
### language the example is in.
|
@@ -141,7 +133,7 @@ class Hoe::ManualGen::ExamplesFilter < Hoe::ManualGen::PageFilter
|
|
141
133
|
caption = options.delete( :caption )
|
142
134
|
content = ''
|
143
135
|
lang = options.delete( :language ).to_s
|
144
|
-
|
136
|
+
|
145
137
|
# Test it if it's testable
|
146
138
|
if options[:testable]
|
147
139
|
content = test_content( body, lang, page )
|
@@ -154,12 +146,12 @@ class Hoe::ManualGen::ExamplesFilter < Hoe::ManualGen::PageFilter
|
|
154
146
|
caption = %{<div class="caption">} + caption.to_s + %{</div>} if caption
|
155
147
|
|
156
148
|
return %{<notextile><div class="example #{lang}-example">%s%s</div></notextile>} %
|
157
|
-
|
149
|
+
[content, caption || '']
|
158
150
|
end
|
159
151
|
|
160
152
|
|
161
|
-
### Parse an options hash for filtering from the given +args+, which can either
|
162
|
-
### be a plain String, in which case it is assumed to be the name of the language the example
|
153
|
+
### Parse an options hash for filtering from the given +args+, which can either
|
154
|
+
### be a plain String, in which case it is assumed to be the name of the language the example
|
163
155
|
### is in, or a Hash of configuration options.
|
164
156
|
def parse_options( args )
|
165
157
|
args = "{ #{args} }" unless args.strip[0] == ?{
|
@@ -173,7 +165,7 @@ class Hoe::ManualGen::ExamplesFilter < Hoe::ManualGen::PageFilter
|
|
173
165
|
end
|
174
166
|
return DEFAULTS.merge( args )
|
175
167
|
end
|
176
|
-
|
168
|
+
|
177
169
|
|
178
170
|
### Test the given +content+ with a rule specific to the given +language+.
|
179
171
|
def test_content( body, language, page )
|
@@ -188,8 +180,8 @@ class Hoe::ManualGen::ExamplesFilter < Hoe::ManualGen::PageFilter
|
|
188
180
|
return body
|
189
181
|
end
|
190
182
|
end
|
191
|
-
|
192
|
-
|
183
|
+
|
184
|
+
|
193
185
|
### Test the specified Ruby content for valid syntax
|
194
186
|
def test_ruby_content( source, page )
|
195
187
|
# $stderr.puts "Testing ruby content..."
|
@@ -216,8 +208,8 @@ class Hoe::ManualGen::ExamplesFilter < Hoe::ManualGen::PageFilter
|
|
216
208
|
return "%s while testing: %s\n %s" %
|
217
209
|
[ err.class.name, err.message, err.backtrace.join("\n ") ]
|
218
210
|
end
|
219
|
-
|
220
|
-
|
211
|
+
|
212
|
+
|
221
213
|
### Test the specified YAML content for valid syntax
|
222
214
|
def test_yaml_content( source, metadata )
|
223
215
|
YAML.load( source )
|
@@ -226,13 +218,13 @@ class Hoe::ManualGen::ExamplesFilter < Hoe::ManualGen::PageFilter
|
|
226
218
|
else
|
227
219
|
return source
|
228
220
|
end
|
229
|
-
|
230
|
-
|
221
|
+
|
222
|
+
|
231
223
|
### Highlights the given +content+ in language +lang+.
|
232
224
|
def highlight( content, options, lang )
|
233
225
|
source = ERB::Util.html_escape( content )
|
234
226
|
return %Q{\n\n<pre class="brush:#{lang}">#{source}</pre>\n\n}
|
235
227
|
end
|
236
|
-
|
228
|
+
|
237
229
|
end
|
238
230
|
|
@@ -1,25 +1,25 @@
|
|
1
|
-
#!/usr/bin/ruby
|
2
|
-
#
|
1
|
+
#!/usr/bin/ruby
|
2
|
+
#
|
3
3
|
# A manual filter to generate links from the page catalog.
|
4
|
-
#
|
4
|
+
#
|
5
5
|
# Authors:
|
6
6
|
# * Michael Granger <ged@FaerieMUD.org>
|
7
7
|
# * Mahlon E. Smith <mahlon@martini.nu>
|
8
|
-
#
|
9
|
-
#
|
8
|
+
#
|
9
|
+
#
|
10
10
|
|
11
11
|
|
12
12
|
### A filter for generating links from the page catalog. This allows you to refer to other pages
|
13
13
|
### in the source and have them automatically updated as the structure of the manual changes.
|
14
|
-
###
|
14
|
+
###
|
15
15
|
### Links are XML processing instructions. Pages can be referenced in one of several ways:
|
16
16
|
###
|
17
17
|
### <?link Page Title ?>
|
18
18
|
### <?link "click here":Page Title ?>
|
19
19
|
### <?link Page Title #section_id ?>
|
20
20
|
### <?link "click here":Page Title#section_id ?>
|
21
|
-
###
|
22
|
-
### This first form links to a page by title. Link text defaults to the page title unless an
|
21
|
+
###
|
22
|
+
### This first form links to a page by title. Link text defaults to the page title unless an
|
23
23
|
### optional quoted string is prepended. If you want to link to an anchor inside the page, include
|
24
24
|
### its ID with a hash mark after the title.
|
25
25
|
###
|
@@ -32,13 +32,13 @@
|
|
32
32
|
### Again, the link text defaults to the page title, or can be overriden via a prepended string,
|
33
33
|
### and you can link into a page with an appended ID.
|
34
34
|
class Hoe::ManualGen::LinksFilter < Hoe::ManualGen::PageFilter
|
35
|
-
|
35
|
+
|
36
36
|
# PI ::= '<?' PITarget (S (Char* - (Char* '?>' Char*)))? '?>'
|
37
37
|
LinkPI = %r{
|
38
38
|
<\?
|
39
39
|
link # Instruction Target
|
40
40
|
\s+
|
41
|
-
(?:"
|
41
|
+
(?:"
|
42
42
|
(.*?) # Optional link text [$1]
|
43
43
|
":)?
|
44
44
|
(.*?) # Title or path [$2]
|
@@ -47,8 +47,8 @@ class Hoe::ManualGen::LinksFilter < Hoe::ManualGen::PageFilter
|
|
47
47
|
\s+
|
48
48
|
\?>
|
49
49
|
}x
|
50
|
-
|
51
|
-
|
50
|
+
|
51
|
+
|
52
52
|
######
|
53
53
|
public
|
54
54
|
######
|
@@ -60,19 +60,19 @@ class Hoe::ManualGen::LinksFilter < Hoe::ManualGen::PageFilter
|
|
60
60
|
link_text = $1
|
61
61
|
reference = $2
|
62
62
|
fragment = $3
|
63
|
-
|
63
|
+
|
64
64
|
self.generate_link( page, reference, link_text, fragment )
|
65
65
|
end
|
66
66
|
end
|
67
|
-
|
68
|
-
|
67
|
+
|
68
|
+
|
69
69
|
### Create an HTML link fragment from the parsed LinkPI.
|
70
70
|
def generate_link( current_page, reference, link_text=nil, fragment=nil )
|
71
71
|
|
72
72
|
if other_page = self.find_linked_page( current_page, reference )
|
73
73
|
href_path = other_page.sourcefile.relative_path_from( current_page.sourcefile.dirname )
|
74
74
|
href = href_path.to_s.gsub( '.page', '.html' )
|
75
|
-
|
75
|
+
|
76
76
|
if link_text
|
77
77
|
return %{<a href="#{href}#{fragment}">#{link_text}</a>}
|
78
78
|
else
|
@@ -85,19 +85,19 @@ class Hoe::ManualGen::LinksFilter < Hoe::ManualGen::PageFilter
|
|
85
85
|
return %{<a href="#" title="#{error_message}" class="broken-link">#{link_text}</a>}
|
86
86
|
end
|
87
87
|
end
|
88
|
-
|
89
|
-
|
88
|
+
|
89
|
+
|
90
90
|
### Lookup a page +reference+ in the catalog. +reference+ can be either a
|
91
91
|
### path to the .page file, relative to the manual root path, or a page title.
|
92
92
|
### Returns a matching Page object, or nil if no match is found.
|
93
93
|
def find_linked_page( current_page, reference )
|
94
|
-
|
94
|
+
|
95
95
|
catalog = current_page.catalog
|
96
|
-
|
96
|
+
|
97
97
|
# Lookup by page path
|
98
98
|
if reference =~ /\.page$/
|
99
99
|
return catalog.uri_index[ reference ]
|
100
|
-
|
100
|
+
|
101
101
|
# Lookup by page title
|
102
102
|
else
|
103
103
|
return catalog.title_index[ reference ]
|