Products         News         Downloads         Licensing         Shop         Support    

 DocFlex Technology
Overview
Features
Documentation
Template Components
Element Iterator (details)
Usage of CSS in generated HTML
 DocFlex/XML
Overview
Features
Documentation
XSDDoc
WSDLDoc
Integrations
 DocFlex/Javadoc
Overview
Documentation
Basic Templates
JavadocPro
Examples
Tutorials
 DocFlex/Together
Overview
Examples
Basic Templates
Documentation
Tutorials
 Try
Downloads
Registration
Trial License
 Use
Licensing
Shop
Support
 Company
News
Products
Customers
About Us
Imprint
Legal
Contact
Links
 

DocFlex Technology - Documentation - Usage of CSS in generated HTML

  1. HTML Generator Options for CSS
  2. Generated CSS Rules
  3. Generated Style Sheets
  4. Custom CSS Rules / CSS File
  5. Appendix

1.  HTML Generator Options for CSS

HTML Option Inspector

Option/Group

Name / Type / Description

Generate style sheet file

html.output.css.file : boolean

Specify whether to generate the external CSS file (global style sheet).

When this option is selected (true), an external CSS file will be generated, which is placed in the output destination directory typically under the name 'stylesheet.css'. Most of the HTML formatting settings used in the generated documentation will be held in this file referenced from each HTML document via a <link> tag, e.g.:

<link rel="stylesheet" type="text/css" href="../../stylesheet.css">
When this option is unselected (false), no external style sheet file will be generated. In that case, all CSS rules used in the generated HTML will be defined locally within those HTML files themselves, inside <style> element.

CSS pattern file

html.output.css.file.pattern : file pathname

Specify a CSS pattern file to frame the generated global style sheet into your own CSS file.

Include anonymous rules

html.output.css.file.anonymRules : boolean

Specify whether all generated anonymous CSS rules must be stored in the external CSS file (global style sheet).

Anonymous CSS rules are CSS rules generated from the formatting settings specified on template components. They are called “anonymous” because these are basically sets of inline CSS properties initially generated for particular HTML tags and, then, moved to a style sheet to eliminate their repeating across the HTML file(s). Now, only class selectors assigned to those CSS rules are specified in the HTML tags (instead of the original CSS properties). But the class selectors are generated automatically, which depends on how early a particular CSS property set was registered in the style sheet. That makes them completely unpredictable and dependent on the data being documented, which prohibits substituting the anonymous rules with any custom ones.

When this option is selected (true), all anonymous rules generated across all generated HTML files will be collected in the global style sheet (which is printed further as the external CSS file). That produces the most compact documentation files, since many anonymous rules repeat themselves across different HTML document. So, it is the default setting.

When this option is unselected (false), the anonymous rules will be generated and stored locally by each HTML document where they are used. The global style sheet won't include anonymous rules. You may want this in the following situations:

  • Since anonymous CSS rules (i.e. their class selectors) are generated completely unpredictably, even a little change in the input data, which would affect just a single HTML file, may cause a great disturbance in the naming of all anonymous rules stored in the style sheet used by that HTML file. When it is the global style sheet, all HTML files, where any anonymous rules are used, will change too.

    This won't be good, for instance, when you store your generated documentation in a repository system that updates only changes of files relative to the previous version. Then, a massive disturbance in the generated HTML (caused by just a few changes in the input data) will lead to a massive update of your repository (particularly in the case of very large documentation). So, keeping all anonymous rules locally would help!

  • If you substitute all generated default and named CSS rules with your custom CSS rules and exclude all anonymous rules from the global style sheet, its content effectively becomes static. Then, you can simply use a CSS pattern file as a complete your CSS file.

Generate name rules

html.output.css.namedRules : enum {"none", "all", "selected"}

Specify whether to generate named CSS rules.

Named CSS rules are CSS rules generated from the formatting styles defined in templates. When such a style is assigned to a template component, the HTML tags generated by that component can be assigned with the CSS rule generated from that style. The class selector assigned to that CSS rule is specified in the template style itself (or derived from its name). Therefore, it has a constant (predictable) relationship with both the particular CSS property set produced from that style and the particular output structures where that CSS rule is applied. This opens a possibility to substitute the generated named CSS rules with the custom ones.

Please note that named CSS rules are not required for proper HTML output and will only increase its size. You need named rules only when you want to style the generated HTML documentation with your own CSS properties/rules.

Possible Values:
"none"
Disable the generation of named CSS rules.
"all"
Generate all named CSS rules possible.

When this setting is selected, almost all template formatting styles involved in the generation of the particular HTML output will be rendered into named CSS rules. See also: Which template styles can produce named rules?

"selected"
Generate only those named CSS rules, which come from the template formatting styles with the selected "CSS | Allow named rule" property.

See also: Controlling Named Rules

Include descriptions

html.output.css.namedRules.descriptions : boolean

Specify whether to add the descriptions of template formatting styles to the named CSS rules generated from them.

When this option is selected (true), the descriptions of template styles (specified in templates) will appear as CSS comments before the definitions of the respective named CSS rule generated from those styles. For example:

/*
 * Used for "About" section added at the bottom
 * of each generated document.
 */
span.about { font-family: "Arial", sans-serif; font-size: 84%; }
Such descriptions may help you to understand the purpose of particular named CSS rules and to decide whether and how to substitute them.

When this options is unselected (false), no descriptions will be added.

Custom rule file

html.output.css.namedRules.customRuleFile : file pathname

