On Fri, Feb 21, 2025 at 07:32:25PM +0000, Gavin Smith wrote:
> I'm not sure that the whole paragraph about a "reference implementation"
> is particularly relevant either.
Here is another attempt, with a separate section added for the
discussion or Texinfo processors, Texinfo parsing and doing a new
parser.
--
Pat
diff --git a/doc/texinfo.texi b/doc/texinfo.texi
index cfade53df4..3f2b6e43ae 100644
--- a/doc/texinfo.texi
+++ b/doc/texinfo.texi
@@ -506,15 +506,6 @@ @node Adding Output Formats
representation of the input, but without the Texinfo syntax and option
peculiarities, as described above.
-@cindex Texinfo parsers, discouraging more
-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. You
-are advised to check that the tests of the language that come with
-@command{texi2any} give correct results with your new program.
-
@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 strict
@@ -536,6 +527,36 @@ @node Adding Output Formats
@uref{http://www.gnu.org/software/help2man}.
+@node Texinfo Processors
+@section Texinfo Processors
+
+@cindex @command{texi2any}, as reference implementation
+@cindex Reference implementation
+@cindex Implementation, @command{texi2any} as reference
+@anchor{Reference Implementation}@c
+The generic @command{texi2any} translator for Texinfo is intended to be a
+reference implementation that defines parts of the language not fully specified
+by the manual. Without reference, Texinfo documents parsing could become
+dependent on the processor. It is also desirable to have consistent
+command-line options for all processors.
+
+Two other processors are documented
+in the manual, the Texinfo @file{texinfo.tex}
+used together with @TeX{} for printed books (@pxref{Hardcopy with @TeX{}}),
+and Emacs Texinfo mode commands (@pxref{@code{texinfo-format} commands}).
+
+@cindex Texinfo language tests
+@cindex Tests, of Texinfo language
+@cindex Texinfo parsers, discouraging more
+These processors should cover most needs. 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. You
+are advised to check that the Texinfo code of tests of the language that come
+withe @command{texi2any} give correct results with your new program.
+
+
@node History
@nodedescription Acknowledgements, contributors and genesis.
@section History
@@ -670,21 +691,6 @@ @node History
@command{texi2any} C implementation embeds a Perl interpreter for the parts
that require Perl.
-@cindex @command{texi2any}, as reference implementation
-@cindex Reference implementation
-@cindex Implementation, @command{texi2any} as reference
-@cindex Texinfo language tests
-@cindex Tests, of Texinfo language
-@anchor{Reference Implementation}@c
-@command{texi2any} is intended to be a reference implementation
-that defines parts of the language not fully specified by the manual.
-Without reference, Texinfo documents parsing could become dependent
-on the processor. It is also desirable to have consistent command-line options
-for all processors. Extensive tests of the language and processor are
-developed with @command{texi2any}; we encourage anyone thinking
-of writing a program to parse Texinfo input to verify the correctness
-of parsing Texinfo code used in these tests.
-
@node Writing a Texinfo File
@anchor{Beginning and Ending a File}@c old name
