Re: [help-texinfo] Texinfo <-> roff?

[Gavin Smith]

On 3 December 2016 at 23:25, James Youngman <address@hidden> 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.