Specify a (CSS) file with custom definitions for some of the automatically generated default and named CSS rules.

For more details, please see: How to substitute generated CSS rules with custom ones?

Units

html.output.css.units : enum {"relative", "points", "pixels"}

Specify measurement units used in the generated HTML.

This applies to font sizes and most of length values (like spacing, margins, paddings etc.), which are specified as properties of CSS rules generated directly from the formatting properties of template components and template formatting styles.

Note: A few length values are always specified in pixels (e.g. border width), because otherwise their effect would be highly unpredictable.

Possible Values:
"relative"
This is the default setting. All font sizes are specified in percents relatively to the document base font size (determined by the HTML browser). Other things like spacings, margins, paddings etc. are set in em units, which are also interpreted against the base font size.

All values are computed from the corresponding formatting properties specified in templates according to the following formulas (for em and % values correspondingly):

valuetpl / defaultFontSizetpl
(valuetpl / defaultFontSizetpl) * 100
where
valuetpl  -  the property value specified in the template
defaultFontSizetpl  -  the template default font size, which it is one provided by the default paragraph style in the main template
Relative units are considered most convenient for viewing HTML documentation in web-browsers. However, there is one problem. According to CSS, the effective value of a CSS property specified in relative units is actually computed against the font size inherited from the parent element where the property is applied. This creates the problem of compounding, which requires special efforts to work around. For more details, see Appendix | The problem with relative length units.
"pixels"
All font sizes, spacings, margins, paddings etc. will be set in pixels (px).

These values are produced from the corresponding formatting properties specified in templates according to the formula:

(valuetpl / defaultFontSizetpl) * baseFontSizepx
where
valuetpl  -  the property value specified in the template
defaultFontSizetpl  -  the template default font size, which it is one provided by the default paragraph style in the main template
baseFontSizepx  -  the value of “Base font size” option for pixels
"points"
All font sizes, spacings, margins, paddings etc. will be set in points (pt).

These values are produced from the corresponding formatting properties specified in templates, which are typically set in points too. But the point values that get in the generated HTML (i.e. CSS rules) are not exactly the same as those specified in templates. Rather, they are computed according to the formula:
(valuetpl / defaultFontSizetpl) * baseFontSizept
where
valuetpl  -  the property value specified in the template
defaultFontSizetpl  -  the template default font size, which it is one provided by the default paragraph style in the main template
baseFontSizept  -  the value of “Base font size” option for points

Base font size

This is actually not a single but two different options corresponding pixel and point units. For relative units this option is not available.

Base font size
(for pixels)

html.output.css.units.baseFontSize.pixels : integer (nonnegative)

Specify the base font size in case of pixel units. The default value is 16 (px).

Base font size
(for points)

html.output.css.units.baseFontSize.points : number (nonnegative)

Specify the base font size in case of point units. The default value is 12 (pt).

2.  Generated CSS Rules

All informative content of HTML files (i.e. HTML tags and text) is generated by various template components through their interpretation.

When a template component is interpreted, it produces a piece of HTML output (which is typically represented by a certain HTML element). All formatting of that output comes in the form of CSS rules. The rules themselves are placed in the style sheet and the class selectors associated with them are specified in HTML tags.

The CSS rules generated by DocFlex fall into three categories:

  1. Anonymous Rules
  2. Named Rules
  3. Default Rules
Those categories determine how the rules are produced, applied and what you can do about them (see Custom CSS Rules / CSS File).

Anonymous Rules

When a template component is interpreted, every formatting property specified on it is rendered with a certain CSS property. So, a list of CSS properties is created.

Example:

The formatting properties specified on a template components may look this:

which will be rendered into the set of corresponding CSS properties:
font-family: "Arial", sans-serif; font-size: 130%; font-weight: bold; color: blue
Further, such a set must be applied to the HTML element generated by the component, which could be done inline. e.g.:
<span style="font-family: "Arial", sans-serif; font-size: 130%; font-weight: bold; color: blue"> ... </span>
That would produce a valid HTML with all formatting in place.

But, the same template component may generate another piece of output and many more. So, the same inline list of CSS properties will be repeating by every of them. That would potentially bloat the generated HTML file quite a lot. (Moreover, different template components may also produce equal CSS property sets.)

