Norman Walsh edited this page Oct 3, 2015 · 2 revisions
Clone this wiki locally

Guidelines for Authoring Embedded Reference Documentation for the DocBook XSL Stylesheets

This page provides guidelines for authors or contributors working on the embedded documentation in the DocBook XSL Stylesheets distribution; particularly, authors working on the embedded documentation for the user-configurable XSLT parameters provided in the stylsheets.


For some of the more esoteric parameters, link to the appropriate page in TDG as a way of explaining them.

We need somewhere to indicate that the indicated value is the default, e.g. {{{<xsl:param name="make.single.year.ranges" select="0"></xsl:param>}}} indicates that zero is the default. If this was available as an opening page, then we could remove all of the default statements.

General statement should be, non-zero 'enables' the feature, zero disables the feature

Describe using the non-zero, affirmative / positive action. Leave the zero option undescribed, it should be clear. State what the non-zero option does, rather than the obvious 'set to non-zero if you want to ...'

Editor constants.

Don't break public APIs unless you really have to - so don't change parameter names. If agreed, add a new one which becomes an alias of the older one.

Use zero/non-zero phrasing rather than true/false or 1, 0 on all occurrences in descriptive text.

General form of documentation follows the lines of ''Set to non-zero to do X''

Don't state what the default is (zero or non zero), just mention the output effect of the default value if not obvious.

Use {{{<xsl:param name="xxx" select="0"/>}}} when the parameter value is two valued (boolean).

Use {{{<xsl:param name="footnote.number.format">1</xsl:param>}}} for values which are required to be strings, e.g. formats

Use {{{<xsl:param name="glossary.collection"></xsl:param>}}} rather than {{{<xsl:param name="glossary.collection" select="''"/>}}}


{{{<xsl:param name="">copyright</xsl:param>}}}

rather than

{{{<xsl:param name="" select='"copyright"'/>}}}

for default string values which are non l10N


{{{<xsl:param name="xref.label-page.separator">xsl:text </xsl:text></xsl:param>}}}

when the text of a parameter may include white space

Use {{{<xsl:param name="xxx">23</xsl:param>}}} when the number can be more than 1


{{{<xsl:param name="nominal.image.depth" select="4 * $pixels.per.inch"/>}}}

when the param is an xpath expression.

Use {{{ <src:fragment xml:id=""> <xsl:param condition="html" name="">.png</xsl:param> <xsl:param condition="fo" name="">.svg</xsl:param> </src:fragment> }}} when the param is different for fo and html.


All docbook elements are hotlinked to the appropriate tdg page by the XSLT processing. The name must be recognised as a docbook element and marked with {{{}}}

All params that Bob has documented are hotlinked to the pages on Bobs book site. All other params are linked to one another, though no self-references. Again this is done by recognising the param names marked up with {{{}}}

Use TOC, not camel case ToC.

Use HTML head, meta, etc. I.e. only HTML should be upper cased. Other elements and attributes from html should be lower case. These may be marked with {{{}}} but processing will not link them.

Markup. Use and abuse.

{{{}}}, where the content is a docbook local-name() element, is transformed into a link to tdg.

{{{}}} where the content is a stylesheet parameter name, is transformed into a link to the relevant parameter page.

xml markup:

There is a file {{{template.xml}}} which provides a general outline.





For example

{{{ <src:fragment xml:id="dry-run"> <xsl:param name="dry-run" select="0"/> </src:fragment> }}}

The {{{xml:id}}} on {{{src:fragment}}} should match the filename, without the extension. Parameter names are descriptive, positive and period seperated.

E.g. {{{show.revisionflag.xml}}} if non-zero, will show the revision flag.

=section heads=

The parameters are broken down into the following sections. Please ensure that any new ones are added to the appropriate section

'''Admonitions. '''

An admonition is a warning, note, caution, important, tip. Information for the user.


A callout is markup intended to add metadata to a piece of information. E.g. explaining a line of code.

'''EBNF. '''

Extended Backus Naur Format. A metasyntax used to express context-free grammars: that is, a formal way to describe formal languages.

'''ToC/LoT/Index Generation'''

For tables of contents, control the appearance.

'''Stylesheet Extensions'''

Use of programming language extensions to utilise special features.

