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/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
- $stderr.puts "This Rakefile requires Hoe (gem install hoe)"
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.md'
21
- self.history_file = 'History.md'
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.extra_deps.push *{
26
- 'hoe' => "~> #{Hoe::VERSION[/^\d+\.\d+/]}",
27
- 'RedCloth' => '~> 4.2',
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.spec_extras[:licenses] = ["BSD"]
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
- begin
66
- require 'pathname'
67
- require 'strscan'
68
- require 'yaml'
69
- require 'rcodetools/xmpfilter'
70
- require 'digest/md5'
71
- require 'tmpdir'
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
- [content, caption || '']
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 ]