Re: man pages and GNOME docs

[Toshio Kuratomi <badger prtr-13 ucsc edu>]

On Wed, 11 Feb, 1998 at 02:06:00PM -0700, Mark Galassi set free these words:
> 
> But we can probably do better than the GNU standards recommend:
> DocBook allows man page information to be embedded in your DocBook
> document (via the <refentry> tag), and we should use that mechanism.
> You can then process the DocBook file and get a man page source as
> output!
> 

I have gotten to the place where I want to add a man page to my documentation
(Well, a man page stub to show myself how it works.)  I've put the page in,
but I now have three questions:
    1) How do I extract it to man page format?
    2) It looks awfully lonesome sitting there in my html output all by
itself.  How do you recomend placing it/introducing it/etc so that it isn't
out of place next to the rest of the html documentation?
    3) Related to two, can I avoid maintaining the information in the refentry
seperately from the rest of the document (If there's not a way to nicely
include it?)  Everything's in the same file with docbook, but I could very
well end up keeping duplicate information in two seperate places within that
file....

I also have one suggestion:
    I'd like to see the man page contain information that I may want without
having to run the program.  So invocation information (Synopsis, options.),
and "ENV variables", if applicable, are prime candidates.  Depending on your
feelings at the time, "See Also", "Files", "Author", "Bugs", etc could be
helpful for setting up config files, sending bug reports, etc.

It may be possible to go overboard with this.... How to deal with that?

There should also be something that tells me to look in online help for more
information.  (Maybe at the top of the Description since that's where GNU puts
their little warning.)

-Toshio
-- 
badger  \"The Difference between today and yesterday is not so much what has
@prtr-13 \ changed between then and now as what I hope to change by tomorrow."
.ucsc.edu  \~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~

PGP signature