Re: [AL] [AD] Man pages

[ Thread Index | Date Index | More lists.liballeg.org/allegro-developers Archives ]


George Foot <george.foot@xxxxxxxxxx> writes:
> OK, I've attached `install_allegro.3'.

Ah, the joys of timeslip: I'm afraid I already went off and did this myself, 
just copying the ones for libc. I've probably misunderstood a billion things 
about the format, but my output files do seem to display correctly.

> We ought to have some form of index too. We can have a manpage `allegro.7' 
> containing the main menu to other pages like `allegro-using.7', 
> `allegro-unicode.7', etc.  These pages contain menus of other functions, 
> like `install_allegro', which all live in section 3.

I got scared at this point in writing the converter. At the moment it only 
writes out function entries. In theory it should be fairly possible to do 
the same thing for the more descriptive bits, and for the blocks of intro 
text at the beginning of each manual section, but I couldn't see an obvious 
place to take the manpage name from (current HTML titles are very long and 
contain spaces and punctuation), and I was reluctant to add yet more markup 
to the ._tx source files.

Do you actually find those large manual pages like the SVGAlib stuff to be 
useful? I love manpages for quick one-function lookups, but for larger 
things like the SVGAlib or Perl docs, I find them to be almost impossible to 
navigate around, which is why I didn't bother trying to get the larger 
sections of Allegro docs converter. But if you do actually use overview 
manpages like that, I suppose I ought to go back and try to do it more 
properly :-)

> One other thing we might like to do is remove any cached versions of our 
> pages when we install them; otherwise the changes won't be seen.

Do you need to do that? I was installing many updated versions in rapid 
succession while developing this, and it seemed to notice that: I assumed 
that the viewer was comparing timestamps on the source vs. cached version...


--
Shawn Hargreaves - shawn@xxxxxxxxxx - http://www.talula.demon.co.uk/
"A binary is barely software: it's more like hardware on a floppy disk."



Mail converted by MHonArc 2.6.19+ http://listengine.tuxfamily.org/