branch master updated: Describe output file and encoding early. More semantic @title, etc.

[Patrice Dumas]

This is an automated email from the git hooks/post-receive script.

pertusus pushed a commit to branch master
in repository texinfo.

The following commit(s) were added to refs/heads/master by this push:
     new 5c98c87d71 Describe output file and encoding early. More semantic 
@title, etc.
5c98c87d71 is described below

commit 5c98c87d71c4d50588cd007deaff35a31eb6d056
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Sun Jul 24 00:44:25 2022 +0200

    Describe output file and encoding early. More semantic @title, etc.
    
    * doc/texinfo.texi (Minimum, @code{@@setfilename}): state the
    default output file name when the input file name extension is
    described, in 'Minimum'.
    texi2any does not need \input texinfo nor @bye, do not implicitly
    say that.
    (Minimum): give the information on the default encoding here, to
    have this information early in the manual.
    (Minimum, Texinfo File Header): treat @settitle as any other
    preamble @-command.
    (Texinfo File Header, @code{@@documentencoding}): use consistently
    'preamble' and not 'Texinfo preamble'.
    (@code{@@titlepage}, @code{@@title @@subtitle @@author}): insist
    less on the formatting of @title, @subtitle and @author, using wording
    less definitive on the formatting, as it is semantic and formatting
    could change over time or across formats.
---
 ChangeLog        |  20 ++++++++++
 doc/texinfo.texi | 120 +++++++++++++++++++++++++++++--------------------------
 tp/texi2any.pl   |   3 +-
 3 files changed, 86 insertions(+), 57 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index dcc54aaf0d..8889dc9284 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,23 @@
+2022-07-23  Patrice Dumas  <pertusus@free.fr>
+
+       Describe output file and encoding early. More semantic @title, etc.
+
+       * doc/texinfo.texi (Minimum, @code{@@setfilename}): state the
+       default output file name when the input file name extension is
+       described, in 'Minimum'.
+       texi2any does not need \input texinfo nor @bye, do not implicitly
+       say that.
+       (Minimum): give the information on the default encoding here, to
+       have this information early in the manual.
+       (Minimum, Texinfo File Header): treat @settitle as any other
+       preamble @-command.
+       (Texinfo File Header, @code{@@documentencoding}): use consistently
+       'preamble' and not 'Texinfo preamble'.
+       (@code{@@titlepage}, @code{@@title @@subtitle @@author}): insist
+       less on the formatting of @title, @subtitle and @author, using wording
+       less definitive on the formatting, as it is semantic and formatting
+       could change over time or across formats.
+
 2022-07-23  Gavin Smith  <gavinsmith0123@gmail.com>
 
        INPUT_FILE_NAME_ENCODING, OUTPUT_FILE_NAME_ENCODING documentation
diff --git a/doc/texinfo.texi b/doc/texinfo.texi
index ecd22c61f0..2131dddd43 100644
--- a/doc/texinfo.texi
+++ b/doc/texinfo.texi
@@ -1482,13 +1482,18 @@ extensions @file{.texi}, @file{.texinfo}, @file{.txi}, 
or
 is already used by @TeX{} and @LaTeX{} input files.  The most common
 and recommended extension is @file{.texi}.
 
-In order to be made into a printed manual and other output
-formats, a Texinfo file must begin with lines like this:
+The output name is based on the input file name, in the default case.
+First, any of the extensions @file{.texi}, @file{.tex}, @file{.txi}
+or @file{.texinfo} is removed from the input file name; then,
+the output format specific extension is added---@file{.html} when
+generating HTML, @file{.info} when generating Info, etc.
+
+In order to be made into a printed manual, a Texinfo file must begin
+with lines like this:
 
 @example
 @group
 \input texinfo
-@@settitle @var{name-of-manual}
 @end group
 @end example
 
@@ -1503,14 +1508,19 @@ must end the Texinfo source with a line like this:
 @findex \input @r{(raw @TeX{} startup)}
 
 The @code{@@bye} line at the end of the file on a line of its own tells
-the formatters that the file is ended and to stop formatting.  If you 
-leave this out, you'll be dumped at @TeX{}'s prompt at the end of the 
+@TeX{} that the file is ended and to stop formatting.  If you
+leave this out, you'll be dumped at @TeX{}'s prompt at the end of the
 run.
 
-Furthermore, you will usually provide a Texinfo file with a title page,
-indices, and the like, all of which are explained in this manual.  But
-the minimum, which can be useful for short documents, is just the two
-lines at the beginning and the one line at the end.
+Furthermore, you will usually provide a Texinfo file with a title,
+a title page, indices, and the like, all of which are explained in
+this manual.  But the minimum, which can be useful for short
+documents, is just the one line at the beginning and the one line
+at the end.
+
+Without additional information, the input and output encodings are
+assumed to be UTF-8, an universal codeset compatible with 7-bit
+ASCII.
 
 
 @node Short Sample Texinfo File
