From: W Kent Starr <elderburn@...>
Date: 2002-09-07T02:55:33+09:00
Subject: Re: Document tools

On Fri, 2002-09-06 at 11:31,
bbense+comp.lang.ruby.Sep.06.02@telemark.stanford.edu wrote:

> 
> - - Well as I see it there are two things missing in the ruby doc
>   world.
> 
>   1. A standard output format

I really don't believe this is possilbe these days while keeping
everybody happy. 'Nixers' prefer man (very handy) or even
/bin/cat/foo.rb (or even /bin/cat/foo.rb | grep "def bar" to get the
args); In Windows, help files are preferred. HTML is a cross platform
compromise.

> 
>   2. A standard place to find it. 

This is a big issue in a number of ways. There is no real offline
standard location (e.g. /usr/local/lib/Ruby/1.7/docs) and while there is
much documentation online, it is all over the place and finding it can
be a real challenge. Cerainly, there is nothing on the order of CPAN. I
think this is the major point contained in stibbs original posting.


> 
> - - rdoc does not solve either of these problems. POD solves them
>   by 
> 
>   a. being trivial

Meaning the inline docs are easy to write?

> 
>   b. Always being between the =begin and =end part of the
>   installed module.

This is good for general parsing and, of course for /bin/cat, although
not necessary.

No documentation system is going to work well unless (1) creating the
docs is sufficiently easy for the programmer as to encourage (with a
little peer pressure applied) everyone to do it and (2) the issues of #2
above are effectively addressed. Both of these are organization and
social engineering concerns more than they are technical IMO.
 
> 
>   Once you have these two things, you can write all kinds of
>   document tools. In some ways rdoc is "just too damn smart",
>   it takes plain code and produces useful documentation. However,
>   since the rdoc "src" is scattered all over the original src
>   code, getting docs on the fly is somewhat difficult.

Well, actually, I see this as a definite advantage to RDoc; a file
totally devoid of any programmer-generated documentation can still be
parsed out to provide a meaningful summary of structure and the
relationships among classes, methods, etc. albeit very general and
incomplete.

An interesting thought, as an aside, would be a kind of
content-management system based on RDoc that would fold comments,
explanations, extensions, etc. back into the source, in the appropriate
places as documentation. This might make post-documentation easier for
the module writer, streamline public documentation projects on major
modules and provide a kind of notes and annotation tool for individual
users of a given module. Just a thought, but, IMO a close to "killer
app" one, or a least a "mini-killer" :-)
 
> 
>   I've taken a closer look at rd and it at least knows enough
>   Ruby to differentiate method lists from regular lists.

Originally, my personal differentiation between RD and RDoc is that the
former is preferable for end-user documentation in the form of man pages
and/or HTML for those who need to get the app up and running quickly
while the latter is better for developers and/or library modules where
the end user is a developer who needs a very thorough and in-depth
understanding of the workings, structure and interrelationships of the
code.

However, I don't see why RDoc cannot be enhanced to provide a choice of
either, depending upon one's needs, possibly through command line args?
 
> 
> - - If you want to emulate perldoc, then you could use XML as
>   and intermediate format, but IMHO, XML is unreadable and 
>   there's the question of where to put it. It also raises
>   the bar for tool writers, although I guess XML is now ubiquitous
>   enough that is not that much of an issue. 
> 
> - - I guess I'm just enough of a Unix Luddite that I think there's
>   a significant advantage to having a document format 
>   that I can use /bin/cat on. The other advantages I see are
> 
> 1. Play nice with the people already happily using rdtool.

I think RDoc already does. Is that right, Dave?
 
> 
> 2. Possible to include all the tools required to do documentation
>    in a ruby-only code with the standard distribution.

This, I think, is imperative. IIRC Matz has already agreed to include
RDoc as part of the standard distribution. 
 
> 
> - - Perhaps, we could clarify the situation with a couple use
>   cases, I'd like a tool that could answer these questions. 
> 
>        "Show me all the installed library objects that have
>        a read method."
> 
>        "Show me the names of all the installed classes." 
>

Well, if RDoc generates XML, then the result can be conditionally parsed
as required. In 'nix you would send the RDoc XML to stdout and pipe that
through your parsing tool like rdoc foo.rb | parsetool.rb -g .read - |
less or whatever. A nice GUI could be created for the Windows users :-)
 
> - - I could brute force this by running rdoc on all the installed
>   ruby src and then grepping the XML... I'd kind of like a more 
>   elegant solution. How were you planning to generalize ri from
>   rdoc output? 

Why do that when you can write a parser in Ruby, maybe using REXML? :-)
 
Regards,

Kent Starr