Re: [Tcllib-devel] missing man pages on tcllib.sf.net/doc?

[Joe E. <jen...@fl...>]

Andreas Kupries wrote:

> [I wrote]
> > Keeping the table of contents up-to-date still takes rather more
> > manual work than I'd like.  Andreas -- does the tcllib Swiss Army Knife
> > tool have a better solution?
> 
> Currently not, I think. How are you generating the TOC again ?
>
> We are speaking about http://tcllib.sourceforge.net/doc/, right ?
>
> Where the various packages/modules are sorted into various
> categories ?

It's maintained by hand as a TMML master document.
 
> If so, we could maybe put the category information into the manpages, as
> proper markup using a new 'category' command, or as temp. hack using
> 'comment' with special contents.

In my experience, this usually isn't the best way to go --
it's easier to maintain the TOC if the overall structure
is stored in a single file.  (For example: splitting up
subsections when they get too big, making sure that "intro" 
manpages appear first in each subsection, that sort of thing.)

The main drawback is that when new manpages appear, someone
has to determine where they fit in the TOC by hand.  I was
hoping that you were already maintaining this as a doctools::toc
document.


> The latter is however not something I want
> to do. Whatver way we go, at the end we can pull the information directly
> out of the manpages, or the TMML conversion (I seem to remember that you go
> TMML first before going to HTML). Documentation with the information goes to
> 'Unfiled' or other category of similar meaning. Then we only have to update
> all existing manpages with the current categories to recreate the current
> result, and new pages are incrementally assigned a category when created ...

That approach works well for keyword-based indexes like [1] and [2],
but not as well for the table of contents, since in the TOC order
and grouping is more important.

[1] <URL: http://tmml.sourceforge.net/doc/tcllib/keyword-index.html >
[2] <URL: http://tmml.sourceforge.net/doc/tcllib/category-index.html >

--JE