@@ -1553,7 +1563,6 @@ This manual is for GNU Sample
 @@end menu
 
 
-@group
 @@node First Chapter
 @@chapter First Chapter
 
@@ -1561,6 +1570,7 @@ This manual is for GNU Sample
 This is the first chapter.
 @@cindex index entry, another
 
+@group
 Here is a numbered list.
 
 @@enumerate
@@ -1570,6 +1580,7 @@ This is the first item.
 @@item
 This is the second item.
 @@end enumerate
+@end group
 
 
 @@node First Section
@@ -1582,7 +1593,6 @@ First section of first chapter.
 @@section Second Section
 
 Second section of first chapter.
-@end group
 
 
 @@node Index
@@ -1599,13 +1609,10 @@ Second section of first chapter.
 @cindex Header for Texinfo files
 @cindex Texinfo file header
 
-Texinfo files start with at least two lines:
+Texinfo files start with the line:
 
 @example
-@group
 \input texinfo
-@@settitle Sample Manual 1.0
-@end group
 @end example
 
 The @samp{\input texinfo} line tells @TeX{} to use the
@@ -1613,18 +1620,22 @@ The @samp{\input texinfo} line tells @TeX{} to use the
 @@-commands into @TeX{} typesetting commands.  (Note the use of the
 backslash, @samp{\}; this is correct for @TeX{}.)
 
-The @code{@@settitle} line specifies a title for the page headers (or
-footers) of the printed manual, and the default title and document
-description for the @samp{<head>} in HTML@.  (Strictly speaking,
-@code{@@settitle} is optional---if you don't mind your document being
-titled `Untitled'.)
+It makes sense to include any command that affects document formatting
+as a whole in the header.  The @code{@@settitle} line is usually
+present at the beginning of the header:
+
+@example
+@@settitle Sample Manual 1.0
+@end example
 
-It makes sense to include any command that affects document formatting 
-as a whole in the header.  @code{@@synindex} (@pxref{@code{@@synindex}}),
-for instance, is another command often included in the header.
+The @code{@@settitle} line specifies a title for the page headers
+(or footers) of the printed manual, and the default title and document
+description for the @samp{<head>} in HTML@.  @code{@@synindex}
+(@pxref{@code{@@synindex}}), for instance, is another command often
+included in the header.
 
 The start of the Texinfo file up to the first content that is output
-as part of the main body of the document is the @dfn{Texinfo preamble}.
+as part of the main body of the document is the @dfn{preamble}.
 It includes the header, @ref{Document Permissions} and @ref{Titlepage & 
Copyright Page}
 specification.  It is important for the @LaTeX{} output format as the
 end of preamble is where the @code{\begin@{document@}} line is output.  In
@@ -1688,23 +1699,22 @@ from the file extension automatically.
 @cindex output file name
 
 The @code{@@setfilename} line specifies the name of the output file to
-be generated by @command{makeinfo}.  This command is ignored
-for @TeX{} formatting.
-When present, it should be the first Texinfo command (that is, after
-@samp{\input texinfo}).
-Write the @code{@@setfilename} command at the beginning of a line and
-follow it on the same line by the Info file name.
+be generated by @command{texi2any}.  This command is ignored for
+@TeX{} formatting.  When present, it should be the first Texinfo
+command (that is, after @samp{\input texinfo}).  Write the
+@code{@@setfilename} command at the beginning of a line and follow it
+on the same line by the Info file name.
 
 @example
 @@setfilename @var{info-file-name}
 @end example
 
-The name must be different from the name of the
-Texinfo file.  There are two conventions for choosing the name: you
+The name must be different from the name of the Texinfo file.
+There are two conventions for choosing the name: you
 can either remove the extension (such as @samp{.texi}) entirely from
 the input file name, or (recommended) replace it with the @samp{.info}
 extension.  It is not advised to base the @code{@@setfilename} name
-on a entirely different name than the input name.
+on a entirely different name than the input file name.
 
 @cindex Ignored before @code{@@setfilename}
 @cindex @samp{\input} source line ignored
@@ -1713,15 +1723,12 @@ ignore everything written before the 
@code{@@setfilename} line.  This
 is why the very first line of the file (the @code{\input} line) does
 not show up in the output.
 
-If there is no @code{@@setfilename} line, @code{makeinfo} uses the
-input file name to determine the output name: first, any of the
-extensions @code{.texi}, @code{.tex}, @code{.txi} or @code{.texinfo}
-is removed from the input file name; then, the output format specific
-extension is added---@code{.html} when generating HTML, @code{.info}
-when generating Info, etc.  The @code{\input} line is still ignored in
-this processing, as well as leading blank lines.
+If there is no @code{@@setfilename} line, @command{texi2any} uses the
+input file name to determine the output name (@pxref{Minimum}).  The
+@code{\input} line is still ignored in this processing, as well
+as leading blank lines.
 
-When producing another output format, @code{makeinfo} will replace any
+When producing another output format, @command{texi2any} will replace any
 final extension with the output format-specific extension (@samp{html}
 when generating HTML, for example), or add a dot followed by the
 extension (@samp{.html} for HTML) if the given name has no extension.
@@ -1876,10 +1883,9 @@ A start-of-header line is a Texinfo comment that looks 
like this:
 @end example
 
 Write the start-of-header line on the second line of a Texinfo file.
-Follow the start-of-header line with an @code{@@settitle} line and,
-optionally, with other commands that globally affect the document
-formatting, such as @code{@@synindex} or @code{@@footnotestyle}; and
-then by an @w{end-of-header} line.
+Follow the start-of-header commands that globally affect the document
+formatting, such as @code{@@settitle}, @code{@@synindex} or
+@code{@@footnotestyle}; and then by an @w{end-of-header} line.
 
 @anchor{End of Header}@c old name
 @cindex End of header line
@@ -2187,11 +2193,12 @@ the program.  (The `Top' node should also contain this 
information; see
 @ref{The Top Node}.)
 
 One method uses the @code{@@title}, @code{@@subtitle}, and
