On 3 December 2016 at 23:25, James Youngman <j...@gnu.org> wrote: > I maintain a substantial Texinfo manual and, in parallel, a substantial roff > manual page. > > The documentation of the command-line options is lengthy and maintaining > this in two places is burdensome. I don't want to abandon either > documentation type (as an output at least) but I'd prefer to reduce the > duplicate effort. > > An obvious solution to this is to keep the overall structure of the two > documents as-is, but to document the command-line options in just one place, > and perform some kind of conversion. For example I could cope with > mastering documentation about command-line options in Texinfo and generating > nroff (which I would concatenate into a manpage) or documenting the options > in nroff and using that to generate part of the reference section of my > Texinfo manual. > > Based on https://www.gnu.org/software/texinfo/ I see that there is a manpage > -> Texinfo converter, and also that there is a Texinfo->roff converter. The > latter is more appealing (since the thing I'm documenting is GNU findutils, > and GNU prefers Texinfo). However, the link is broken > (http://texinfo.org/texi2roff/ redirects to www3.texinfo.org, which domain > is apparently for sale and contains no useful content). Does anybody have > a concrete suggestion as to how to proceed?
Have you tried man2texi? (http://ftp.math.utah.edu/pub/man2texi/) I heard that there might be a new release of man2texi soon. This would require you to keep the master documentation in roff man page format, however. I've heard of a system called pandoc which supposedly can convert many different types of documentation format; I don't know if it would work for your purposes. You can generate man pages from a program's help message using the help2man program. (https://www.gnu.org/software/help2man/). This would be useful for a non-comprehensive man page. Many projects, Texinfo included, use help2man to provide man pages without the burden of maintaining them. See also the advice at https://www.gnu.org/prep/standards/html_node/Man-Pages.html#Man-Pages for GNU packages. > Is there, for example, an > nroff configuration for texi2any that wasn't mentioned? No. > Mastering in Docbook and generating both nroff and Texinfo might also be > feasible, but I'm not sure if that works well for just part of a document > (and I'm reluctant to entirely demote Texinfo to only an output format for > my documentation). > > Thanks, > James.