Hello.
Some two weeks ago, I told Bradley Kuhn that I preprocess my own
texinfo documentation to extract manual pages. He told me that it
sounds great, and suggested to write to this address and tell what I did.
Actually, the best way to look at what I did is checking the
documentation of my programs: either GNU barcode (on the GNU sites) or
gpm (metalab and mirrors, under system/mouse) or my silly drivers
(ftp.linux.it/pub/People/rubini). In practice I use an awk script,
called manpager, which does simple parsing and skipping of my source
in order to produce more-or-less-correct nroff input files. The same
source is preprocessed by another simple filter to get plain-texinfo
used to generate the other output formats.
Disclaimer: Please note that my docs are pretty poor, as I
began writing in texinfo a lot of time ago, when there were no
nice features like support for illustrations or html
generation (or plain-text generation). Since I never upgraded
my texinfo experience my docs are still old-fashioned and
somehow hacked together, if compared to what newer versions of
texinfo offer.
The main problem I see with manual pages is that their structure is
clearly different from an info (or printed or html)
document. Therefore the structuring of man pages must be completely
separate from the structuring of the texinfo source. What is usually
needed is making several man pages, some of them may span several
chapters of the input file and other may only cover a subsection of
the input file.
Therefore manpage structuring must be somehow separate from the normal
texinfo structuring: ``@manpage program.1'' and ``@end manpage'' don't
fit the target, in my opinion. On the other hand, if the keywords
stand out of other keywords well enough, I think two orthogonal
structures can coexist on the same file. For example, the source files
of my documentation are pretty easily managed despite the double
structuring (I use ``%M'' to mark manpage meta-information, and ``%''
at large is my comment marker as I find it more visible than ``@c'').
Unfotunately I see that inclusion of manpage support is a
non-negligible task, requiring a new back-end to spit out troff
source. While I'd like to help in this project I don't think I have
enough experience in texinfo internals nor available time to try to
accomplish this.
Thanks for reading that far
/alessandro
