I've started writing a node in the Texinfo manual with documentation
of aspects of the HTML output of texi2any that would be useful for
browsing of local installed manuals.
I mentioned the idea of this in the TODO.HTML file.
The draft focuses on two aspects: intermanual links and indices. It doesn't
focus on any third aspect, because I didn't think of one: I could have missed
it, though.
When I get the change I am going to try to look through info.js etc. in
more detail to see what it actually relies on.
Here's the current Info node for ease of reference:
File: texinfo.info, Node: HTML Output Description, Next: HTML Splitting,
Prev: HTML Translation, Up: Generating HTML
22.2 Description of the HTML output from ‘texi2any’
===================================================
As stated in the previous section, the HTML output by ‘texi2any’ is
intended to be usual HTML that is widely portable. The result would be
suitable for uploading to a web server for a user to read in a web
browser.
However, in this section, we attempt to describe some aspects of the
‘texi2any’ HTML output that would potentially be useful for a more
specialized program used for browsing HTML documentation, especially one
installed locally on a user's computer.
We expect to make these aspects into requirements for ‘texi2any’ that
should be held to in future Texinfo releases.
Warning
This is a draft section and details could change. Please feel free
to email <[email protected]> with any feedback that you feel could be
helpful.
Computer code that avails itself of these aspects of the HTML output
includes ‘info.js’, the augmented browsing interface implemented in
JavaScript that is output with the ‘INFO_JS_DIR’ variable (*note
JavaScript Interface and Licenses::), and the experimental/demonstration
program ‘infog’ (using an embedded WebKitGTK browser) which is under the
‘infog/’ subdirectory of the Texinfo development repository
(<https://savannah.gnu.org/git/?group=texinfo>). However, the Texinfo
developers have limited ability to push development of these further,
and widespread adoption of either appears extremely unlikely at this
stage.
We document these aspects here in the hope that they may be used more
widely in programs reading locally installed HTML documentation. (1)
Some of these aspects are intended to allow replicating the benefits
of the Info format (*note Info Files::) while getting the full benefits
of HTML:
Cross-references to other Texinfo manuals
-----------------------------------------
Links to other Texinfo manuals are made with the ‘<a>’ tag, with the web
location of the target in the ‘href’ attribute, and the name of the
target Texinfo manual (corresponding to the fourth argument to ‘@xref’;
see *note Four and Five Arguments::) is placed in the ‘data-manual’
attribute.(2)
For example, here is a possible link to the ‘What information is
listed’ node within the ‘coreutils’ manual:
<a data-manual="coreutils"
href="https://www.gnu.org/software/coreutils/manual/coreutils#What-information-is-listed";>
Verbose listing
</a>
(*FIXME:* use a shorter example that fits in the page width)
The value of the ‘data-manual’ attribute could be used by a help
browsing program to search for the manual on the user's computer, rather
than using the target in ‘href’. This would allow for manuals to
installed in multiple locations and for a search path to be used,
similar to ‘INFOPATH’ in the ‘info’ program (*note (info-stnd)Invoking
Info::) or ‘MANPATH’ used by the ‘man’ program.
The node name (or anchor name) comes from the end of the address in
the ‘href’ value. (*FIXME:* check if we should use the fragment
‘#What-information-is-listed’ or if we need a file name from a reference
to a manual split by node.)
Indices
-------
In the main table of contents (in the ‘Top’ node in ‘index.html’), links
to the nodes containing indices are annotated with the ‘rel’ attribute.
For example:
<a id="toc-Index-of-Command-Line-Options-1"
href="#Index-of-Command-Line-Options"
rel="index">
Appendix H Index of Command Line Options
</a>
The table of contents is contained with a ‘<div>’ element with a
‘class’ attribute equal to ‘contents’.
This aids in identifying index nodes, which can be used to provide an
index search function to users.
(*FIXME:* ‘info.js’ doesn't seem to check ‘rel’ attribute?)
Within each index node, each index entry occurs as an ‘<a>’ element
inside an element with a class of ‘printindex-index-entry’. For
example:
<td class="printindex-index-entry">
<a href="A4-Paper.html#index-A4-paper_002c-printing-on">
A4 paper, printing on
</a>
</td>
Secondary or tertiary index entries appear as ‘<a>’ elements inside
an element with the class ‘printindex-index-subentry-level-1’ or
‘printindex-index-subentry-level-2’ respectively. These occur after an
entry for the superior entry or other subentries at the same level. For
example, the following shows a primary entry, followed by a secondary
entry, followed by a tertiary entry. In this example, only the tertiary
entry has a link:
<tr>
<td class="printindex-index-entry">
asterisk (<code class="code">*?</code>)
</td>
<td></td>
</tr>
<tr>
<td class="printindex-index-entry index-entry-level-1">
<code class="code">*?</code> operator
</td>
<td></td>
</tr>
<tr>
<td class="printindex-index-entry index-entry-level-2">
<a
href="Regexp-Operator-Details.html#index-asterisk-_0028_002a_003f_0029-_002a_003f-operator-as-regexp-operator">
as regexp operator
</a>
</td>
<td class="printindex-index-section">
<a href="Regexp-Operator-Details.html">
Regexp Operator Details
</a>
</td>
</tr>
(*FIXME:* use shorter examples that fit in the page width)
The index ‘<a>’ links are to the output file and anchor (with a name
beginning with ‘index-’) containing the target of the index entry.
(*FIXME:* check since what version of Texinfo these classes have been
used.)
---------- Footnotes ----------
(1) In our opinion, the benefits of locally installed documentation
are often ignored. It is reliable, does not depend on an Internet
connection, respects the user's privacy, and matches the version of
software a user has installed.
(2) Exception: the ‘data-manual’ attribute is not output if the
‘NO_CUSTOM_HTML_ATTRIBUTE’ variable is set. *Note HTML Features
Customization::.
