hoe-manualgen 0.2.0 → 0.3.0
Sign up to get free protection for your applications and to get access to all the features.
- 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 ]
|