On Jul 20, 2011, at 8:44 AM, Quintus wrote:
==================================================
endThis allows me in my LaTeX ERB templates to just call the
#latex_description method of a CodeObject (instead of #description,
which seems to default always to the ToHtmlCrossref formatter) to get
the fully formatted comment. Do I really have to do this monkeypatch?
Isn’t there another way, like, say, setting the wanted formatter on an
instance of the generator class (in my case RDoc::Generator::PDF_LaTeX)?
In RDoc this happens using rdoc/generator/markup.rb
(The code is in a separate module to allow smaller parts of RDoc to be
loaded depending upon what you’re doing. For example ri shouldn’t
need to load all the generators and markup parsers).
I think it’s just fine to create a separate module for Latex formatting
and cross-referencing and including it in the same places that
RDoc::Generator::Markup is used.
I would do it this way:
require ‘rdoc/generator/markup’
module RDoc::Generator::LatexMarkup
def formatter
# make latex formatter like RDoc::Generator::Markup#formatter
end
end
class RDoc::CodeObject
include RDoc::Generator::LatexMarkup
end
class RDoc::Context::Section
include RDoc::Generator::LatexMarkup
end
While this allows only HTML or only LaTeX output per run of RDoc I don’t
think that’s much of a problem.
I should be able to allow RDoc to support a preferred formatter per
generator in a future release. Cross-reference formatters require a
context object so I’m not sure what the API will look like.
And btw, why do we need a separate Generator and Formatter class? Nearly
the whole work of processing the parsed input is done in the formatter,
the generator then just writes it out to a file or whereever. Is this
really the sole purpose of a generator?
A Generator turns an RDoc::CodeObject tree into some kind of output.
That output may be a set of HTML files, an ri data store, a PDF or
records in a database.
A Formatter turns a parsed block of text into another form of output.
In the case of ri, RDoc::Generator::RI turns the RDoc::CodeObject tree
into a set of Marshal files and a cache file describing the data.
When ri runs it examines the cache file, loads the correct data files,
extracts the comment and uses the appropriate RDoc::Markup::Formatter to
display the pre-parsed data.
(There’s also rdoc --pipe which uses the HTML formatter.)
Since formatters get used in various different places they need to be
separate from the generators.
If so, why is there a such small amount of documentation of adding new
subclasses of RDoc::Markup::Formatter?
I haven’t had time to write it and few people have expressed interest in
needing it. I’m also not sure what I should write about it. Using the
visitor pattern makes the formatters rather simple to write.
Please take a look at RDoc::Markup::FormatterTestCase. Subclassing it
should help you immensely as it provides tests for everything you need
to implement. (There’s also RDoc::markup::TextFormatterTestCase)
If I had an idea of what things you wish you’d know I can use that to
write documentation.
Also, where is your project hosted? I’d like to take a look at it.