Rdtool and rdoc

I took a look at your comparison page. I’ve not used either, but some things stood out to me…

What stands out to me is that the RDTool result is simple, single-paged, and presumably easy to print or to convert to other forms via printing. It also is likely to be easy to read in lynx and other similar browsers (including speech-enabled browsers for the blind).

The RDoc result is heavily frames-based and seems specifically designed for Web-access. It’s cute and quite usable in the Web context, but likely not as easily accessible outside of the Web.

For me, seems like RDTool is more generally usable. Also, programmers SHOULD write documentation - and keep it up to date.

Is it possible to have both available and/or to use both at the same time? Do they interact well or badly?

Dave@PragmaticProgrammer.com 7/22/02 10:28AM >>>
Minero Aoki aamine@mx.edit.ne.jp writes:

In this thread, Nobuyoshi Nakada has noted that he had imported
OptionParser (optparse.rb) to the CVS repository. This is the
preparation to bundle RDtool into the standard package.

At this risk of sounding biased… :slight_smile:

I’m wondering if any consideration was given to including RDoc in the
base distribution?

I think RDTool is a wonderful utility for creating general purpose
documentation: if I were writing a manual I’d seriously consider using
it. However, I personally find it quite cumbersome when using it to
document source files: the documentation breaks up the source, and the
documentation writer is forced to repeat much of the information that’s
in the source itself. That’s why I wrote RDoc. Because it understands
the syntax of the languages it’s documenting (Ruby, C extensions, and
Fortran currently) , it can produce meaningful output even if the
input file contains no documentation whatsoever. If also has output
options that are useful when working with source code (such as the
pseudo file/module/method browser bar for quick navigation, automatic
hyperlinks, and pop-up source code for method (just click on the
method name).

I’ve put up a small compare-and-contrast page at

http://rdoc.sourceforge.net/rd/

So… A suggestion. I’d like to propose RDoc as the tool used to
document Ruby libraries and the Ruby interpreter itself. We could use
the text from the PickAxe for the interpreter documentation and for
many of the libraries, and the others could be added as we go along.

For this to be useful, we’d need to bundle RDoc with Ruby.

Cheers

Dave

No, programmers SHOULD write programs, by the very definition of the
word “programmer” being “one who programs.”

I vote for RDoc, completely. However, I do agree with you completely
that the frames nonsense needs to go away, or be an option that has to
be turned on. Frames was probably the worst decision the W3C could
have ever made to allow into the specification.

I like RDoc because I can, without any extra work on my part, point
it at my source and have it generate documentation.

If the code isn’t written well, the RDoc will not be very sensible
or useful: that’s a smell that my code stinks, not that I should be
annotating it with inline RDoc comments.

Good class name choices, logical object hierarchy, appropriate method
names and methods that do one thing well (and expose what that “one
thing” is by its method name) are all good goals for code writing.
Code written this way, when passed through RDoc, shouldn’t need much
documentation outside of the code itself.

– Dossy

···

On 2002.07.23, David Douthitt DDouthitt@cuna.coop wrote:

Also, programmers SHOULD write documentation - and keep it up to date.


Dossy Shiobara mail: dossy@panoptic.com
Panoptic Computer Network web: http://www.panoptic.com/
“He realized the fastest way to change is to laugh at your own
folly – then you can let go and quickly move on.” (p. 70)

Hi –

···

On Tue, 23 Jul 2002, David Douthitt wrote:

I took a look at your comparison page. I’ve not used either, but
some things stood out to me…

What stands out to me is that the RDTool result is simple,
single-paged, and presumably easy to print or to convert to other
forms via printing. It also is likely to be easy to read in lynx
and other similar browsers (including speech-enabled browsers for
the blind).

The RDoc result is heavily frames-based and seems specifically
designed for Web-access. It’s cute and quite usable in the Web
context, but likely not as easily accessible outside of the Web.

For me, seems like RDTool is more generally usable. Also,
programmers SHOULD write documentation - and keep it up to date.

RDoc is pluggable; there are different backends, and more can be
written. In particular, there’s an XML backend, which can be
post-processed to just about anything. (For example, I’ve written a
suite of XSL-FO stylesheets for it – see contrib/xslfo in the RDoc
distribution.)

David


David Alan Black
home: dblack@candle.superlink.net
work: blackdav@shu.edu
Web: http://pirate.shu.edu/~blackdav

If I remember correctly, RDoc is designed around plugins, so what
you’re seeing is the way RDoc outputs currently, not the only way it
ever will.

(Anyway it looks fine in links.)

Massimiliano

···

On Tue, Jul 23, 2002 at 04:19:06AM +0900, David Douthitt wrote:

The RDoc result is heavily frames-based and seems specifically
designed for Web-access. It’s cute and quite usable in the Web
context, but likely not as easily accessible outside of the Web.

“David Douthitt” DDouthitt@cuna.coop writes:

The RDoc result is heavily frames-based and seems specifically
designed for Web-access. It’s cute and quite usable in the Web
context, but likely not as easily accessible outside of the Web.

That’s just the default. RDoc also generates Windows .chm files
(actually quite nice) and can generate linear xml and rdf. Given the
XML you could XSLT up any style output you wanted. David Black has
also contributed some xslfo stuff that generates decent printed
output.

Cheers

Dave

RDtool doco is a pain to maintain and keep up to date, and it doesn’t
"fit" with the language that surrounds it.

I would always vote for RDoc here - it’s effortless to use, and easy to
maintain. (http://linuxbrit.co.uk/rbot/doc/ -> better API documentation
than I’ve ever produced before)

However, there are some issues that need to be fixed. Frames are horrid,
and RDoc shouldn’t produce them. And rdoc needs to have a commandline
interface so it’s not quite so HTTP biased. I need to be able to query
api documentation from the commandline -> man/perldoc style output would
be a great feature.

Tom.

···

I took a look at your comparison page. I’ve not used either, but some things stood out to me…

What stands out to me is that the RDTool result is simple, single-paged, and presumably easy to print or to convert to other forms via printing. It also is likely to be easy to read in lynx and other similar browsers (including speech-enabled browsers for the blind).

The RDoc result is heavily frames-based and seems specifically designed for Web-access. It’s cute and quite usable in the Web context, but likely not as easily accessible outside of the Web.

For me, seems like RDTool is more generally usable. Also, programmers SHOULD write documentation - and keep it up to date.


.^. .-------------------------------------------------------.
/V\ | Tom Gilbert, London, England | http://linuxbrit.co.uk |
/( )\ | Open Source/UNIX consultant | tom@linuxbrit.co.uk |
^^-^^ `-------------------------------------------------------’

David Douthitt wrote:

I took a look at your comparison page. I’ve not used either, but some
things stood out to me…

What stands out to me is that the RDTool result is simple,
single-paged, and presumably easy to print or to convert to other
forms via printing. It also is likely to be easy to read in lynx and
other similar browsers (including speech-enabled browsers for the blind).

The RDoc result is heavily frames-based and seems specifically
designed for Web-access. It’s cute and quite usable in the Web
context, but likely not as easily accessible outside of the Web.

For me, seems like RDTool is more generally usable. Also, programmers
SHOULD write documentation - and keep it up to date.

Is it possible to have both available and/or to use both at the same
time? Do they interact well or badly?

Dave@PragmaticProgrammer.com 7/22/02 10:28AM >>>
Minero Aoki aamine@mx.edit.ne.jp writes:

In this thread, Nobuyoshi Nakada has noted that he had imported
OptionParser (optparse.rb) to the CVS repository. This is the
preparation to bundle RDtool into the standard package.

At this risk of sounding biased… :slight_smile:

I’m wondering if any consideration was given to including RDoc in the
base distribution?

I think RDTool is a wonderful utility for creating general purpose
documentation: if I were writing a manual I’d seriously consider using
it. However, I personally find it quite cumbersome when using it to
document source files: the documentation breaks up the source, and the
documentation writer is forced to repeat much of the information that’s
in the source itself. That’s why I wrote RDoc. Because it understands
the syntax of the languages it’s documenting (Ruby, C extensions, and
Fortran currently) , it can produce meaningful output even if the
input file contains no documentation whatsoever. If also has output
options that are useful when working with source code (such as the
pseudo file/module/method browser bar for quick navigation, automatic
hyperlinks, and pop-up source code for method (just click on the
method name).

I’ve put up a small compare-and-contrast page at

http://rdoc.sourceforge.net/rd/

So… A suggestion. I’d like to propose RDoc as the tool used to
document Ruby libraries and the Ruby interpreter itself. We could use
the text from the PickAxe for the interpreter documentation and for
many of the libraries, and the others could be added as we go along.

For this to be useful, we’d need to bundle RDoc with Ruby.

Cheers

Dave

Frames is a bad way to go if you intend to print it, but if you intend
to print it you really need page numbers, and many other features that
are missing. Like tables of contents and indexes.

The use of the frames is bad for a large collection of code from many
classes. This is because the methods aren’t filtered by the current
class, and because constants don’t seem to appear anywhere (and a few
other small factors). This is one place where Smalltalk got it right.
Look at the Squeak class browser to see how it should be done! (Well,
at least the version they were using a few months ago.) Nothing wrong
with frames at all, you just need to do things slightly differently.
(And need a bit more computation under the hood.) Actually, from the
look of things, the Smalltalk class browser has already been an
inspiration for rdoc, they just didn’t follow it far enough yet.

···


– Charles Hixson
Gnu software that is free,
The best is yet to be.

Dave Thomas wrote:

David Black has also contributed some xslfo stuff that
generates decent printed output.

David, where do I find out how to do this? I.e., is there
a tutorial, an example, or readme somewhere which would
take me through the steps from code to printed matter?

XML/XSLT challenged,

···


Bil

Hi –

···

On Wed, 24 Jul 2002, Charles Hixson wrote:

Frames is a bad way to go if you intend to print it, but if you intend
to print it you really need page numbers, and many other features that
are missing. Like tables of contents and indexes.

I just want to re-emphasize that RDoc is pluggable. Not that that
means we shouldn’t discuss the pros and cons of how it’s currently
shipped – but there’s nothing missing that can’t be added.

Hmmm… anyone want to participate in an RDoc extension codefest at the
conference?

David


David Alan Black
home: dblack@candle.superlink.net
work: blackdav@shu.edu
Web: http://pirate.shu.edu/~blackdav

Charles Hixson charleshixsn@earthlink.net writes:

The use of the frames is bad for a large collection of code from
many classes. This is because the methods aren’t filtered by the
current class, and because constants don’t seem to appear anywhere
(and a few other small factors). This is one place where Smalltalk
got it right. Look at the Squeak class browser to see how it should
be done! (Well, at least the version they were using a few months
ago.) Nothing wrong with frames at all, you just need to do things
slightly differently. (And need a bit more computation under the
hood.) Actually, from the look of things, the Smalltalk class browser
has already been an inspiration for rdoc, they just didn’t follow it
far enough yet.

Some things (such as comments) are on the ToDo list. Having the method
lst change when you click on classes is hard to do in HTML (or at
least it was the last time I looked at it).

I’d certainly welcome any code contributions you’d care to make.

Cheers

Dave

I took a look at your comparison page. I’ve not used either, but some things stood out to me…

What stands out to me is that the RDTool result is simple,
single-paged, and presumably easy to print or to convert to other
forms via printing. It also is likely to be easy to read in lynx
and other similar browsers (including speech-enabled browsers for
the blind).

The RDoc result is heavily frames-based and seems specifically
designed for Web-access. It’s cute and quite usable in the Web
context, but likely not as easily accessible outside of the Web.

For me, seems like RDTool is more generally usable. Also,
programmers SHOULD write documentation - and keep it up to date.

RDtool doco is a pain to maintain and keep up to date, and it doesn’t
"fit" with the language that surrounds it.

Agreed.

I would always vote for RDoc here - it’s effortless to use, and easy to
maintain. (http://linuxbrit.co.uk/rbot/doc/ -> better API documentation
than I’ve ever produced before)

I’d like to chip in and mention my support for RDoc as well (and not
just because Dave used my Imlib2 bindings as an example ;)).

However, there are some issues that need to be fixed. Frames are horrid,
and RDoc shouldn’t produce them. And rdoc needs to have a commandline
interface so it’s not quite so HTTP biased. I need to be able to query
api documentation from the commandline -> man/perldoc style output would
be a great feature.

I’m not sure about the stable version, but the CVS version of RDoc does
have a command-line interface (ie, you can output to HTML, XML, and
Windows help files). I have no idea if the XML and Windows help
templates work properly, though.

What would be really nice is if ri could do arbitrary API queries,
instead of having hard-coded documentation for the built-in classes,
and if RDoc had an output template for said format. Because then
you’d have the command-line documentation interface in addition to a
web-based interface, and said documentation would be easily accessible
from the existing ri wrapper interfaces (eg, the emacs, irb, and vim ri
wrappers).

My biggest problems with RDoc at the moment would have to be (ironically)
a lack of documentation for the templates, and less than
spectacular C prototype handling (I’d like an override to explicitly
specify static and variadic method prototypes in the comments, javadoc
or gtk-doc-style). I’ve talked to Dave on IRC about the latter; I have
no idea if it’s available in RDoc yet (a brief glance over the CVS RDoc
says no).

I agree with Tom about the frames in the default HTML template. I
realize that RDoc is already template-based, and that the XSL-FO in
contrib can generate a number of output formats, but it would be nice
if those output options were more conveniently available from the
RDoc command-line and Ruby interfaces.

That said, I still prefer RDoc over any other documentation generators
I’ve used.

Tom.

.^. .-------------------------------------------------------.
/V\ | Tom Gilbert, London, England | http://linuxbrit.co.uk |
/( )\ | Open Source/UNIX consultant | tom@linuxbrit.co.uk |
^^-^^ `-------------------------------------------------------’

Damn your penguin! :slight_smile:

···


Paul Duncan pabs@pablotron.org pabs in #gah (OPN IRC)
http://www.pablotron.org/ OpenPGP Key ID: 0x82C29562

Hi –

Dave Thomas wrote:

David Black has also contributed some xslfo stuff that
generates decent printed output.

David, where do I find out how to do this? I.e., is there
a tutorial, an example, or readme somewhere which would
take me through the steps from code to printed matter?

There’s a README in the contrib/xslfo directory, and also there’s a
demo subdir. There’s a script in the demo dir that semi-automates the
process.

You need an XSLT processor, which basically takes the XML file
(generated by RDoc) and the stylesheets I written, and spits out an
XSL-FO document. This document is a thick description of a visual
presentation of the information, including internal and external
hyperlinks.

Then, to do anything with this, you need another software layer. I’ve
been using PassiveTeX, which takes XSL-FO as input and produces a DVI
file as output. I’ve also been running it through pdflatex, which
produces a PDF file (with working links). But you can use anything
that reads XSL-FO and outputs something else.

If all of this is too cryptic or uphill, let me know and I’ll see if I
can flesh it out.

David

···

On Tue, 23 Jul 2002, Bil Kleb wrote:


David Alan Black
home: dblack@candle.superlink.net
work: blackdav@shu.edu
Web: http://pirate.shu.edu/~blackdav

Dave Thomas wrote:

Having the method
lst change when you click on classes is hard to do in HTML (or at
least it was the last time I looked at it).

I wrote a ruby program which generates such a set of pages
to browse (not search) a database.
(Corresponding to various views (“catalogues”) of a library)

It uses three frames. Target for frame1 is frame2,
target for frame2 is frame3.
So clicking on a man topic in frame1 shows a subset of
related index entries in frame2;
and clicking on an entry in frame2 shows the data in frame3.

Using JavaScript we could even update two frames simultaneously,
but this was not required for this purpose.
Sorry, this URL is not (yet) in the public internet.

kind regards,
Norbert

Paul Duncan wrote:

I agree with Tom about the frames in the default HTML template. I
realize that RDoc is already template-based, and that the XSL-FO in
contrib can generate a number of output formats,

XSLFO is an output format. XSLT is the one that can be used to
transform XML into various formats.

Tobi

···


http://www.pinkjuice.com/

Paul Duncan wrote:

I agree with Tom about the frames in the default HTML template. I
realize that RDoc is already template-based, and that the XSL-FO in
contrib can generate a number of output formats,

XSLFO is an output format. XSLT is the one that can be used to
transform XML into various formats.

I’m aware of that. What I was trying to say is that I wish the output
formats available via the XSLFO transform in contrib/ were directly
accessible from the RDoc command line interface (eg. "rdoc --fmt pdf"
instead of “rdoc --fmt xml foo.xml && xsltproc …”).

···

Tobi


http://www.pinkjuice.com/


Paul Duncan pabs@pablotron.org pabs in #gah (OPN IRC)
http://www.pablotron.org/ OpenPGP Key ID: 0x82C29562

Paul Duncan pabs@pablotron.org writes:

I’m aware of that. What I was trying to say is that I wish the output
formats available via the XSLFO transform in contrib/ were directly
accessible from the RDoc command line interface (eg. "rdoc --fmt pdf"
instead of “rdoc --fmt xml foo.xml && xsltproc …”).

To do that I’d have to know all about your XML/XSLT/LaTeX (or whatever)
environment, which I’d rather not build in.

However, perhaps the good Dr Black might be persuaded to produce an
installation tool for his xslfo stuff that did work all this out
and which then generated a shell script/batch file so you could type

rdoc2pdf

Cheers

Dave