DevHeads.net

Re: [RDoc internals] Changing the RDoc formatter

On Jul 20, 2011, at 8:44 AM, Quintus wrote:
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.

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.

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.

Comments

Re: Changing the RDoc formatter

By =?utf-8?Q?Marvi... at 07/22/2011 - 09:57

(Sorry for the late response, been busy last days)

Thanks for all the explanations, I'm going to dig into them in the next
few days.

Am 21.07.2011 02:18, schrieb Eric Hodel:
A word about what a formatter’s and what a generator’s purpose is would
be nice. At least one person wasn't able to grep the difference solely
from the documentation and had to ask here at the list^^. Thanks again
for your explanations.
Maybe a kind of flow chart how RDoc processes things and invokes
parsers/generators/formatters? Just an idea, I always think flow charts
are the easiest way to understand how a process works [but don't try
them with my RDoc-LaTeX-PDF code, it doesn't handle images yet^^).

I just uploaded it to GitHub, you can find it at:

<a href="https://github.com/Quintus/rdoc_pdf-latex" title="https://github.com/Quintus/rdoc_pdf-latex">https://github.com/Quintus/rdoc_pdf-latex</a>

And if you know a way to define new LaTeX headings I'd be *very*
thankful, because the current way I do it a) doesn't work properly and
b) looks absolutely horrible (see data/main.tex.erb file).

Vale,
Marvin

Re: Changing the RDoc formatter

By Eric Hodel at 07/22/2011 - 11:14

On Jul 22, 2011, at 7:57 AM, Quintus wrote:
I think I can add additional descriptions to RDoc::Markup::Formatter and RDoc::Generator as well as a "how rdoc generates stuff" somewhere else.

I don't know much about LaTeX, but I'll poke at it, maybe this weekend.