branch master updated: * doc/texinfo.texi (HTML Output Structure Customization): edit

[Gavin D. Smith]

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

gavin pushed a commit to branch master
in repository texinfo.

The following commit(s) were added to refs/heads/master by this push:
     new e6fdd240be * doc/texinfo.texi (HTML Output Structure Customization): 
edit
e6fdd240be is described below

commit e6fdd240be2e74b7e86103ff83b6d9e97b49dc2a
Author: Gavin Smith <gavinsmith0123@gmail.com>
AuthorDate: Sat Nov 9 22:01:24 2024 +0000

    * doc/texinfo.texi (HTML Output Structure Customization): edit
---
 ChangeLog        |   4 +++
 doc/texinfo.texi | 103 ++++++++++++++++++++++++++++++++-----------------------
 2 files changed, 64 insertions(+), 43 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 16ad65f5d9..fa5530c34a 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2024-11-09  Gavin Smith <gavinsmith0123@gmail.com>
+
+       * doc/texinfo.texi (HTML Output Structure Customization): edit
+
 2024-11-09  Gavin Smith <gavinsmith0123@gmail.com>
 
        HTML Output Customization manual edit
diff --git a/doc/texinfo.texi b/doc/texinfo.texi
index 06ad991ecb..86cfdf6465 100644
--- a/doc/texinfo.texi
+++ b/doc/texinfo.texi
@@ -16122,6 +16122,7 @@ accented characters in HTML, XML, DocBook and @LaTeX{} 
output and special
 characters in HTML and @LaTeX{} output based on the document encoding.
 @xref{@code{@@documentencoding}}, and @ref{Inserting Accents}.
 
+@anchor{TOP_NODE_UP}
 @item TOP_NODE_UP
 Up node for the Top node; default @samp{(dir)}.  This node name is
 supposed to be already formatted for the output format.  In HTML
@@ -18178,6 +18179,9 @@ have the node name used as heading in that case, set
 @node File Names and Links Customization for HTML
 @subsection File Names and Links Customization for HTML
 
+There are customization variables to control output file names, and
+to customize hyperlinks output within output files.
+
 @c file names
 
 @vindex PREFIX @subentry @r{for HTML}
@@ -18197,28 +18201,32 @@ constructed as if the filesystem were case 
insensitive.  In that case,
 one file name is used for all files differing only by case.
 
 @vindex TOP_FILE
-Furthermore, the customization variables @code{TOP_FILE} override
+Furthermore, the customization variable @code{TOP_FILE} overrides
 the output file name for the top element.  This is, in general,
 only taken into account when output is split.
 
 @vindex USE_ACCESSKEY
 @vindex USE_REL_REV
 If @code{USE_ACCESSKEY} is set, the default, the @code{accesskey} attribute
-is used in navigation.  Keyboards shortcuts are set for selected directions
-only, with @kbd{n} for links to next node or section, @kbd{p} for links to
-previous previous node or section and @kbd{u} for up directions links.
+is used to provide keyboard shortcuts on some navigation hyperlinks.
+@kbd{n} is used for links to the next node or section, @kbd{p} for links to
+the previous node or section, and @kbd{u} for up direction links.
 Similarly, if the @code{USE_REL_REV} customization variable is set, the
 default, the @code{rel} attribute is used in navigation to define the
 relationship between the current page and the linked resource.  For example,
 the @samp{contents} @code{rel} attribute is set for a link to the table of
 contents, the @samp{next} @code{rel} attribute is set for a link to the next
 node or section.
+@c name of USE_REL_REV is a reference to the 'rev' attribute which is
+@c not actually used
 
 @c internal links
 
-Internal links customization is specific of link type:
+There are customization variables that are specific to particular
+types of link:
+
 @table @emph
-@item cross-reference command link
+@item Cross-reference command links
 @vindex XREF_USE_NODE_NAME_ARG
 If the second argument of a cross-reference command is set, it is displayed
 as hyperlink text (@pxref{Two Arguments}).  Otherwise the
@@ -18230,23 +18238,23 @@ name.  If set to @samp{undef}, use the first argument 
in preformatted
 environments, otherwise use the node name or section name depending on
 @code{USE_NODES}.  The default is @samp{undef}.
 
-@item link to float
+@item Links to floats
 @vindex XREF_USE_FLOAT_LABEL
 If you set @code{XREF_USE_FLOAT_LABEL} (default is off), the float label
 is used instead of the type followed by the float number
 (@pxref{@code{@@float}}).
 
-@item link to index entries root commands
+@item Links to nodes or sections for index entries
 @vindex NODE_NAME_IN_INDEX
-In @code{@@printindex} formatting, two links are output, a link to the index
-entry and a link to the root @@-command containing the index entry.  The
+In @code{@@printindex} formatting, two links are output: a link to the index
+entry, and a link to the root @@-command containing the index entry.  The
 @code{NODE_NAME_IN_INDEX} customization variable specifies whether the node or
 section should be used for the link to the root @@-command.  If true, use node
-names in index entries, otherwise prefer section names.  If undefined, use
-@code{USE_NODES} value to determine which root @@-command to prefer.  Default
-is undefined.
+names in index entries, otherwise use section names.  If undefined, use
+the @code{USE_NODES} value to determine which root @@-command to prefer.
+Default is undefined.
 
-@item menu links
+@item Menu links
 @vindex NODE_NAME_IN_MENU
 Node names are used in menu entries links by default.  Set
 @code{NODE_NAME_IN_MENU} to false to use section names instead.
@@ -18262,26 +18270,27 @@ Table of Contents entries in the default case.  Set
 If you set @code{TOC_LINKS}, links from headings to toc entries are created;
 default false.
 
