21.3 HTML CSS ¶

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

By default, some CSS code is included to better implement the appearance of some Texinfo environments. For example:

pre.display { font-family:inherit }

The above tells the web browser to use the same font as the main document inside ‘<pre>’ elements used for @display environments. By default, the HTML ‘<pre>’ command uses a monospaced font.

Please see the reference above for a full explanation of CSS.

You can influence the CSS in the HTML output with two texi2any 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.

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 first line may be a ‘@charset’ directive. If present, this directive is used to determine the encoding of the CSS file. The line is not copied into the output.

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 they are handled.

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. 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";

The crucial characters are the ‘@’ at the beginning and the semicolon terminating the directive. When reading the CSS file, any such ‘@’-directive is simply copied into the output, as follows:

• If file contains only normal CSS declarations, it is included after the 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 the default CSS is included. If you need to override the default CSS from an ‘@import’, you can do so with the ‘! important’ CSS construct, as in:

  pre.example { font-size: inherit ! important }
  

• If file contains both ‘@import’ and inline CSS specifications, the ‘@import’’s are included first, then default CSS, and lastly the inline CSS from file.
• Any @-directive other than ‘@import’ and ‘@charset’ is treated as a CSS declaration, meaning the default CSS is included and then the rest of the file is prepended.

If the CSS file is malformed or erroneous, the output is unspecified. The meaning of the CSS file is not interpreted in any way; the special ‘@’ and ‘;’ characters are looked for the text is blindly copied 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, texi2any has many user-definable customization variables with which you can influence the HTML output. See Customization Variables.