texinfo ChangeLog doc/texinfo.txi

[Karl Berry]

CVSROOT:        /sources/texinfo
Module name:    texinfo
Changes by:     Karl Berry <karl>       12/02/23 19:04:59

Modified files:
        .              : ChangeLog 
        doc            : texinfo.txi 

Log message:
        (Output Formats): more on new back-ends vs. new programs

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/texinfo/ChangeLog?cvsroot=texinfo&r1=1.1332&r2=1.1333
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/texinfo.txi?cvsroot=texinfo&r1=1.426&r2=1.427

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/texinfo/texinfo/ChangeLog,v
retrieving revision 1.1332
retrieving revision 1.1333
diff -u -b -r1.1332 -r1.1333
--- ChangeLog   23 Feb 2012 02:53:39 -0000      1.1332
+++ ChangeLog   23 Feb 2012 19:04:55 -0000      1.1333
@@ -1,3 +1,8 @@
+2012-02-23  Karl Berry  <address@hidden>
+
+       * doc/texinfo.txi (Output Formats): expand the text on writing
+       new back-ends vs. a new programs; idea and basis from Patrice.
+
 2012-02-22  Karl Berry  <address@hidden>
 
        * doc/texinfo.txi (#line Syntax Details): update for new regexp,

Index: doc/texinfo.txi
===================================================================
RCS file: /sources/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.426
retrieving revision 1.427
diff -u -b -r1.426 -r1.427
--- doc/texinfo.txi     23 Feb 2012 02:53:40 -0000      1.426
+++ doc/texinfo.txi     23 Feb 2012 19:04:56 -0000      1.427
@@ -1,5 +1,5 @@
 \input texinfo.tex    @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.426 2012/02/23 02:53:40 karl Exp $
address@hidden $Id: texinfo.txi,v 1.427 2012/02/23 19:04:56 karl Exp $
 @c Ordinarily, Texinfo files have the extension .texi.  But texinfo.texi
 @c clashes with texinfo.tex on 8.3 filesystems, so we use texinfo.txi.
 
@@ -958,23 +958,10 @@
 represent the exact appearance of a document, including fonts and
 graphics, and supporting arbitrary scaling.  It is intended to be
 platform-independent and easily viewable, among other design goals;
address@hidden://tug.org/TUGboat/Articles/tb22-3/tb72beebe-pdf.pdf} has
-some background.  Texinfo uses the @command{pdftex} program, a variant
-of @TeX{}, to output PDF; see
address@hidden://tug.org/applications/pdftex}.  @xref{PDF Output}.
-
address@hidden XML
address@hidden XML output
address@hidden DTD, for Texinfo XML
address@hidden texinfo.dtd
-(Generated via @command{makeinfo --xml}.)  XML is a generic syntax
-specification usable for any sort of content (see, for example,
address@hidden://www.w3.org/XML/}).  The @command{makeinfo} XML output,
-unlike all the formats above, interprets very little of the Texinfo
-source.  Rather, it merely translates the Texinfo markup commands into
-XML syntax, for processing by further XML tools.  The particular
-syntax output is defined in the file @file{texinfo.dtd} included in
-the Texinfo source distribution.
address@hidden://tug.org/TUGboat/tb22-3/tb72beebe-pdf.pdf} has some
+background.  Texinfo uses the @command{pdftex} program, a variant of
address@hidden, to output PDF; see @uref{http://tug.org/applications/pdftex}.
address@hidden Output}.
 
 @item Docbook
 @cindex Docbook output
@@ -985,39 +972,68 @@
 to convert from Docbook @emph{to} Texinfo, please see
 @uref{http://docbook2X.sourceforge.net}.
 
address@hidden XML
address@hidden XML output
address@hidden DTD, for Texinfo XML
address@hidden texinfo.dtd
+(Generated via @command{makeinfo --xml}.)  XML is a generic syntax
+specification usable for any sort of content (see, for example,
address@hidden://www.w3.org/XML}).  The @command{makeinfo} XML output,
+unlike all the other output formats, interprets very little of the
+Texinfo source.  Essentially, it translates the Texinfo markup
+commands into XML syntax, for processing by further XML tools.  The
+details of the output are defined in an XML DTD as usual, contained in
+a file @file{texinfo.dtd} included in the Texinfo source distribution
+and available via the Texinfo web pages.
+
 @end table
 
 @cindex Man page output, not supported
 From time to time, proposals are made to generate traditional Unix man
-pages from Texinfo source.  However, because man pages have a very
-strict conventional format, generating 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
+pages from Texinfo source.  However, because man pages have a strict
+conventional format, generating 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 just write the man page
 directly.
 
 @pindex help2man
 @cindex O'Dea, Brendan
-Man pages still have their place, and if you wish to support them, you
-may find the program @command{help2man} to be useful; it generates a
-traditional man page from the @samp{--help} output of a program.  In
-fact, this is currently used to generate man pages for the programs in
-the Texinfo distribution.  It is GNU software written by Brendan
-O'Dea, available from @uref{http://ftp.gnu.org/gnu/help2man/}.
+Man pages are still used on today's systems, and if you wish to
+support them, you may find the program @command{help2man} to be
+useful; it generates a traditional man page from the @samp{--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
address@hidden://ftpmirror.gnu.org/help2man}.
 
 @cindex Output formats, supporting more
 @cindex SGML-tools output format
 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.  But please do not write a separate translator
address@hidden for your favorite format foo!  That is the hard way to
-do the job, and makes for an impractical amount of subsequent
-maintenance, since the Texinfo language is continually being enhanced
-and updated.  Instead, the best approach is modify @code{makeinfo} to
-generate the new format.  @xref{Generic Translator texi2any,,
address@hidden: The Generic Translator}.
+would be excellent.  Probably the way to do this that is most useful
+is to write a new back-end for @command{texi2any}, the reference
+implementation of a Texinfo parser; it creates a tree representation
+of the Texinfo input that you can use for the conversion.
address@hidden Translator texi2any,, @command{texi2any}: The Generic
+Translator}.
+
+Another viable approach is use the Texinfo XML output from
address@hidden as your input.  This XML is an essentially complete
+representation of the input, but without the Texinfo syntax and option
+peculiarities, as described above.
+
address@hidden Texinfo parsers, discouraging more
+If you still cannot resist the temptation of writing a new program
+that reads the Texinfo source directly, let us give some more caveats:
+please do not underestimate the amount of work required.  Texinfo is
+by no mean a simple language to parse correctly, and is still being
+enhanced, so you would be committing to an ongoing task.  At a
+minimum, please check that the extensive tests of the language that
+come with @command{texi2any} give correct results with your new
+program.
 
 
 @node Info Files
@@ -21769,7 +21785,7 @@
 Revision Control System}) or other version control systems, which
 expand it into a string such as:
 @example
-$Id: texinfo.txi,v 1.426 2012/02/23 02:53:40 karl Exp $
+$Id: texinfo.txi,v 1.427 2012/02/23 19:04:56 karl Exp $
 @end example
 (This is useful in all sources that use version control, not just manuals.)
 You may wish to include the @samp{$Id:} comment in the @code{@@copying}