From: Michael Davis <mdavis@...>
Date: 2004-03-25T12:59:28+09:00
Subject: Re: RDoc and the one file option

Dave Thomas wrote:

> 
> On Mar 24, 2004, at 10:39, Michael Davis wrote:
> 
>> Hi all,
>>
>> I am attempting to run rdoc with the --one-file option and get the 
>> following error:
> 
> 
> 
> Hmm.. this has been fixed for a while now. Are you using the latest CVS 
> version of Ruby? If not, you might want to ask whoever builds your 
> release to upgrade.
> 
> (Having said that, checking out your problem revealed an issue using 
> --one-page when generating HTML from C extensions, which I've just fixed).
> 
> 
> Cheers
> 
> Dave
> 
> 
> 

It works great with the latest version of Ruby.  Thanks:)  I was working with an older snapshot.

I have to create documentation and release notes for a non-Ruby related project I am working and I would like to use RDoc for creating the documentation.  Here are a couple of things that would help me out in the short term:

- How can I specify what one_page template I want to use.  I would like to create some one pagers and would like to customize the template that gets used.  Maybe the one-file option could receive an optional parameter for the template name?

- Can I sort or not sort the list file names?  I would like to have the list of file names sorted in reverse order and/or not sorted at all so I can explicitly specify the order the files appear in.


The full blown documentation I would like to create involves the following:

- The documentation for the whole project will contain sub-directories for each sub-system. 

- Within each sub-system (sub-directory) there will be many files documenting the various aspects of each sub-system.

Here is an example (each is a directory name, sub-directory name, or file-name):

   main project name
	sub-system1
		task1.txt
		task2.txt
		task3.txt
	sub-system2
		task1.txt
		task2.txt

RDoc works great for this with one exception, navigating through the sub-systems.  Currently, all files are displayed in the files section making navigation difficult (especially where there are lots of tasks).  Is is possible to have a section, similar to the files section that would support a tree like structure allowing me to expand or contract the files for any given sub-system?  Another possibility would be a new option that supports nested directories in a tree type of format rather than showing all files at once.  

From inside a template, I can see how to alter how each filename as it is written to the html file.  What I can't seem to figure out is how alter the list of filenames just before they are processed.

I know this may seem unusual but documentation has always been one of those challenging things that I have to do for each project.  I would like to change this.  Since I love what RDoc has become, I wonder if expanding RDoc a little could make writing all sorts of documentation easier.  

Thanks, Michael