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