'''Automatic labelling'''

Inappropriately named? This is about enumeration? Suggest Automatic numbering. Customize the enumeration style for various elements.

'''HTML''' Parameters which control the html output.

'''XSLT Processing''' High level navigation and appearance parameters.

'''Meta/*Info and Titlepages''' Parameters related to title pages and control of metainformation

'''Reference Pages''' Customisation for refentry pages.

'''Tables.''' Table customization

'''QAndASet''' Customization for Question and Answer sets.

'''Linking.''' Customization for the various types of linking

'''Cross References''' Customize the way cross references are presented.

'''Lists.''' List customization

'''Bibliography''' Bibliography customization.

'''Glossary''' Glossary customization

'''Miscellaneous''' Miscellaneous customizations, ...

'''Annotations.''' Enable pop-up annotations

'''Graphics. ''' Graphics related customizations.

'''Chunking.''' Control for creating multiple output files.

'''Profiling.''' Control for Profiling. See for more information

'''HTML Help''' Control for generation of HTML help


After going through the parameters, the following left me unsure as to purpose.


  1. Not used in same manner as I don't understand why it's different.

The callouts extension processes areaset elements in ProgramListingCO and other text-based callout elements.

No idea what that means in terms of presentation of callouts (which is what the user might like to know?)


Sets the background color for EBNF tables (pale brown). No bgcolor attribute is output if ebnf.table.bgcolor is set to the null string.

Last sentance not helpful without a link? Suggest delete. #F5DCB3 Is that a red, orange brown or what? How to find out.


If true, TOCs will be annotated. At present, this just means that the RefPurpose of RefEntry TOC entries will be displayed.

No idea what this means. What's the visual difference produced? Meaningless to me. Is an example appropriate?


The manual.toc identifies an explicit TOC that will be used for building the printed TOC.

What's the relationship to 'process.source.toc' ??

Unclear IMHO, but not understood. What does explicit mean in this contxt?

toc.max.depth — How many levels should be created for each TOC?

Specifies the maximum depth of any TOC.



The generate.section.toc.level parameter controls the depth of section in which TOCs will be generated. Note that this is related to, but not the same as toc.section.depth, which controls the depth to which TOC entries will be generated in a given TOC.

These two sound identical to me? How to clarify the difference.


Specify if an index should be generated. [How to specify 'where' it should be generated? Should be same as surely?]


Issue: How to align this for xslt 2.0 work, where the collation is available?

Use Saxon (version 6 or 8) as your XSLT processor. ???? Sure? Will saxon 8 run OK using 1.0? Must admit I've never tried it.

index.prefer.titleabbrev — Should abbreviated titles be used as back references

??? Missing and incomprehensible from the name. Back references to ... what?


Is this sufficiently complex that it requires either an small example, or a link to Bobs book?

e.g. how to use gentext named template in a param?

index.number.separator Same as above. How to use it. (here I think a user needs a tiny how to :-)

index.range.separator Same as above.


The separator is inserted between line numbers and lines in the verbatim environment. The default value is a single white space. Remember to put the character in quotes. Note the interaction with (xref) linenumbering.width

Issue: This brings up the idea of an introductory how to, e.g. to quote all string values? [nice one for xslt 2.0 params]


