texinfo: HTML CSS

Generating HTML

HTML Xref

HTML Splitting

Back to Software Index

24.3 HTML CSS
=============

Cascading Style Sheets (CSS for short) is an Internet standard for
influencing the display of HTML documents: see
<http://www.w3.org/Style/CSS/>.

  By default, 'makeinfo' includes a few simple CSS commands to better
implement the appearance of some Texinfo environments.  Here are two of
them, as an example:

     pre.display { font-family:inherit }
     pre.smalldisplay { font-family:inherit; font-size:smaller }

  A full explanation of CSS is (far) beyond this manual; please see the
reference above.  In brief, however, the above tells the web browser to
use a 'smaller' font size for '@smalldisplay' text, and to use the same
font as the main document for both '@smalldisplay' and '@display'.  By
default, the HTML '<pre>' command uses a monospaced font.

  You can influence the CSS in the HTML output with two 'makeinfo'
options: '--css-include=FILE' and '--css-ref=URL'.

  The option '--css-ref=URL' adds to each output HTML file a '<link>'
tag referencing a CSS at the given URL.  This allows using external
style sheets.  You may find the file
'texi2html/examples/texinfo-bright-colors.css' useful for visualizing
the CSS elements in Texinfo output.

  The option '--css-include=FILE' includes the contents FILE in the HTML
output, as you might expect.  However, the details are somewhat tricky,
as described in the following, to provide maximum flexibility.

  The CSS file may begin with so-called '@import' directives, which link
to external CSS specifications for browsers to use when interpreting the
document.  Again, a full description is beyond our scope here, but we'll
describe how they work syntactically, so we can explain how 'makeinfo'
handles them.

  There can be more than one '@import', but they have to come first in
the file, with only whitespace and comments interspersed, no normal
definitions.  (Technical exception: an '@charset' directive may precede
the '@import''s.  This does not alter 'makeinfo''s behavior, it just
copies the '@charset' if present.)  Comments in CSS files are delimited
by '/* ... */', as in C.  An '@import' directive must be in one of these
two forms:

     @import url(http://example.org/foo.css);
     @import "http://example.net/bar.css";

  As far as 'makeinfo' is concerned, the crucial characters are the '@'
at the beginning and the semicolon terminating the directive.  When
reading the CSS file, it simply copies any such '@'-directive into the
output, as follows:

   * If FILE contains only normal CSS declarations, it is included after
     'makeinfo''s default CSS, thus overriding it.

   * If FILE begins with '@import' specifications (see below), then the
     'import''s are included first (they have to come first, according
     to the standard), and then 'makeinfo''s default CSS is included.
     If you need to override 'makeinfo''s defaults from an '@import',
     you can do so with the '! important' CSS construct, as in:
          pre.smallexample { font-size: inherit ! important }

   * If FILE contains both '@import' and inline CSS specifications, the
     '@import''s are included first, then 'makeinfo''s defaults, and
     lastly the inline CSS from FILE.

   * Any @-directive other than '@import' and '@charset' is treated as a
     CSS declaration, meaning 'makeinfo' includes its default CSS and
     then the rest of the file.

  If the CSS file is malformed or erroneous, 'makeinfo''s output is
unspecified.  'makeinfo' does not try to interpret the meaning of the
CSS file in any way; it just looks for the special '@' and ';'
characters and blindly copies the text into the output.  Comments in the
CSS file may or may not be included in the output.

  In addition to the possibilities offered by CSS, 'makeinfo' has many
user-definable customization variables with which you can influence the
HTML output.  Note: Customization Variables.