Is it a good idea to write your software manual pages (manpages) / reference manuals using TeX? I'm new to TeX and exploring my options around this.
I'd be able to deliver a manpage.pdf along with the sources, but I'd also like to put them online. Not only in PDF format, but also as HTML or within a MediaWiki. Is this possible? And how?
What would be a good template / example to start with? Any .sty file to add manpage functionality?
Thank you
I'm not sure how one would write a man page in TeX. If you open one up in an editor, you can see that they're written in *roff.
For reference manuals, see the answers to this question.
There are several ways one can produce html files from a TeX file. Some information is given in this question.
I've never heard of producing MediaWiki's markup from LaTeX.
pod2man.
Feb 6, 2011 at 7:55
For software documentation, there is the texinfo system which is primarily used in the GNU project, and allows output in various formats like PDF, HTML, info, DocBook and other XML formats. The PDF output is produced by TeX, but the syntax of a texinfo source is not the usual LaTeX/Plain TeX syntax (for example, commands start with @, not \). It doesn't feature man as an output format, however (I'm not sure if your question is about the man format itself or about documentation formats in general.)
texinfo.tex is, however, based on plain TeX -- it just reassigns the catcodes near the end, and then does some trickery to arrange for any \input texinfo that may occur at the top of the file to be skipped over in the event that texinfo.tex was preloaded into a format file (while also allowing for the possibility that the file might not start with \input texinfo). It's a pretty nice format file to look at, I think: you don't have dozens of different packages, half of which have to patch over things that other packages didn't do quite right, like you do in LaTeX :-).
manmac, but on the plus side it supports PDF, and you can get your table of contents autogenerated at the beginning of the PDF, and of course manmac can only do typeset output. (The reason I say it's not extensible is that makeinfo, which generates the non-typeset output formats, is written in C, so about the only aspect of Texinfo that makes sense to change is the typesetting; also, any attempt to patch it by redefining commands would be likely to break for people with a different version of texinfo.tex than you.)
Maybe not quite what you're looking for, but Sphinx is good for documentation. Once you have documentation written using Sphinx, you can easily produce html, LaTeX, and PDF. Python documentation is written using Sphinx, and I know about Sphinx from working on Sage, but the Sphinx web page provides links to many projects which use it for their documentation. It is possible to use LaTeX math commands within Sphinx, essentially verbatim; the resulting PDF is produced from LaTeX, and so it looks good, as you can imagine. The resulting html looks best if you use it in combination with jsMath, and I expect Sphinx to support MathJax eventually.
There are actually at least two *roff macro packages to choose from for writing manpages: man(7) and mdoc(7). The former is suggested for new pages to be added to the Linux man-pages package; the latter is very strongly urged for *BSD manpages. (Therefore, the manpage links for each macro package above go to the manpage provided by the group that advocates its use.)
I'd recommend using pandoc, you can either use it to convert LaTeX (at least simple LaTeX) to HTML, man pages, media wiki, and several other formats. Or you can use extended markdown too, and convert it to almost anything.
If you want single source, multi-output publishing (to HTML, PDF, etc) then you can't really beat the XML + XSL + FOP tool chain. Docbook is probably what you're looking for if you want to write technical information in XML. XMLMind has a free personal edition that works pretty well. As much as I like latex, any complex document is going to be too much for something like Tex4ht to handle well (or at least this has been my experience).