To avoid that repeating, each set of CSS properties is specified only once in the form of a CSS rule, which is placed in a style sheet under a certain class name (selector), like this (here 'aXXX' is the rule's class name):

<style>
  span.aXXX { font-family: "Arial", sans-serif; font-size: 130%; font-weight: bold; color: blue }
</style>
So, now only the class name will be added to each HTML element where the given CSS property set is applied:
<span class="aXXX"> ... </span>
The rule's class name is used here only for linking purpose. So, it is generated automatically just to be unique in the given style sheet (and as short as possible).

Such CSS rules, which are produced by the generator automatically in order to replace with them the inline CSS properties, we shall call anonymous rules. That's because the class names assigned to those CSS rules, besides being meaningless, have no constant relation with the particular lists of CSS properties they represent.

Exactly how such class names are generated depends on the data being processed. Another HTML document generated by the same template may contain similar anonymous CSS rules, but associated with different class names. Even when a global style sheet is maintained, the rule class names may be different when you generate another documentation for a different data source.

That prohibits using any custom CSS rules to replace the anonymous ones. If you need to change something in the formatting of the generated HTML, you have to edit the corresponding templates and rely only on the formatting capabilities provided by DocFlex (via the template language and its rendering by the HTML generator).

That problem has been solved with the introduction of named CSS rules.

Named Rules

Since DocFlex/XML 1.9 (DocFlex/Javadoc 1.7), it is possible to associate with particular CSS rules some constant (and meaningful) class names. That is, whenever some HTML documentation is generated by a given template set, a particular CSS rule (i.e. a specific set of CSS properties) used across all generated HTML files will be always associated with the same CSS class name.

Such CSS rules associated with constant class names that are specified in templates, we shall call named rules.

Here is how it works.

CSS rules derived from template formatting styles

Template formatting styles are not CSS styles. Rather, they are another type of definitions stored in templates (besides components):
Basically, a template formatting style is a bunch of component formatting properties:
which is given a certain name:
By that name the style can be assigned to any component in the template. When a component has a formatting style, those formatting properties not specified directly on the component are inherited from the style.

Originally, template formatting styles were modeled on RTF styles. When RTF output is generated, a template formatting style would be rendered with a corresponding RTF style.

Let's look how template formatting styles are used to generate named CSS rules.

Suppose, a component C is assigned with a template formatting style 'Highlighted Text' and there is no other formatting properties directly specified on it:

When C is interpreted, the 'Highlighted Text' style will produce a CSS rule encoding all formatting properties specified in that style. The rule will be assigned with the 'highlight' class name and registered in the style sheet:
<style>
  span.highlight { color: #EE0000 }
</style>
That class name will be used to format the HTML output of the component:
<span class="highlight"> ... </span>

Where does CSS class name come from?

The class name (selector) assigned to a named CSS rule comes from the corresponding template formatting style, by which the rule is generated. The rule class name must be specified with the "CSS | Class name" property in the style definition:
When a template formatting style has no specified "CSS | Class name" property, the valid class selector will be generated automatically from the style name.

Any template formatting style has a certain (primary) name, by which it is identified in the template. That name may be a rather long string with spaces, which is unsuitable for immediate use as a CSS class name. But a valid CSS class name may be produced automatically from that primary name using some conversion.

For example, the automatically generated CSS class name for the style shown on the screenshot will be "Highlighted-Text".

Multiple named rules with the same class selector

As it was said early, named rules are generated from template formatting styles, which have not been modeled on CSS and do not conform to it perfectly.

That means, some template styles cannot be expressed with a single CSS rule. Rather, they must be rendered with several CSS rules applied to different HTML elements nested in each other. Such multiple CSS rules (produced from the same template style) will still have the same class name (specified in the style). So, you can substitute all of them with your custom rules as well.

In fact, there are quite a few specific situations when multiple named rules with the same class selector are produced:

  • Ambiguous formatting properties

    Some formatting properties specified in templates have no direct analogues in CSS. For example, there is no special CSS property for background color of text. Of course, CSS has 'background-color' property, but when it is applied to a particular HTML element, it will color the whole object described by that element. For instance, when that is a <div>, the entire strip on the page will be colored - not just the text contained in it!

    In the following flash movie it is explained in full details (click on the picture):

  • Property conflicts caused by relative units

    Another problem arises, when relative units (for font sizes and lengths) are used. Then, the CSS rule like this (which might be generated from a template paragraph style 'heading'):

    div.heading font-family: "Arial", sans-serif; font-size: 90%; font-weight: bold; text-decoration: none; color: black; margin-top: .58em; margin-bottom: .25em; white-space: nowrap; }
    would not produce the top and bottom margins as intended in the template, because the values for those margins specified in the rule would be interpreted not against the document base font size, but against a new font size (reduced to 90%), which comes from the rule itself.

    Of course, the margins may be corrected according to that local font size too. But such tricks would complicate everything enormously.

    To work around those problems, each template paragraph styles is rendered with two named CSS rules: one for paragraph properties and another one for text properties. For example:
    div.heading  {  margin-top: .58em; margin-bottom: .25em; white-space: nowrap; }
    span.heading font-family: "Arial", sans-serif; font-size: 90%; font-weight: bold; text-decoration: none; color: black; }
    and here is how those rules are applied:
    <div class="heading"><span class="heading">Heading Text</span></div>
    See also:

  • Blended-in hyperlinks

    Some hyperlinks must not be too prominent. That is, they must look the same as the normal text, yet have something indicating the hyperlink (e.g. underlining). Another possibility is that the hyperlink must be hidden completely, so it appears as ordinary text all the time, yet reveals itself when the mouse cursor hovers over it. Both effects can be achieved by formatting the hyperlink as normal text and adding to it some extra-formatting (indicating the link either constantly or only during the mouse hovering).

    Formatting of a hyperlink as normal text means applying to the <a> element the same CSS properties as for the normal text and having those properties override any default hyperlink formatting.

    This is achieved by specifying that the CSS rule for text is also applicable for <a> elements. In the following example, two named CSS rules are produced from the same template formatting styles 'heading':

    /* CSS rule to format the heading paragraph */
    div.heading margin-top: .58em; margin-bottom: .25em; white-space: nowrap; }

    /* CSS rule for both normal text and hyperlinks blended into it */
    span.heading, a.heading font-family: "Arial", sans-serif; font-size: 90%; font-weight: bold; text-decoration: none; color: black; }

    /* CSS rule to indicate a hyperlink when mouse hovering */
    a:hover.link { text-decoration: underline; }
    Now, the HTML code for a blended-in hyperlink will look like this:
    <div class="heading">
      <a ref="..." class="heading link">Heading Text/Link</a>
    </div>
    
    In the following flash movie you can see how this is programmed in a real doc-generator (click on the picture):

Named + anonymous rules

