DocBookXslDocsAuthoring

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.

General.

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="''"/>}}}

Use

{{{<xsl:param name="html.head.legalnotice.link.types">copyright</xsl:param>}}}

rather than

{{{<xsl:param name="html.head.legalnotice.link.types" select='"copyright"'/>}}}

for default string values which are non l10N

Use

{{{<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

Use

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

when the param is an xpath expression.

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

Linking

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.

{{{ NAME NAME

<title>Description</title>

FIXME:

}}}

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.

'''Callouts.'''

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 http://docbook.sourceforge.net/projects/xsl/doc/tools/profiling.html for more information

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

Queries

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

callouts.extension

  1. Not used in same manner as callout.graphics.extension. 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?)

ebnf.table.bgcolor

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.

annotate.toc

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?

autotoc.label.in.hyperlink Meaningless to me. Is an example appropriate?

manual.toc

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.

generate.toc

generate.section.toc.level

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.

generate.index

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

index.method

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?

index.term.separator

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.

linenumbering.separator

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]

textinsert.extension

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]

graphicsize.use.img.src.path

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

chapter.autolabel

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:

appendix.autolabel

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:

part.autolabel

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:

reference.autolabel

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.

section.autolabel.max.depth

add section.autonumber.max.depth as alias

section.label.includes.component.label

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'?]

label.from.part

add autonumber.from.part as alias

component.label.includes.part.label

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.

html.stylesheet.type

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

css.decoration

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.

emphasis.propagates.style

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?]

html.longdesc.link — 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?]

draft.mode

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

generate.meta.abstract

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?]

make.single.year.ranges

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.]

funcsynopsis.decoration

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?]

funcsynopsis.style

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

refentry.xref.manvolnum

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?]

default.table.width

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

table.cell.border.style

[Issue: Is this one from list

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

? Or some other CSS style of border decoration?]

ulink.target — The HTML anchor target for ULinks

If ulink.target 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]

olink.pubid

[Issue: @@FIXME ]

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

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

Description

FIXME: Badly broken.

olink.resolver

FIXME:

formal.title.placement

[Issue: Another one for an xml structure?]

show.comments — Display comment elements?

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

Description

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>

Description

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 http://www.w3.org/TR/2004/WD-xsl11-20041216/

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.