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/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 ]