Re: Document tools

-----BEGIN PGP SIGNED MESSAGE-----

In article <1031334976.12271.675.camel@starcrusher>,
W Kent Starr  <[e-mail]> wrote:
>On Fri, 2002-09-06 at 11:31,
>[e-mail] 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.

- - It certainly is possible. POD shows us the way. I think the
  point I'm trying to make is that POD is an output format.
  It just happens to be so trivial that it's accepted in the
  perl community to write raw POD. Once you have a well defined
  simple output format, you can translate that to any other format 
  required. 

  I think we all want to get to the point where when you install
  ruby you can type 

       make install-man

  or 

       make install-html

  or even

       make install-winhelp

- - If you pick a relatively neutral format that everybody uses
  it's pretty straightforward to get to this goal. In the ruby
  community we have this really great tool for helping us write
  our version of POD, RDoc. To me the question is whether we
  choose rd or XML as the "intermediate" output format. 

>
>> 
>>   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.
>

- - CPAN is not a document archive, it's a source archive. It just
  happens that the most common place to find perl documentation 
  is imbedded in the src. 

>
>> 
>> - - rdoc does not solve either of these problems. POD solves them
>>   by 
>> 
>>   a. being trivial
>
>Meaning the inline docs are easy to write?

- - Write, read, slice and dice into your favorite output format. 
  We have a big advantage in that we have this really nifty tool
  to help us already in writing inline docs.  

>
>> 
>>   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.
> 

- - Well, the only reason that 99% of perl modules have
  documentation is that the easiest way to get started
  writing a module is to run a program that sets up the
  structure for you. One of the things this program does
  is write a dummy doc skeleton with embarassing comments
  like

  "Stub documentation for Foo, created by h2xs. It looks like the
   author of the extension was negligent enough to leave the stub
   unedited. "

   Perhaps we should add this feature to rpkg. 

>> 
>>   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.

- - It's an advantage if we use it properly. I agree that it's a
  great tool, there's nothing even close in the perl world. 

>
>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" :-)
> 

- - That's an extension of my idea. Rdoc next to the methods with 
a post processing step of putting rd between the =begin =end
tags. 

>> 
>>   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.

- - Well, my take is that rd is an output format and RDoc is an
  input one. 

[snip]
> 
>> 
>> - - 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 :-)

- - Certainly, that's an alternative. It wouldn't be my first choice.

> 
>> - - 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? :-)

- - I was using grep in the "generic" sense, but if people think
  XML on the fly is adequate, then I see at least one big
  problem. Rightly or Wrongly, the file name of a ruby module
  has no relation to the classes included. Perl ( and I think
  Java ) have "solved" this problem by using the convention 
  that filenames and modulenames must be in sync[1]. This makes
  finding the embedded documentation much simpler. In the 
  current ruby world you would need to run rdoc on every
  installed library to find the answer to "any" question. 
  rdoc is fast, but I don't think it's that fast. Perhaps,
  the solution is to big a global index for classnames/methods,
  XML is probably the correct solution there. 

- - Booker C. Bense 

[1]- Well, at least all the classes in a module should be
subclasses of the main module name. 
 



-----BEGIN PGP SIGNATURE-----
Version: 2.6.2

iQCVAwUBPXoUqGTWTAjn5N/lAQHHuAQAnhcReTnyBjDjxtQ5yvZMf8fYaEnDC1SD
1KSMt8YSKRGVypwd+HiJR1oLu0Mk7Hv9ExFhAzObJvjQQ/jRERBlO65FD8982IIO
ovaLgUBFPfO4jx3IsaXD3yn9m+QFfvkHhXOI4r+pvMrzDgjd/QHYs4bUeIb6zjTZ
1VirRfZNBag=
=7ye8
-----END PGP SIGNATURE-----