4.6 Simple Customization of CSS Rules and Imports

CSS in HTML output can already be modified with command line options (see HTML CSS in Texinfo) and customization options such as NO_CSS and INLINE_CSS_STYLE.

Information on static CSS data used in conversion and some control over the CSS output is possible. The information is about CSS rules lines and CSS import lines obtained from parsing --css-include=file files, as described in HTML CSS in Texinfo, and CSS style rules associated with HTML elements and class attributes used in the conversion to HTML. The CSS style rules selectors are, classically, element.class strings with element an HTML element and class an attribute class associated to that element.

The function used are css_get_info to get information and css_add_info to modify:

Function: $converter->css_get_info ($specification, $css_info)
Function: $converter->css_add_info ($specification, $css_info, $css_style)

Those functions can only be used on a converter $converter, from functions registered and called with a converter. $specification is 'rules' to get information on or set information for CSS rules lines and 'imports' to get information on or set information for CSS import lines. Any other value for $specification corresponds to CSS style rules associated with HTML elements and class attributes selectors.

With css_get_info, if $specification is set to 'rules' or 'imports', the corresponding arrays are returned. Otherwise, if $css_info is undef, a hash reference with all the CSS rules selector as keys and the corresponding rules as values is returned. If $css_info is defined, it is considered to be a CSS rule selector and the corresponding CSS style is returned, or undef if not found.

With css_add_info, $css_info is an additional entry added to CSS rules lines if $specification is set to 'rules' or an additional entry added to CSS import lines if $specification is set to 'imports'. Otherwise, $css_info is a CSS rule selector and the associated style rule is set to $css_style.

Some examples of use:

my @all_included_rules = $converter->css_get_info('rules');
my $all_default_selector_styles = $converter->css_get_info('styles');
my $titlefont_header_style = $converter->css_get_info('styles',
                                                      'h1.titlefont');

$converter->css_add_info('styles', 'h1.titlefont', 'text-align:center');
$converter->css_add_info('imports', "\@import \"special.css\";\n");

Note that the CSS selectors and associated style rules that can be accessed and modified will not necessarily end up in the HTML output. They are output only if the HTML element and class corresponding to a selector is seen in the document. See Customizing the CSS lines.

How to run code during the conversion process is described later (see Init File Calling at Different Stages). The simplest way to use the css_add_info function would be to use a function registered for the ‘structure’ stage:

sub my_function_set_some_css {
  my $converter = shift;

  $converter->css_add_info('styles', 'h1.titlefont',
                           'text-align:center');
  # ... more calls to  $converter->css_add_info();
}

texinfo_register_handler('structure', \&my_function_set_some_css);

See Customizing the CSS lines for even more control on CSS lines output.