From: bbense+comp.lang.ruby.Sep.07.02@... Date: 2002-09-08T00:21:58+09:00 Subject: Re: Document tools -----BEGIN PGP SIGNED MESSAGE----- In article <1031334976.12271.675.camel@starcrusher>, W Kent Starr wrote: >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. - - 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-----