[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
branch master updated: * doc/texinfo.texi (Menus): HTML menus are also a
|
From: |
Patrice Dumas |
|
Subject: |
branch master updated: * doc/texinfo.texi (Menus): HTML menus are also automatically generated. |
|
Date: |
Mon, 01 Apr 2024 14:22:53 -0400 |
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 5ec5b71b62 * doc/texinfo.texi (Menus): HTML menus are also
automatically generated.
5ec5b71b62 is described below
commit 5ec5b71b6259b53caf0552e148db7b364e090f79
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Mon Apr 1 20:22:44 2024 +0200
* doc/texinfo.texi (Menus): HTML menus are also automatically
generated.
* doc/texinfo.texi (EPUB HTML): minor change on customization
variables used.
* doc/texinfo.texi (HTML Output Structure Customization): add
FORMAT_MENU nomenu to explanations.
* doc/texinfo.texi: add index entries in HTML Customization nodes and
references to those nodes.
---
ChangeLog | 14 ++++++++++
doc/texinfo.texi | 78 ++++++++++++++++++++++++++++++++++++++++++++------------
2 files changed, 75 insertions(+), 17 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index e7e4b9fa1d..8c1cb3c945 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,17 @@
+2024-04-01 Patrice Dumas <pertusus@free.fr>
+
+ * doc/texinfo.texi (Menus): HTML menus are also automatically
+ generated.
+
+ * doc/texinfo.texi (EPUB HTML): minor change on customization
+ variables used.
+
+ * doc/texinfo.texi (HTML Output Structure Customization): add
+ FORMAT_MENU nomenu to explanations.
+
+ * doc/texinfo.texi: add index entries in HTML Customization nodes and
+ references to those nodes.
+
2024-04-01 Patrice Dumas <pertusus@free.fr>
* doc/texinfo.texi (Customization Variables)
diff --git a/doc/texinfo.texi b/doc/texinfo.texi
index bd4fc4e53f..6a145988fd 100644
--- a/doc/texinfo.texi
+++ b/doc/texinfo.texi
@@ -279,7 +279,7 @@ Files}, and @ref{Creating and Installing Info Files}.
same as Info output with the navigational control characters
omitted.
-@cindex HTML output, overview
+@cindex HTML output @subentry overview
@item HTML
@c @cindex Mozilla
@c @cindex Lynx
@@ -2826,12 +2826,12 @@ a menu as follows:
@dfn{Menus} contain pointers to subordinate nodes. In Info output,
you use menus to go to such nodes. @command{texi2any} can output menus in
HTML output, but does not do so by default
-(@pxref{Other Customization Variables}, under @code{FORMAT_MENU}).
+(@pxref{HTML Output Structure Customization}, @code{FORMAT_MENU}).
Menus have no role in printed manuals or other output formats.
Menus are automatically generated by @command{texi2any} when outputting
-Info for nodes followed by a sectioning command, without an explicit
-@code{@@menu} block, and with automatic pointers.
+Info or HTML with menus for nodes followed by a sectioning command, without an
+explicit @code{@@menu} block, and with automatic pointers.
It is often more convenient to let @command{texi2any} generate
menus for you, as you do not then have the burden of updating menu
@@ -9463,6 +9463,7 @@ for plain @TeX{} math control sequences for symbols,
functions,
and so on.
@cindex Math output for HTML
+@cindex HTML output @subentry math
By default, the HTML output is only emphasized.
@command{texi2any} provides three options for displaying properly
formatted mathematics for HTML. You can select these with the
@@ -11928,7 +11929,7 @@ encoding where possible. If this is not possible, or
if the option
@option{--disable-encoding} is given, an ASCII transliteration is
used instead.
-@cindex HTML output, and encodings
+@cindex HTML output @subentry encodings
@cindex @code{http-equiv}, and charset specification
@cindex @code{<meta>} HTML tag, and charset specification
In HTML output, a @samp{<meta>} tag is output, in the @samp{<head>}
@@ -15685,7 +15686,8 @@ Use tables for header formatting rather than a simple
@code{<div>} element; default false.
@item HTML_MATH
-Method to use to render @code{@@math}. This can be unset, set to
+Method to use to render @code{@@math} (@pxref{HTML Customization for Math}).
+This can be unset, set to
@samp{mathjax} (@pxref{MathJax Customization Variables}),
set to @samp{l2h}, which uses @command{latex2html}
(@pxref{@command{latex2html} Customization Variables}), or set to
@@ -17566,7 +17568,7 @@ to the output (i.e., suppressing the normal escaping of
input
@samp{<}, @samp{>} and @samp{&} characters which have special
significance in HTML)@. @xref{Conditional Commands}.
-@cindex HTML output, browser compatibility of
+@cindex HTML output @subentry browser compatibility
@strong{Standards}:
It is intentionally not our goal, and not even always possible, to pass
through every conceivable validation test without any diagnostics.
@@ -17590,7 +17592,7 @@ dropped@dots{}).
@nodedescription How HTML output is split.
@section HTML Splitting
@cindex Split HTML output
-@cindex HTML output, split
+@cindex HTML output @subentry split
When splitting output at nodes (which is the default),
@command{texi2any} writes HTML output into (basically) one output file
@@ -17870,10 +17872,10 @@ set @code{CHECK_HTMLXREF} to 0.
The HTML generated for EPUB is XHTML conformant, UTF-8 encoded, and
formatted without the usual HTML navigation headers and footers.
Most of these features are enabled with customization variables, such as
-@code{USE_XML_SYNTAX} or @code{OUTPUT_FILE_NAME_ENCODING}. Some
-features of printed output are used in EPUB@. In particular, the Top
-node does not appear in the EPUB output, while a title page is
-generated. This is obtained by setting @code{NO_TOP_NODE_OUTPUT}.
+@code{USE_XML_SYNTAX}, @code{HEADERS} or @code{OUTPUT_ENCODING_NAME}. Some
+features of printed output are used in EPUB@. In particular, the Top node does
+not appear in the EPUB output, while a title page is generated. This is
+obtained by setting @code{NO_TOP_NODE_OUTPUT}.
The @code{OUTFILE} and @code{SUBDIR} customization variables values
correspond initially to the EPUB directory container and/or the
@@ -18447,9 +18449,13 @@ it needs to be achieved through the use of
initialization files and
is described in a separate manual (@pxref{,,, texi2any_api, GNU
Texinfo @command{texi2any} Output Customization}).
+
@node HTML Output Structure Customization
@subsection HTML Output Structure Customization
+@vindex NO_TOP_NODE_OUTPUT
+@vindex SHOW_TITLE
+@vindex USE_TITLEPAGE_FOR_TITLE
In the default case, the HTML output is tailored for online viewing with
a direct access to the information at the Top node. For an output more
similar to a book, set @code{NO_TOP_NODE_OUTPUT} to remove the Top node.
@@ -18462,12 +18468,14 @@ If @code{SHOW_TITLE} is set, it is possible to output
the table of contents
at the end of the title by setting @code{CONTENTS_OUTPUT_LOCATION} to
@samp{after_title}.
+@vindex CONTENTS_OUTPUT_LOCATION
+@vindex FORMAT_MENU
In the default case, a list of subordinate sections is output in each node
for navigation, corresponding to @code{FORMAT_MENU} set to @samp{sectiontoc}.
The table of contents are output at the end of the @code{@@top}
section, to have the main location for navigation in the whole document
early on, corresponding to @code{CONTENTS_OUTPUT_LOCATION} set to
-samp @code{after_top}. To use menus instead to navigate in the document
+@samp{after_top}. To use menus instead to navigate in the document
(@pxref{Menus}), set @code{FORMAT_MENU} to @samp{menu}.
If menus are used for navigation, the tables of contents are not
@@ -18480,9 +18488,14 @@ to @samp{separate_element}. It is also possible to set
the tables of content are output where
the corresponding @@-command, for example @code{@@contents}, is set.
+If menus and subordinate sections list for navigation are not desired,
+set @code{FORMAT_MENU} to @samp{nomenu}.
+
+@vindex DO_ABOUT
A special @dfn{About} element explaining how to navigate can be added by
setting @code{DO_ABOUT}, set to 0 in the default case (no About element).
+@vindex MONOLITHIC
If non-split, in the default case, the special elements such as the About
element or the tables of contents are output in the same file as the
manual nodes and sections. If you prefer such special elements to be separate,
@@ -18490,6 +18503,8 @@ set @code{MONOLITHIC} to 0 to output special elements
to separate files. As
already described, the table of contents location may also be tuned with
@code{CONTENTS_OUTPUT_LOCATION}.
+@vindex INFO_JS_DIR
+@cindex JavaScript browsing interface for HTML
An experimental JavaScript browsing interface to the manual can be added, by
setting @code{INFO_JS_DIR} value to the directory to place the code for this
interface as e.g.@: @samp{texi2any --html -c INFO_JS_DIR=js @var{manual}.texi}
@@ -18516,6 +18531,7 @@ website that includes your manual.
Labels files are generated for @code{INFO_JS_DIR} and with @code{HTML_MATH}
set to @samp{mathjax} (@pxref{MathJax scripts}).
+@vindex USE_NEXT_HEADING_FOR_LONE_NODE
The @code{@@node} @@-commands are usually followed by a sectioning command,
which provides a heading for the node. In the default case, a node not
associated to a sectioning command but followed by a command like
@@ -18533,6 +18549,7 @@ have the node name used as heading in that case, set
@vindex PREFIX
@vindex SUBDIR
@vindex EXTENSION
+@vindex CASE_INSENSITIVE_FILENAMES
It is possible to specify the output file names with more control than
merely the command line option @option{--output} (@pxref{Invoking
@command{texi2any}}). The @code{PREFIX} customization
@@ -18550,6 +18567,8 @@ Furthermore, the customization variables
@code{TOP_FILE} override
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
@@ -18655,6 +18674,7 @@ know that no manual is installed locally.
@vindex HTMLXREF_MODE
@vindex HTMLXREF_FILE
@vindex EXTERNAL_CROSSREF_SPLIT
+@cindex HTML cross-references @subentry configuration customization
Customization variables can specify more precisely the HTML Xref Configuration.
In the default case, the file name used for HTML Xref configuration
is searched for in directories, and all the files found are used.
@@ -18670,6 +18690,7 @@ is considered to be split or monolithic based on the
splitting of the manual
being output. It is possible to set it explicitely, instead, with
@code{EXTERNAL_CROSSREF_SPLIT}.
+@cindex Cross-references customization, in HTML
It also is possible to 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
@@ -18677,6 +18698,10 @@ 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.
+@vindex TOP_NODE_FILE_TARGET
+@vindex EXTERNAL_DIR
+@vindex EXTERNAL_CROSSREF_EXTENSION
+@vindex BASEFILENAME_LENGTH
The file name used for the Top node in cross-references is set to
the @code{TOP_NODE_FILE_TARGET} customization variable value; default is
@file{index.html}. A base directory for external manuals is specified
@@ -18691,22 +18716,26 @@ base file name is changed by setting
@code{BASEFILENAME_LENGTH}.
@node Customization of Navigation and Headers
@subsection Customization of Navigation and Headers
+@vindex HEADERS
Headers with a navigation panel are output in the default case. if
@option{--no-headers} is used or the customization variable @code{HEADERS}
is unset, the navigation bar is only inserted at the beginning of
split files.
+@vindex USE_LINKS
In the default case, @code{<link>} elements are generated in the
HTML @code{<head>} to specify relationships between the HTML page
and other resources, for example the Top node, the next node or
the table of contents. Unset @code{USE_LINKS} to avoid those elements.
+@vindex SECTION_NAME_IN_TITLE
The @code{<title>} and the document description in @code{<head>}
are based on @code{@@settitle} (@pxref{@code{@@settitle}}).
If the manual is split, the node name is also added to this HTML title.
If @code{SECTION_NAME_IN_TITLE} is set, the argument of the associated
chapter structuring command is used instead of the node name.
+@vindex WORDS_IN_PAGE
When output is split at nodes (@pxref{HTML Splitting}), the
@code{WORDS_IN_PAGE} customization variable value specifies the approximate
minimum page length at which a navigation panel is placed at the bottom of a
@@ -18733,6 +18762,9 @@ page footers.
If set, a vertical navigation panel is used.
@end vtable
+@cindex Initialization file, HTML icon direction buttons
+@vindex ACTIVE_ICONS
+@vindex PASSIVE_ICONS
Setting @code{ICONS} is necessary but not sufficient to get icons for direction
buttons since no button image is specified in the default case.
The @code{ACTIVE_ICONS} and @code{PASSIVE_ICONS} customization
@@ -18748,6 +18780,9 @@ The generated HTML code may be modified in two way.
Firstly by specifying
broad features of the generated HTML and secondly by inserting
some HTML code in a few specific places.
+@vindex USE_XML_SYNTAX
+@cindex DOCTYPE customization
+@vindex DOCTYPE
In the default case, HTML is generated, but it is also possible to
generate XML compatible code, by setting @code{USE_XML_SYNTAX}. The main
difference is that @samp{/>} instead of @samp{>} closes elements with an
@@ -18756,6 +18791,9 @@ opening element, but no closing element, such as
@code{<img>} or @code{<link>}
To set the @dfn{DOCTYPE}, set the @code{DOCTYPE} customization variable.
The default is the HTML5 DTD-less simple DOCTYPE.
+@vindex USE_ISO
+@vindex USE_NUMERIC_ENTITY
+@vindex OUTPUT_CHARACTERS
In the default case, entities are used for doubled single-quote characters
(@pxref{Inserting Quotation Marks}), and @samp{---} and @samp{--}
(@pxref{Conventions}). Set @code{USE_ISO} to @samp{0} in the unlikely case
@@ -18765,17 +18803,21 @@ In the default case, textual entities are used when
possible. Set
Set @code{OUTPUT_CHARACTERS} to output accented characters based on
the output encoding instead of entities.
+@vindex NO_CUSTOM_HTML_ATTRIBUTE
In the default case, a custom attribute, as allowed by the standard, is
used to provide the target manual name in cross-references.
If it is not desirable, for example to generate strict XHTML, it is
possible to set @code{NO_CUSTOM_HTML_ATTRIBUTE} to prevent custom attributes to
be output.
+@vindex DEFAULT_RULE
+@vindex BIG_RULE
To change the HTML code for breaks (horizontal rule) inserted in various
contexts, set @code{DEFAULT_RULE},
used for most horizontal separators output in the resulting HTML,
and set @code{BIG_RULE} for the wider separator sometime used.
+@vindex COPIABLE_LINKS
Copiable links are output for link targets for the definition commands
(@pxref{Definition Commands}), table commands (@pxref{Two-column
Tables}) where an index entry is defined and headings. A link appears
@@ -18921,6 +18963,8 @@ default false.
@node HTML Customization for Math
@subsection HTML Customization for Math
+@vindex HTML_MATH
+@cindex HTML output @subentry math @subentry customization
Diverse methods can be used to render math in HTML (@pxref{Inserting Math}).
The is controlled by the @code{HTML_MATH} customization variable
value. In the default case, the customization variable is unset
@@ -18949,9 +18993,9 @@ a cache file to avoid redoing translation HTML if
already done.
@item mathjax
@anchor{MathJax scripts}
-Inserts references in the output files to MathJax scripts to format the
-material. The MathJax option requires JavaScript
-to be enabled in the browser to work.
+Inserts references in the output files to MathJax scripts to format
+mathematcs. The MathJax option requires JavaScript to be enabled in the
+browser to work.
MathJax handles @LaTeX{} math, including @TeX{}
math compatible with @LaTeX{} commonly used. Some specific constructs
@@ -18980,6 +19024,7 @@ output directory, with @samp{_tex4ht} in their name.
@end table
+@vindex CONVERT_TO_LATEX_IN_MATH
In the default case, with @code{CONVERT_TO_LATEX_IN_MATH} undefined,
setting @code{HTML_MATH} also sets @code{CONVERT_TO_LATEX_IN_MATH}.
In that case Texinfo @@-commands inside @code{@@math} and @code{@@displaymath}
@@ -18987,7 +19032,6 @@ are converted to @LaTeX{}, before converting the
@code{@@math} or
@code{@@displaymath} to HTML.
-
@node @@-Command Details
@nodedescription Details of the Texinfo @@-commands.
@appendix @@-Command Details
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- branch master updated: * doc/texinfo.texi (Menus): HTML menus are also automatically generated.,
Patrice Dumas <=