texinfo: Adding Output Formats

Overview

Texinfo Document Structure

Output Formats

Back to Software Index

1.4 Adding Output Formats
=========================

The output formats in the previous section handle a wide variety of
usage, but of course there is always room for more.

  From time to time, proposals are made to generate traditional Unix man
pages from Texinfo source.  However, because man pages have a strict
conventional format, creating a good man page requires a completely
different source than the typical Texinfo applications of writing a good
user tutorial and/or a good reference manual.  This makes generating man
pages incompatible with the Texinfo design goal of not having to
document the same information in different ways for different output
formats.  You might as well write the man page directly.

  As an alternative way to support man pages, you may find the program
'help2man' to be useful.  It generates a traditional man page from the
'--help' output of a program.  In fact, the man pages for the programs
in the Texinfo distribution are generated with this.  It is GNU software
written by Brendan O'Dea, available from
<http://www.gnu.org/software/help2man>.

  If you are a programmer and would like to contribute to the GNU
project by implementing additional output formats for Texinfo, that
would be excellent.  The way to do this that would be most useful is to
write a new back-end for 'texi2any', our reference implementation of a
Texinfo parser; it creates a tree representation of the Texinfo input
that you can use for the conversion.  The documentation in the source
file 'tp/Texinfo/Convert/Converter.pm' is a good place to start.  Note:
Generic Translator texi2any.

  Another viable approach is use the Texinfo XML output from 'texi2any'
as your input.  This XML is an essentially complete representation of
the input, but without the Texinfo syntax and option peculiarities, as
described above.

  If you still cannot resist the temptation of writing a new program
that reads Texinfo source directly, let us give some more caveats:
please do not underestimate the amount of work required.  Texinfo is by
no means a simple language to parse correctly, and remains under
development, so you would be committing to an ongoing task.  At a
minimum, please check that the extensive tests of the language that come
with 'texi2any' give correct results with your new program.