[groff] groff as the basis for comprehensive documentation?

[Nate Bargmann]

I have long been involved with a project that has lacked good
documentation for nearly all of its existence.  We've had documentation,
but it isn't in a good format for generating man, HTML, or PDF versions.

Long ago I started with Docbook and then that got to a point no one else
would touch it and I didn't want to either.  XML was the "wave of the
future" but I didn't jump on that wagon.  The project has long had the
capability of using Doxygen and I find its output wanting and never
warmed up to it as even with it, other man pages needed to be maintained
and its man output is horrid.  Some years ago I moved over to Texinfo
and while we get nice info, HTML, and possibly PDF files from the
document source, there are no man pages and I don't wish to maintain two
sets of documentation, which is the same road I found myself on with
Docbook.

After letting this sit for some time, I realized that I had not
investigated groff deeply and now having made myself more familiar with
it and its macro packages, I still have some questions.  Despite all the
offered solutions, I still find "man xxxx" to be the fastest and easiest
way to look at reference material.  The groff tools to render individual
pages into HTML and PDF do a very nice job.  Thank you.

But (there is always a 'but'), beyond the collection of nroff files I am
creating for the man pages, it would be nice to be able to tie them all
together into a whole.  Or, rather a master document, likely in man7,
that when rendered as HTML has links to the reference pages also
rendered as HTML.  When rendered as PDF, the reference pages rendered as
PDF could be collated into a single PDF document.

I was hoping the mom macro package might have some sort of a facility
for this idea, but its inclusion only seems to be other mom formatted
files.  In fact, it seems as though all of the macro packages are
mutually exclusive.  Perhaps I have not looked deeply enough.

Regardless, I plan to continue with improving our project's collection
of man pages and work from there and will likely remove the Texinfo
files at some point.

Thanks,

- Nate

-- 

"The optimist proclaims that we live in the best of all
possible worlds.  The pessimist fears this is true."

Web: http://www.n0nb.us  GPG key: D55A8819  GitHub: N0NB

signature.asc
Description: PGP signature