-@item Top node up direction link
+@item Top node Up direction link
 @vindex IGNORE_REF_TO_TOP_NODE_UP
-By default no Top node Up reference is generated.  You can set
-@code{IGNORE_REF_TO_TOP_NODE_UP} so that references to the Top Up node
-appearing in other cross-references are also ignored.
-@code{IGNORE_REF_TO_TOP_NODE_UP} is not set in the default case.
+By default no Up reference is generated for the Top node.  You can set
+@code{IGNORE_REF_TO_TOP_NODE_UP} so that any references to the Top Up node
+(by default, @samp{(dir)}) appearing in other cross-references are also
+ignored.  @code{IGNORE_REF_TO_TOP_NODE_UP} is not set in the default case.
+(@xref{TOP_NODE_UP}.)
 
 @vindex TOP_NODE_UP_URL
 @vindex TOP_NODE_UP @subentry @r{for HTML}
-If the manual is referred to in a web page together with other manuals
+If the manual is referred to in a web page together with other manuals,
 it may be relevant to link to that page.  Set
 @code{TOP_NODE_UP_URL} to the URL used for Top node up references.
-If @code{TOP_NODE_UP_URL} is set, the @code{TOP_NODE_UP} customization
-variable value is used for the hyperlink text, with @samp{(dir)} as default.
+If @code{TOP_NODE_UP_URL} is set, the value of @code{TOP_NODE_UP}
+is used for the hyperlink text, with @samp{(dir)} as default.
 @code{TOP_NODE_UP} can be used in attribute, so should not contain any element.
 
-For example, for GNU @url{http://www.gnu.org/manual/} collects
-links to most GNU manuals, therefore @code{TOP_NODE_UP_URL} is
-best  specified as  @code{/manual/} if the manual
-will be installed on @code{www.gnu.org}.
+For example, in the GNU project @url{http://www.gnu.org/manual/} collects
+links to most GNU manuals; therefore @code{TOP_NODE_UP_URL} is best
+specified as @code{/manual/} if the manual will be installed on
+@code{www.gnu.org}.
 
 @xref{First Node} for more about the Top node pointers.
 
@@ -18301,7 +18310,7 @@ through the @file{htmlxref.cnf} file (@pxref{HTML Xref 
Configuration}).
 
 @vindex CHECK_HTMLXREF
 Default directories and file names are used for cross-reference target
-manual not found through HTML Xref Configuration (@pxref{HTML Xref Link
+manuals not found through HTML Xref Configuration (@pxref{HTML Xref Link
 Basics}).  By default, a warning is given for each external manual not in
 the HTML Xref configuration files.  If you do not want warnings about such
 manuals, you should set @code{CHECK_HTMLXREF} to @samp{0}.  This could
@@ -18325,30 +18334,38 @@ variable sets the file used for HTML Xref 
configuration to another value than
 the default, @file{htmlxref.cnf}.  If @code{HTMLXREF_FILE} contains 
directories,
 it is loaded if found, but is not searched for in directories.  By default, the
 distant manual is considered to be split or monolithic based on the splitting
-of the manual being output.  You can set it explicitely, instead, by setting
+of the manual being output.  You can set it explicitly, instead, by setting
 @code{EXTERNAL_CROSSREF_SPLIT}.
 
 @cindex Cross-references customization, in HTML
-You can also set customization variables to modify how
-cross-references are output in various other ways.  In general, this will make
-cross-manual references ``invalid'', in the sense that the generated URL will
-not link to the external manual, unless this manual was itself produced using
-corresponding customization.  It is therefore, in general, better to use HTML
-Xref Configuration only.
+There are also customization variables that modify various other
+aspects of cross-references:
 
+@itemize @bullet
 @vindex TOP_NODE_FILE_TARGET
+@item You can set the file name used for the Top node in cross-references by
+setting the @code{TOP_NODE_FILE_TARGET} customization variable value;
+default is @file{index.html}.
+
 @vindex EXTERNAL_DIR
+@item You specify a base directory for external
+manuals with @code{EXTERNAL_DIR}; in the default case, there is none.
+
 @vindex EXTERNAL_CROSSREF_EXTENSION
 @vindex BASEFILENAME_LENGTH
-You can set the file name used for the Top node in cross-references by
-setting the @code{TOP_NODE_FILE_TARGET} customization variable value;
-default is @file{index.html}.  You specify a base directory for external
-manuals with @code{EXTERNAL_DIR}, in the default case there is none.
-Similarly, you set the file extension for cross-references to other manuals
-with @code{EXTERNAL_CROSSREF_EXTENSION}, which, if unset, is based on
-@code{EXTENSION}.  By default, the base file names are truncated to 245
-characters (@pxref{HTML Xref Link Basics}).  Change the maximum length of
-a base file name by setting @code{BASEFILENAME_LENGTH}.
+@item Similarly, you set the file extension for cross-references to other
+manuals with @code{EXTERNAL_CROSSREF_EXTENSION}, which, if unset, is based on
+@code{EXTENSION}.  You can change the maximum length of a base file name
+by setting @code{BASEFILENAME_LENGTH}; by default, the base file names
+are truncated to 245 characters (@pxref{HTML Xref Link Basics}).
+@end itemize
+
+@noindent However, in general use of these will make cross-manual
+references ``invalid'' in the sense that the generated URL will not link
+to the external manual, unless this manual was itself also produced
+using the corresponding customization. It is therefore, in general,
+better to use HTML Xref Configuration only.
+
 
 
 @node Customization of Navigation and Headers