-@code{@@author} commands to create a title page with black rules under
+@code{@@author} commands to create a title page.  With this method,
+you do not specify any of the actual formatting of the title page.
+You specify the text you want, and Texinfo does the formatting.
+The usual formatting consist of black rules under
 the title and author lines and the subtitle text set flush to the
-right-hand side of the page.  With this method, you do not specify any
-of the actual formatting of the title page.  You specify the text
-you want, and Texinfo does the formatting.
+right-hand side of the page.
 
 Texinfo also provides a second method for creating a title page.
 using typesetting commands that are not to be used in the main text.
@@ -2229,7 +2236,7 @@ an @code{@@quotation} block (@pxref{@code{@@quotation}});
 except for that, it is an error to use any of these commands outside
 of @code{@@titlepage}.
 
-The @code{@@title} command produces a line in which the title is set
+The @code{@@title} command normally produces a line in which the title is set
 flush to the left-hand side of the page in a larger than normal font.
 The title is underlined with a black rule.  The title must be given on
 a single line in the source file; it will be broken into multiple
@@ -2245,13 +2252,14 @@ conditional (@pxref{Conditionals}).  For example:
 @@title This Long Title@@inlinefmt@{tex,@@*@} Is Broken in @@TeX@{@}
 @end example
 
-The @code{@@subtitle} command sets subtitles in a normal-sized font
+The @code{@@subtitle} command normally sets subtitles in a normal-sized font
 flush to the right-hand side of the page.
 
-The @code{@@author} command sets the names of the author or authors in
-a middle-sized font flush to the left-hand side of the page on a line
-near the bottom of the title page.  The names are followed by a black
-rule that is thinner than the rule that underlines the title.
+The @code{@@author} command normally sets the names of the author
+or authors in a middle-sized font flush to the left-hand side of the
+page on a line near the bottom of the title page.  The names are
+followed by a black rule that is thinner than the rule that normally
+underlines the title.
 
 There are two ways to use the @code{@@author} command: you can write
 the name or names on the remaining part of the line that starts with
@@ -12531,7 +12539,7 @@ based on the encoding.  This, by itself, does not 
ensures that all
 the characters from the input document  can be subsequently output.
 The fonts used in the default case should cover the specific Texinfo
 glyphs, but not all the possible encoded characters.  You may need to
-load different fonts in the Texinfo preamble and use
+load different fonts in the preamble and use
 @code{\DeclareUnicodeCharacter} with a UTF-8 encoding.  For example:
 @example
 @@latex
diff --git a/tp/texi2any.pl b/tp/texi2any.pl
index 0d4d3b027a..d303337622 100755
--- a/tp/texi2any.pl
+++ b/tp/texi2any.pl
@@ -1218,7 +1218,8 @@ if (defined(get_conf('FORMAT_MENU'))
 
 # using no warnings is wrong, but a way to avoid a spurious warning.
 no warnings 'once';
-my @parser_settable_options = 
keys(%Texinfo::Common::default_parser_customization_values);
+my @parser_settable_options
+      = keys(%Texinfo::Common::default_parser_customization_values);
 # Copy relevant customization variables into the parser options.
 foreach my $parser_settable_option (@parser_settable_options) {
   if (defined(get_conf($parser_settable_option))) {