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 a proposal to move that paragraph to the Overview, and
deduplicate the part about tests and alternative implementation that is
already in Adding Output Formats.
What do you think?
--
Pat
diff --git a/doc/texinfo.texi b/doc/texinfo.texi
index 32a0760eff..afcbff69c1 100644
--- a/doc/texinfo.texi
+++ b/doc/texinfo.texi
@@ -207,6 +207,16 @@ @node Overview
is, rather than the English letter ``ex'', actually the Greek letter
``chi''.
+@cindex @command{texi2any}, as reference implementation
+@cindex Reference implementation
+@cindex Implementation, @command{texi2any} as reference
+@anchor{Reference Implementation}@c
+The @command{texi2any} generic translator distributed with GNU 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.
+
Texinfo is the official documentation format of the GNU project.
More information, including manuals for GNU packages, is available
at the @uref{http://www.gnu.org/doc/, GNU documentation web page}.
@@ -506,13 +516,15 @@ @node Adding Output Formats
peculiarities, as described above.
@cindex Texinfo parsers, discouraging more
+@cindex Texinfo language tests
+@cindex Tests, of Texinfo language
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.
+are advised to check that the Texinfo code of 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
@@ -673,21 +685,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