The textinsert extension element inserts the contents of a a file into the result tree (as text). [Where, how? This isn't at all clear]


I don't understand how a size parameter relates to a path parameter? Not clear to me.


add chapter.autonumber as alias perhaps, to make more 'true'

If non-zero, then chapters will be numbered, using the parameter value as the number format if the value matches one of the following:


add to appendix.autonumber as alias

If non-zero, then appendices will be numbered, using the parameter value as the number format if the value matches one of the following:


add part.autonumber as alias

If non-zero, then parts will be numbered, using the parameter value as the number format if the value matches one of the following:


add reference.autonumber as alias

If non-zero, then references will be numbered, using the parameter value as the number format if the value matches one of the following:

preface.autolabel add preface.autonumber as alias

If non-zero prefaces will be numbered, using the parameter value as the number format if the value matches one of the following:

qandadiv.autolabel chx to add qndadiv.autonumber as alias

If non-zero, unlabeled qandadivs will be enumerated.


add section.autonumber.max.depth as alias


If non-zero, section labels are prefixed with the label of the component that contains them. [Confused. Does this mean prefix with 'section'.... or something else, e.g.l10N variant of 'section'?]


add autonumber.from.part as alias


If non-zero, number for chapters, appendices, and other component elements are prefixed with the number of the part that contains them. So you might see Chapter II.3 instead of Chapter 3. Also, the numbers for formal elements such as table and figure will include the part number. If there is no part element container, then no prefix is generated.


Is this redundant? Are there other options than text/css?


I'm unsure, but isn't the source element name copied over to the html element in the style attribute? If so, I think this should be stated.

If true, the role attribute of emphasis elements will be passed through to the HTML as a class attribute on a span that surrounds the emphasis. [Isn't it more than this? If 'bold' then b element created? etc]

html.longdesc — Should longdesc URIs be created?

If non-zero, HTML files will be created for the longdesc use. These files are created from the textobjects in mediaobjects and inlinemediaobject if they contain para children?

[Issue: I think I can get longdesc just by using para as child of textobject, without this param? Is this right?] — Should a link to the longdesc be included in the HTML? Synopsis

If non-zero, links will be created to the HTML files created for the longdesc attribute. It makes no sense to turn enable this option without also enabling the $html.longdesc parameter.

[Issue: This is pointless? Should be merged with html.longdesc surely?]


[Issue: No indication of any visible change in output when this is non-zero?] Should this be two way linked with draft.watermark.image?


If non-zero, document abstracts will be reproduced in the HTML HEAD with . The content attribute will be taken from the entire abstract?

[Is this correct? What level of content will be taken? Any markup etc?]


If non-zero, year ranges that span more than a single year will be printed in range notation (1998-1999) instead of discrete notation (1998, 1999). [Issue: What years are we talking about? see make.year.ranges.]


If non-zero, elements of the FuncSynopsis will be decorated (e.g. bold or italic). The decoration is controlled by functions that can be redefined in a customization layer.

[I don't understand this. Seems like only half the story? What functions? When bold and when Italics?]

Needs to say what these look like? Pointer to Bobs book? Seems not to be discussed?


if non-zero, the manvolnum is used when cross-referencing refentrys, either with xref or citerefentry

[Issue: Is the user interested in which form of xref is used?]


[Issue: Is this a numeric value or a length? Why no default?]

[Issue: Is this one from list

{{{ hidden dotted dashed solid double groove ridge inset outset inherit}}}

? Or some other CSS style of border decoration?] — The HTML anchor target for ULinks

If is set, its value will be used for the target attribute on anchors generated for ulinks.

[Issue: links to itself?] Disagrees with Bobs book (says it's the window name)

olink.outline.ext — Synopsis

<xsl:param name="olink.outline.ext" select="'.olink'"></xsl:param>

Description. The extension to be expected for OLink outline files [Issue: Nothing found]


[Issue: @@FIXME ]

olink.sysid — Names the system identifier portion of an OLink resolver query Synopsis

<xsl:param name="olink.sysid" select="'sysid='"></xsl:param>


FIXME: Badly broken.




[Issue: Another one for an xml structure?]

show.comments — Display comment elements?

<xsl:param name="show.comments" select="1"/>


If non-zero, comments will be displayed, otherwise they are suppressed. Comments here refers to the comment element, which will be renamed remark in DocBook V4.0, not XML comments (<-- like this -->) which are unavailable.

[Issue. Why isn't there a 'show remarks' param]

pixels.per.inch — How many pixels are there per inch? Synopsis

<xsl:param name="pixels.per.inch" select="90"></xsl:param>


When lengths are converted to pixels, this value is used to determine the size of a pixel. The default value is 90 pixels per inch. Used by xref to nominal.image.width.

link is 404, should be

Unable to find a default value?

[Issue: What value to use? Remove link?]

Future Directions

I posted to the list the variety of data formats in use as parameters.

As we move forward to XSLT 2.0 usage I think users may benefit from simplifying the variety of options.

Two major forms are in use.

  1. Those needing simple XML structures, even simple lists.
  2. Those needing XSLT structures such as attribute sets.

I don't think more are needed. Other than binary values and simple string values.