Re: makeinfo and CSS

[Karl Berry]

    Yes, but it is not only easy to find the *start* of an @import rule,
    but also its end, because it must be a ";" (you must skip one string
    though).  Many @import rules may be present, but nothing inbetween,
    not even other @... rules.

I just implemented --css-include in this way.  Thanks for all the
information.  The patch probably won't apply as-is to the 4.5 sources,
so I won't bother including it here.  I plan to make another pretest
shortly.  Torsten, if you'd like to be on texinfo-pretest list where
pretests are announced/discussed, just let me know.

Meanwhile, here is the new section I wrote in the manual about it.
Please tell me if I said anything wrong or stupid :).

Thanks,
karl


@node HTML CSS
@subsubsection HTML CSS
@cindex HTML, and CSS
@cindex CSS, and HTML output
@cindex Cascading Style Sheets, and HTML output

Cascading Style Sheets (CSS for short) is a network standard for
influencing the display of HTML documents:
@uref{http://www.w3.org/Style/CSS/}.

By default, @command{makeinfo} includes a few simple CSS commands to
better implement the appearance of some of the environments.  Here is
a couple of them:

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

A full explanation of CSS is (far) beyond this manual; please see the
references above.  In brief, however, this specification tells the web
browser to use a `smaller' font size for @code{@@smalldisplay} text,
and to use the `inherited' font (generally a regular roman typeface)
for both @code{@@smalldisplay} and @code{@@display}.  By default, the
HTML @samp{<pre>} command uses a monospaced font.

You can influence the CSS in the HTML output with the
@address@hidden option to @command{makeinfo}.  This
includes the contents @var{file} in the HTML output, as you might
expect.  However, the details are somewhat tricky, to provide maximum
flexibility.

@cindex Comments, in CSS files
The CSS file may begin with so-called @samp{@@import} specifications,
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 @command{makeinfo} handles them.

There can be more than one @samp{@@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 @samp{/*
... */}, as in C.)  An @samp{@@import} specification must be in one of
these two forms:

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

As far as @command{makeinfo} is concerned, the crucial character is
the semicolon terminating the declaration.  When reading the CSS file,
it considers everything between an @samp{@@} and a @samp{;} to be an
@samp{@@import}, and processes the file as follows:

@itemize
@item If @var{file} contains only normal CSS specifications, it is
included after @command{makeinfo}'s default CSS, thus overriding it.

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

@item If @var{file} contains both @samp{@@import} and inline CSS
specifications, the @samp{@@import}'s are included first, then
@command{makeinfo}'s defaults, and lastly the inline CSS from
@var{file}.
@end itemize

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