The gendocs.sh script that is part of Gnulib by default includes a reference
to a CSS file for the HTML output that it generates for Texinfo manuals.
The CSS file is here:
https://www.gnu.org/software/gnulib/manual.css
I have checked the appearance of Texinfo's own manual with this stylesheet.
There are no major problems that I could see, but there were a few
minor problems. I list the four problems I found below.
------------------------------------------------------
* @group creates a thin blank line on the coloured background in @example.
This is due to a margin on the div.group element.
This appears to be set in a rule in the included file
https://www.gnu.org/style.css:
/* For make, gawk, bison, etc. */
div[class*="example"] > pre + pre, div[class*="example"] > .group {
margin: 3px 0;
}
The @group command is for affecting page breaks, which make no sense
in an HTML file, and so @group should have no user-visible effect in HTML.
* The output of @acronym is underlined and the mouse cursor changes when
over the text, even though clicking it does nothing.
This is due to a rule in 'style.css':
abbr,acronym {
font-variant: normal;
border: 0;
border-bottom:1px dotted #000;
text-decoration: none;
cursor:help;
}
Presumably, hovering over the text produces a pop-up with the expansion
of the acronym if this expansion is given as the second argument to @acronym.
But there's no guarantee that such an argument was given.
* The main symbol on a definition line from a command such as @deftypefn
is not distinguishable due to everything being bold. Only the name of
the defined symbol should be in bold.
This is due to the setting for dt in 'style.css':
h1, h2, h3, h4, h5, h6, strong, dt, th { font-weight: bold; }
The output for this has changed over the last couple of releases:
it's possible that the main symbol is also output with a larger font
size, but with the current development version, a consistent font size
is used for the entire definition line.
* The output of @displaymath has a blue background. This is appearently
not intentional, as it comes from these rules in 'style.css':
/* Backgrounds should more or less correspond to what the <pre> is used for,
but this varies a lot across manuals. */
pre[class^="example"], pre[class^="lisp"] {
background: #f9f6ed; /* very light tan */
}
pre[class^="display"] {
background: #e7eef9; /* light blue */
}
pre[class*="example"], pre[class*="lisp"], pre[class^="display"],
pre.verbatim, div[class*="example"], table.cartouche {
border-radius: .3em;
}
Evidently only @display was intended to be targeted here, but @displaymath
is included by the CSS attribute selector pre[class^="display"].
(in Texinfo 7.1, this was output with <div> not <pre>, so the rule
did not apply).)
------------------------------------------------------
I've attached files to show these problems.
* css-fail.texi is the Texinfo source
* css-fail.html does reference the Gnulib CSS and was generated with:
./texi2any --html --css-ref=https://www.gnu.org/software/gnulib/manual.css \
css-fail.texi --no-split -c HTML_MATH=mathjax \
-c MATHJAX_SCRIPT=https://www.gnu.org/software/texinfo/manual/tex-svg.js
* no-css-win.html does not have the Gnulib CSS and was generated with:
./texi2any --html css-fail.texi --no-split -c HTML_MATH=mathjax \
-c MATHJAX_SCRIPT=https://www.gnu.org/software/texinfo/manual/tex-svg.js \
-o no-css-win.html
I used the development version of texi2any.
As you can see, all the problems appear to come from style.css, rather
than Gnulib's additions in manual.css.
There's no information on who if anyone maintains
https://www.gnu.org/style.css. I assume it would be the GNU webmasters.
I'm undecided whether to use this CSS file for the Texinfo project manuals
on the GNU website. It's possible we will use a plainer CSS file or
continue to use the texi2any defaults.
css-fail.texi
Description: TeXInfo document
Title: Untitled Document
Title: Untitled Document