So far, we discussed a situation when all formatting properties of a template component come from a formatting style (e.g. 'Highlighted Text') assigned to it. That will produce a named CSS rule ('highlight') applied to the component's HTML output.

But what will happen when, besides the style 'Highlighted Text', the component has other formatting properties directly specified on it? For example, the bold font:

Then, those properties will produce an additional CSS rule, now anonymous one, with an automatically-generated class name (e.g. 'aXXX'). So, the style sheet now will include two rules:
<style>
  span.highlight { color: #EE0000 }
  span.aXXX { font-weight: bold }
</style>
Both class name will be applied in the component's HTML output:
<span class="highlight aXXX"> ... </span>
The ordering of the rules in the style sheet is important! Since formatting properties specified directly on the template component override those defined in the template formatting style, to have the same effect in HTML, the CSS properties defined in the anonymous rule must override similar properties found in the named rule (generated from the style). This works only when the anonymous rule appears in the style sheet later (below) the named one.

Named + named + anonymous rules

Now, let's look into even more complex situation, where, along with the formatting properties directly specified on the component, two formatting styles are involved: one for paragraphs and one for text.

The following Area Section (shown on the screenshot) would generate a certain message. It is a paragraph filled with a bright color and surrounded by the border to highlight the whole message. The message text is formatted mostly with the same font and color, however, a part of it is highlighted with a different color and the bold font. The panel on the right actually shows what that message would look like:

The formatting properties of that Area Section consist of just one setting: assigning to it the paragraph style 'Message'. So, all paragraph formatting (including text) comes from that style:
Here is how the 'Message' style is defined:
It provides the paragraph specific properties, which include the background color and border:
and also some margins and paddings:
The 'Message' style also provides the text formatting properties, which include the font and its color:
The specifically highlighted part of the message text is generated by a separate Text Control:
Its formatting settings are the same as described in the “Named + anonymous rules” section (the 'Highlighted Text' style plus the bold font specified directly on the control):
Now, let's see what HTML/CSS output this everything will generate. The style sheet will include three named rules and one anonymous rule:
<style>
  /*
   * Two named rules generated from 'Message' style
   * (see also: Multiple named rules with the same class selector)
   */
  div.msg  { background-color: #FFFFDD; border: solid 1px #FF0000; 
             margin-top: .4em; margin-bottom: .4em; padding-top: .1em; padding-bottom: .1em; }
  span.msg { font-family: "Verdana", sans-serif; font-size: 110%; color: #008000; }

  /* the named rule generated from 'Highlighted Text' style */
  span.highlight { color: #EE0000 }

  /* the anonymous rule generated by the direct settings on the control */
  span.aXXX { font-weight: bold }
</style>
and here is what we'll get in HTML:
<div class="msg">
   <span class="msg">A message with the normal and </span><span class="msg highlight aXXX">highlighted</span><span class="msg"> text.</span>
</div>
You can see that the word “highlighted” is formatted with three CSS rules simultaneously. That's possible according to CSS and will work fine in any modern HTML browser!

But you may notice also that both 'msg' and 'highlight' rules specify the color property. So, which color will be used for “highlighted” then? According to how CSS works, it will be the color from the latest defined CSS rule, that is from 'highlight'. That will be the same in any browser! See also: Applying multiple CSS rules to the same HTML element.

Other cases: Which template styles can produce named rules?

In the previous section (“Named + named + anonymous rules”) we have seen how two named rules generated from a paragraph and character formatting styles were applied together (along with an anonymous rule) to format the same piece of text output.

Now, you may assume that when even more formatting styles are used in a chain, that will lead to an HTML output like this:

<span class="style1 style2 ... styleN aXXX"> . . . </span>
No. Although templates do allow assigning formatting styles to any parent/container components (or even having a style chain formed dynamically during the calls of stock-sections or subtemplates), the generator actually tracks only the nearest paragraph style and nearest character style (nearest to the component being interpreted). Only those styles may be rendered into named rules.

There is one exception, however. It is hyperlink styles. Hyperlink styles are the character formatting styles assigned to the template controls that may generate hyperlinks. When a hyperlink is generated, the hyperlink formatting style will be applied to it, including in the form of a named rule. There are several methods of how hyperlinks are formatted. One of them is blended-in hyperlink (i.e. the hyperlink always looks the same as the ordinary text at the given location, however, with some extra feature indicating the hyperlink). In that case, when a paragraph, character and hyperlink styles are involved together and all provide some text formatting properties, all of them will be rendered into the corresponding named rules for the <a> tag, so that all the three rules are applied to the hyperlink.

The formatting properties originating from any other styles will be treated the same as those assigned to the component directly (that is, they will get into the anonymous rule). That means that when a certain template formatting style being involved in the generation of the output is always shadowed by other styles, it will never get visible as a named rule.

That's because when even more template styles are tracked simultaneously to become named rules, the implementation of that gets so complicated that it isn't worth it. Also, the formatting properties defined in those styles may override each other according to how the styles are ordered in the chain. Replicating the same behavior in CSS would require the equal ordering of the corresponding named rule definitions. But what if the same styles are applied somewhere else in a different order? In short, CSS simply doesn't support such things. The object model of CSS rules is too rudimentary for this.

Controlling named rules

Named CSS rules are not necessary for proper HTML output and will just bloat its size. You need named rules only when you want to substitute some of the generated CSS rules with your own ones.

Generation of named rules is controlled by the “Output | CSS | Generate named rules” option:

  • When it is set "none", no named rules will be generated. Then, all formatting properties of a template component will be treated the same, irrelevant where they originate. That will produce only anonymous rules.
  • When the option is set "all", all possible named rules will be generated.
  • When the option is set "selected", only those named CSS rules will be generated, which are produced from template formatting styles with the selected "CSS | Allow named rule" property:

    This allows you to enable exactly those named CSS rules, which you are going to substitute.

Default Rules

Besides anonymous and named CSS rules, the HTML generator produces one more type of rules, which we call default rules. These rules specify the CSS properties applied to particular HTML tags by default, that is without the use of class selectors, e.g.:
<style>
  body { background: #FFEEDD; }
  a:link { color: #0066CC; }
  a:visited { color: #800080; }
  div { text-decoration: none; color: black; }
  ...
</style>
All of such rules are generated according to the settings specified on the "Formatting" tab of the Template Properties dialog of the main template (the one specified to the generator) or those subtemplates producing whole HTML documents:
The rule for <div> tag is the most important of them, because it encodes the template's default paragraph style (see also CSS rules derived from template formatting styles). That style, which is always present in any template typically under the name 'Normal', provides the default paragraph and text formatting properties for any component in the given template:
When a template component is set to generate a paragraph or a piece of text and has no particular paragraph/text formatting property (specified either directly on the component or inherited from a template formatting style assigned to it), that property will be looked for in the template default paragraph style.

The default CSS rule for <div> tag:

div {  /* CSS properties produced from default paragraph style */ }
perfectly serves the required interpretation of the template default paragraph style. That CSS rule is the same as the named rule:
div.Normal { ... }
which is actually never generated.

Note that a formatting styles defined in the main template will override any equally-named style found in subtemplates. This applies to the default paragraph style too!

Like named rules, the default CSS rules are always statically connected to what they format (that is particular HTML tags). So, you can easily substitute them with your own default CSS rules.

3.  Generated Style Sheets

Every CSS rule produced during the generation of HTML output is registered (accounted) in a special table called style sheet, which is maintained by the HTML generator dynamically. That table will be printed eventually either as a part of some HTML file or in the form of a separate CSS file.

Correspondingly, there are two types of style sheets:

  1. Local Style Sheet
  2. Global Style Sheet

Local Style Sheet

Such a style sheet is associated with a particular HTML document and collects only CSS rules used in it. It will be printed inside the <style> element of the corresponding HTML file:
<html>
<head>
  ...
  <!-- local style sheet -->
  <style type="text/css">
    ...
  </style>
  ...
</head>
<body>
  ...
</body>
</html>

Global Style Sheet

This style sheet accounts all those CSS rules, which are commonly used across all generated HTML documents.

Once the generation of all HTML files is finished, the global style sheet is printed as a separate CSS file placed in the output destination directory typically under the name 'stylesheet.css'. That CSS file is referenced from every HTML file via a <link> tag, e.g.:

<link rel="stylesheet" type="text/css" href="../../stylesheet.css">
The global style sheet is enabled when the option “Output | CSS | Generate style sheet file” is selected (true). When it is unselected (false), all CSS rules will be stored in local style sheets (according to where they are used).

Multiple Style Sheets

Style sheets of both types may co-exist and used together in the same HTML:
<html>
<head>
  ...
  <!-- link to the global style sheet -->
  <link rel="stylesheet" type="text/css" href="../../stylesheet.css">

  <!-- local style sheet -->
  <style type="text/css">
    ...
  </style>
  ...
</head>
<body>
  ...
</body>
</html>
For instance, local style sheets may hold only anonymous rules, whereas global style sheet may be used for all default and named rules.

Which CSS rules go where depends on the options controlling what's included in the global style sheet (i.e. CSS file). For instance, unselecting the option “Output | CSS | Generate style sheet file | Include anonymous rules” will cause all anonymous rules to be generated and stored locally by each HTML file where they are used.

By default, the global style sheet (CSS file) holds all CSS rules. That makes the generated HTML documentation most compact.

Style Sheet Structure

In its printed form, a style sheet generated by DocFlex consists of the following sections:
[Default Rules]
[Named Rules]
[Anonymous Rules]
The ordering of these sections is important.

Basically, it is because, in order to achieve the formatting effects specified in a template, several CSS rules may be applied together to the same HTML tag. At that, the properties specified in some of those rules must override the same properties specified in others. That can be achieved only by the specific ordering of the CSS rule definitions in the style sheet. See also: Appendix | Applying multiple CSS rules to the same HTML element.

In particular, the definitions of anonymous rules must appear strictly after the definitions of named rules. Because, when both named and anonymous rules are applied together, the CSS properties specified in the anonymous rule must override those specified in the named one. This works only when the anonymous rule appears in the style sheet later. See also: Named + anonymous rules.

The [Named Rules] section also has its own strict structure:

[Named Rules generated from Table Styles]
[Named Rules generated from Table Row Styles]
[Named Rules generated from Table Cell Styles]
[Named Rules generated from Horizontal Rule Styles]
[Named Rules generated from Paragraph Styles]
[Named Rules generated from Character Styles]
[Named Rules generated from Character Styles for hyperlinks]
Here again, the CSS rules specified in a lower group in that list must have higher priority. See also: Named + named + anonymous rules.

4.  Custom CSS Rules / CSS File

Most of the said above actually has a single purpose: to allow the users to style the generated HTML documentation with their own CSS properties/rules.

But please note, this is not the only (and even not the main) way how you can customize the generated HTML!

Since all ready-to-use documentation generators (available on this website) are implemented in the form of templates, you can always change everything (both how your documentation looks and what it contains) by editing/modifying the templates.

Basically, you may need a custom style sheet / custom CSS rules in the following situations:
  • You don't want (have no time) to learn much about how templates work.
  • You need a more quick (customary) way to modify the documentation formatting (rather than editing templates).
  • You want to use some CSS features not supported directly in templates.

Since it is impossible to tell the HTML generator which CSS rules must be used at which output locations, the only way to apply custom CSS rules is to substitute with them those produced automatically by the generator itself. That can be done only for the rules with a constant (predictable) connection to the specific output structures, which they are applied to. That is, whenever a given template set is used, the same pieces/structures of the output will be formatted with the CSS rules associated with the same tag/class selectors. This applies only to named and default rules!

The anonymous rules, which have no predictable relationship with the output, must be preserved in any case to keep the overall formatting integrity.

Another complication is that in the style sheet named rules must be defined in a specific order, so that properties specified in one rules override properties specified in others (in case of collisions), and anonymous rules must be defined the last, because their properties must override anything else. See also: Style Sheet Structure.

All that means that replacing the automatically generated style sheet file with the static custom one may be rather tricky.

Much easier is to let the generator produce the result CSS file by itself, at that, feed to it those custom rules that must substitute the generated ones. Lastly, if something extra is needed not coming from the generator at all, that can be added to the result CSS file via CSS pattern file.

How to substitute generated CSS rules with custom ones?

Here is the step-by-step instruction.

Find which generated rules to substitute

First, you need see which named rules are actually generated by the given template set, so you can decide which of them to substitute. To do that:
  1. Make sure that “Output | CSS | Generate style sheet file” option is selected. That will direct all CSS rules into a single CSS file.
  2. Set options:
  3. Run the generator.
Once it's finished, look in the stylesheet.css file found in the output directory. You will see something like this:
/* DocFlex styles; generated by DocFlex SDK 1.x on Fri Jul 19 06:00:15 CEST 2013 */

/*===== NAMED RULES (generated from paragraph styles) =====*/

/*
 * Generated from style: "Derivation Tree Heading"
 * References: 220
 *
 * Formats the heading of Type Derivation Tree
 */
div.derivTreeHead { margin-bottom: .57em; }
span.derivTreeHead { font-size: 90%; font-weight: bold; color: #990000; }

...

/*===== NAMED RULES (generated from character styles) =====*/

/*
 * Generated from style: "XML Source"
 * References: 3327
 * 
 * The default font for the reproduced XML source.
 */
span.src, a.src { font-family: "Verdana", sans-serif; font-size: 83%; }

/*
 * Generated from style: "XML Source Attribute Name"
 * References: 3315
 * 
 * The font for the names of attributes in the reproduced XML source.
 */
span.srcAttrName { font-family: "Verdana", sans-serif; font-size: 83%; color: #990000; }

/*
 * Generated from style: "XML Source Attribute Name (Reserved)"
 * References: 8
 * 
 * The font for reserved attribute names in the reproduced XML source.
 * 
 * Reserved are namespace bindings (e.g. "xmlns:xs") and attributes from the XML
 * namespace (e.g. "xml:lang").
 */
span.srcAttrNameRes { font-family: "Verdana", sans-serif; font-size: 83%; color: #FF0000; }

/*
 * Generated from style: "XML Source Attribute Value"
 * References: 3307
 * 
 * The font for the values of attributes in the reproduced XML source.
 */
span.srcAttrVal, a.srcAttrVal { font-family: "Verdana", sans-serif; font-size: 70%; font-weight: bold; color: black; }

/*
 * Generated from style: "XML Source Attribute Value (Reserved)"
 * References: 8
 * 
 * The font for the values of reserved attributes in the reproduced XML source.
 * Reserved are namespace bindings (e.g. "xmlns:xs") and attributes from the XML
 * namespace (e.g. "xml:lang").
 */
span.srcAttrValRes { font-family: "Verdana", sans-serif; font-size: 70%; font-weight: bold; color: #FF0000; }

/*
 * Generated from style: "XML Source Comment"
 * References: 8
 * 
 * The font for XML source comments
 */
span.srcCom { font-family: "Courier New", monospace; font-size: 83%; color: #4D4D4D; }

/*
 * Generated from style: "XML Source Comment Markup"
 * References: 16
 * 
 * The font for XML comment markup ("<!--" and "-->") in the reproduced XML source
 */
span.srcComMrk { font-family: "Verdana", sans-serif; font-size: 83%; color: #0000FF; }

/*
 * Generated from style: "XML Source DOCTYPE"
 * References: 2
 * 
 * The font for <!DOCTYPE> declaration (except internal subset) in the reproduced
 * XML source
 */
span.srcDOCTYPE { font-family: "Verdana", sans-serif; font-size: 83%; color: #0000FF; }

/*
 * Generated from style: "XML Source Element Name"
 * References: 3963
 * 
 * The font for the names of elements in the reproduced XML source.
 */
span.srcElemName { font-family: "Verdana", sans-serif; font-size: 83%; color: #990000; }

/*
 * Generated from style: "XML Source Element Value"
 * References: 138
 * 
 * The font for the values of elements in the reproduced XML source.
 */
span.srcElemVal { font-family: "Verdana", sans-serif; font-size: 70%; font-weight: bold; }

/*
 * Generated from style: "XML Source Internal Subset"
 * References: 3
 * 
 * The font for Internal Subset (embedded in <!DOCTYPE> declaration) in the
 * reproduced XML source.
 */
span.srcIS { font-family: "Courier New", monospace; font-size: 83%; color: #0000FF; }

/*
 * Generated from style: "XML Source Markup"
 * References: 12512
 * 
 * The font for XML markup characters (such as angle brackets, quotes etc.)
 */
span.srcMrk { font-family: "Verdana", sans-serif; font-size: 83%; color: #0000FF; }

/*
 * Generated from style: "XML Source Processing Instruction"
 * References: 2
 * 
 * The font for Processing Instructions in the reproduced XML source.
 */
span.srcPI { font-family: "Verdana", sans-serif; font-size: 83%; color: #0000FF; }

...

/*===== NAMED RULES (generated from character styles for hyperlinks) =====*/

/*
 * Generated from style: "Hyperlink (blended in)"
 * References: 2370
 * 
 * Used to format hyperlinks blended into the text.
 */
a.link { text-decoration: underline; }

/*
 * Generated from style: "Hyperlink (blended in, hover)"
 * References: 28
 * 
 * Used to format completely blended-in (latent) hyperlinks.
 */
a:hover.link-hover { text-decoration: underline; }

...

/*===== ANONYMOUS RULES =====*/

div.a0, span.a0 { font-size: medium; }
div.a1 { margin-top: .67em; }
span.a2 { font-weight: bold; }
td.a3 { padding: .42em .25em .25em .25em; }
...
Now, you will be able to find those named rules, by substituting which you could achieve the result formatting you need.

Provide your own declarations

When you know which automatically generated named rules must be substituted, you can prepare your own declarations for them in a separate file.

As an example, suppose our goal is to change a little bit the style of XML schema documentation (generated by XSDDoc), namely the coloring scheme of:

  • Reproduced XML source
  • Normal hyperlinks
Here are our custom CSS rules for that (the purpose of each rule can be found in the inset above):
/* default rules for normal hyperlinks */

a:link { color: #0066CC; }
a:visited { color: #0066CC; }

/* named rules for XML source */

span.src, a.src { font-family: "Arial", sans-serif; font-size: 80%; }
span.srcMrk { font-family: "Arial", sans-serif; font-size: 80%; color: #000000; }

span.srcAttrName, span.srcAttrNameRes { font-family: "Arial", sans-serif; font-size: 80%; font-weight: bold; color: #000000; }
span.srcAttrVal, a.srcAttrVal, span.srcAttrValRes { font-family: "Arial", sans-serif; font-size: 80%; color: #0066CC; }

span.srcCom, span.srcComMrk { font-family: "Courier New", monospace; font-style: italic; font-size: 80%; color: #008800; }

span.srcElemName { font-family: "Arial", sans-serif; font-size: 80%; font-weight: bold; color: #800080; }
span.srcElemVal { font-family: "Arial", sans-serif; font-size: 80%; color: #000000; }

span.srcDOCTYPE, span.srcIS { font-family: "Courier New", monospace; font-size: 80%; font-style: italic; font-weight: bold; color: #FF0000; }
span.srcPI { font-family: "Courier New", monospace; font-size: 80%; font-style: italic; color: #CC66CC; }
span.srcCDATA, span.srcCDATAMrk { font-family: "Courier New", monospace; font-size: 80%; color: #CC0066; }
The custom CSS rules must be saved in a separate file (e.g. mystyles.css), which is specified in “Output | CSS | Generate name rules | Custom rule file” option:
If you run XSDDoc with now, you'll get a reproduced XML schema source like shown on the left screenshot (on the right is the same doc without applying the custom CSS rules; click on each screenshot to see the real HTML):

Custom default rules

Since default rules implicitly apply to all HTML tags (for which they are declared), in order substitute the automatically generated ones you don't need to see which of them have been actually generated in a particular documentation. All you need is to know which default rules the generator can generate. It is currently limited to only six:
html { ... }
body { ... }
a:link { ... }
a:visited { ... }
a:active { ... }
div { ... }
If you specify any of them in your custom rule file, your definitions will be picked and inserted in the generated style sheet. That will happen in any case, whether or not the generator was to produce a given default rule of its own.

If you need to apply any other default CSS rules, you can do it via CSS pattern file.

Case of relative length units

When you use relative length units (see “Output | CSS | Units” option) and want to substitute some generated named CSS rules with your own ones, you should be aware of the following:
  • Currently, DocFlex HTML generator uses only the following relative units:
    • percent (%) for font sizes
    • em for spacing, margins and paddings (and a few other things)
  • Although, these relative units are context-dependent (that is, CSS computes property values specified in such units against the context font size inherited by the element where the property applied), that is incompatible with the most concepts, on which DocFlex (template language) is based.

    Because of this, DocFlex treats all CSS property values specified in relative units effectively against the document base font size. That requires periodic resetting of the context font size to the document base font size. For more details, please see: Appendix | The problem with relative length units.

    Another consequence is that the same CSS rule cannot specify both the font size and any other relative-unit properties. When it is actually needed (in the case of a named CSS rule produced from a paragraph style), such a CSS rule will be broken into two ones applied to nested HTML tags (one for paragraph and one for text). For more details, please see: Multiple named rules with the same class selector | Property conflicts caused by relative units.

  • Because of the said above, make sure that when your custom CSS rule contains some length-unit properties, the generated CSS rule it substitutes also contained that kind of properties. (Note that this is specified in the corresponding template formatting style, from which the given rule was generated).

    For instance, you should avoid substituting a CSS rule without font size with the one that specifies the font size. That may result in unpredictable distortions of the entire document formatting!

If all this sounds too complicated for you, simply don't use relative units.

Which license required?

The possibility to use custom CSS rules / style sheets is covered by the “SDK license” (that is the license covering the Template Designer):
This is considered a deep customization of your generated documentation (i.e. of the doc-generator implemented by a DocFlex template set you want to use). Moreover, if you plan to customize the generated style sheets, you will likely need also to change something in the templates themselves as well as require some special support about all that.

CSS pattern file

The CSS pattern file allows you to frame the CSS declarations generated by DocFlex into your own CSS file.

It may be useful when you need to add in the result style sheet some CSS rules not generated by DocFlex at all (for instance, to format the HTML markup embedded in your descriptions/annotations).

Those CSS rule that are generated can also be substituted with your own ones using custom rule file.

The content of the CSS pattern file should look like the following:

...
...
/* docflex-styles */
...
Here, the dots depict some your content. All those lines will be copied as is to the result CSS file.

The line '/* docflex-styles */' is important. All DocFlex-generated CSS rules will be inserted in place of that comment. When it is absent, no automatically generated CSS rules will appear in the result CSS file.

This opens a possibility to use the CSS pattern file as a complete your CSS file. You just need to provide your definitions for all generated default and named CSS rules and exclude from the global style sheet all anonymous rules by unselecting the option: Output | CSS | Generate style sheet file | Include anonymous rules. See also: Style Sheet Structure.

The CSS pattern file can be applied only for the global style sheet. The local style sheets are not affected by it.

The name of the result CSS file (generated by DocFlex) will be the same as the name of your CSS pattern file. Thereby you can assign your own name to the result CSS file found in the generated documentation.

5.  Appendix

The problem with relative length units

According to CSS, relative units like % and em are interpreted actually not against some base font size chosen for the whole HTML document, but against the context font size inherited from the parent HTML element at the location where the property applied.

This creates a problem. When a CSS rule with the specified font size is applied to an HTML element, any values in relative units used within that element will be interpreted against that font size. This would make many of the generated CSS rules context-dependent, which breaks the whole idea of named rules (which are supposed to be independent of where they are used).

To work around that problem the context font size is reset to the document's base font size each time it was changed by applying a font-size-containing CSS rule and another font-size-dependent CSS rule needs to be applied within its scope. As a font size resetter, the following CSS rule is used:

div.a0 { font-size: medium; }
The medium keyword specifies the document base font size.

In a few cases, it is impossible to insert an intermediate tag with the font size resetting CSS rule. So, if some length-unit values are applied down there, they must be adjusted to the context font size.

For example, suppose the HTML code must define a numbered list with the following requirements:

  • The item numbers must be of a certain font size.
  • The list items must have a certain spacing between them.
  • The content of each list item may be complex with own font sizes, spacings etc.
Here's how all this achieved:
<html>
<head>
  ...
  <!-- style sheet -->
  <style type="text/css">
    /* the rule for the list item numbers */
    ol.list { font-family: "Verdana"; font-size: 80%; }

    /* the rule to make spacing between list items;
     we want the spacings to be exactly 1em (relative the base font size),
     but this rule will be applied in context of the 80% font size left from
     the 'list' rule (above), so the spacings are adjusted accordingly */
    li.item { margin-top: 1.25em; margin-bottom: 1.25em; }

    /* the rule for a text within the list item */
    span.text { font-family: "Arial"; font-size: 80%; }

    /* the rule for spacing between text paragraphs within the list item */
    div.spacing { margin-top: .5em; }

    /* the font size resetter rule (generated automatically) */
    div.a0 { font-size: medium; }
    ...
  </style>
</head>
<body>
  ...
  <!-- the list -->
  <ol class="list">
    <!-- a list item -->
    <li class="item">
      <!-- reset the context font size to the document's base one -->
      <div class="a0">
        <!-- first paragraph -->
        <span class="text">TEXT 1</span>
        <!-- spacing between paragraphs -->
        <div class="spacing"></div>
        <!-- second paragraph -->
        <span class="text">TEXT 2</span>
      </div>
    </li>
    ...
  </ol>
  ...
</body>
</html>
However, those resettings and adjustments, besides slightly bloating the output, make it rather unstable when you want to use custom CSS rules.

There is a new relative unit planned in CSS: the rem (for "root em"), which will be computed exactly against the document's base font size. That would save us the day! Unfortunately, that unit is not quite established yet and not supported by some browsers.

See also:

Applying multiple CSS rules to the same HTML element

CSS does not allow you to base one CSS rule on others. What is possible instead is to assign several CSS rules to the same HTML element (just by listing their class selectors in the value of class attribute), thereby creating an inline rule based on all the listed ones together.

The question is: When a CSS property is defined in several of those listed rules and has different values there, which of them will take effect? One could expect, it must be from the rule, whose class is listed the last. But that's wrong. Rather, that will be from the rule, which is defined the last!

For example, suppose you have two rules rule1 and rule2 defined in a style sheet like this:

<style>
  span.rule1 { color: red; }
  span.rule2 { color: blue; }
 ...
</style>
When you apply both rules to a <span> tag:
<span class="rule1 rule2"> text </span>
what color will be of the text? It will be blue!

Even when you reverse the ordering of the class selectors specified in the class attribute:
<span class="rule2 rule1"> text </span>
the color of the text will still be blue.

Copyright© 2017 Filigris Works, Leonid Rudy Softwareprodukte. All rights reserved.