From: Bob Stayton Date: Sun, 6 Dec 2009 21:47:04 +0000 (+0000) Subject: Params to support generated CSS files. X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=4b2ee74edd3140d6b8adf72e486272d8e457e8d0;p=docbook-dsssl Params to support generated CSS files. --- diff --git a/xsl/params/custom.css.source.xml b/xsl/params/custom.css.source.xml new file mode 100644 index 000000000..60d76f305 --- /dev/null +++ b/xsl/params/custom.css.source.xml @@ -0,0 +1,119 @@ + + + custom.css.source + string + + + custom.css.source + Name of a custom CSS input file + + + + custom.css.xml + + + Description + +The custom.css.source +parameter enables you to add CSS styles to DocBook's +HTML output. + +The parameter +specifies the name of a file containing custom +CSS styles. The file must be a well-formed XML file that +consists of a single style root +element that contains CSS styles as its text content. +For example: + + +]]> + +The filename specified by the parameter +should have a .xml +filename suffix, although that is not required. +The default value of this parameter is blank. + +If custom.css.source is not blank, then +the stylesheet takes the following actions. +These actions take place regardless of the value of +the make.clean.html parameter. + + + + The stylesheet uses the XSLT document() + function to open the file specified by the parameter and + load it into a variable. + + + The stylesheet forms an output pathname consisting of the + value of the base.dir parameter (if it is set) + and the value of custom.css.source, + with the .xml suffix stripped off. + + + + The stylesheet removes the style + wrapper element and writes just the CSS text content to the output file. + + + The stylesheet adds a link element to the + HTML HEAD element to reference this external CSS stylesheet. + For example: + <link rel="stylesheet" href="custom.css" type="text/css"> + + + + + + + +If the make.clean.html parameter is nonzero +(the default is zero), +and if the docbook.css.source parameter +is not blank (the default is not blank), +then the stylesheet will also generate a default CSS file +and add a link tag to reference it. +The link to the custom CSS comes after the +link to the default, so it should cascade properly +in most browsers. +If you do not want two link tags, and +instead want your custom CSS to import the default generated +CSS file, then do the following: + + + + + Add a line like the following to your custom CSS source file: + @import url("docbook.css") + + + + Set the docbook.css.link parameter + to zero. This will omit the link tag + that references the default CSS file. + + + +If you set make.clean.html to nonzero but +you do not want the default CSS generated, then also set +the docbook.css.source parameter to blank. +Then no default CSS will be generated, and so +all CSS styles must come from your custom CSS file. + +You can use the generate.css.header +parameter to instead write the CSS to each HTML HEAD +element in a style tag instead of an external CSS file. + + + diff --git a/xsl/params/docbook.css.link.xml b/xsl/params/docbook.css.link.xml new file mode 100644 index 000000000..016dccc63 --- /dev/null +++ b/xsl/params/docbook.css.link.xml @@ -0,0 +1,42 @@ + + +docbook.css.link +boolean + + +docbook.css.link +Insert a link referencing the default CSS stylesheet + + + + + + + + +Description + +The stylesheets are capable of generating a default +CSS stylesheet file. The parameters +make.clean.html and +docbook.css.source control that feature. + +Normally if a default CSS file is generated, then +the stylesheet inserts a link tag in the HTML +HEAD element to reference it. +However, you can omit that link reference if +you set the docbook.css.link to zero +(1 is the default). + +This parameter is useful when you want to import the +default CSS into a custom CSS file generated using the +custom.css.source parameter. + + + + diff --git a/xsl/params/docbook.css.source.xml b/xsl/params/docbook.css.source.xml new file mode 100644 index 000000000..8ba7eb768 --- /dev/null +++ b/xsl/params/docbook.css.source.xml @@ -0,0 +1,83 @@ + + + docbook.css.source + string + + + docbook.css.source + Name of the default CSS input file + + + + docbook.css.xml + + + Description + +The docbook.css.source parameter +specifies the name of the file containing the default DocBook +CSS styles. Those styles are necessary when the +make.clean.html parameter is nonzero. + +The file is a well-formed XML file that +must consist of a single style root +element that contains CSS styles as its text content. +The default value of the parameter (and filename) +is docbook.css.xml. +The stylesheets ship with the default file. You can substitute +your own and specify its path in this parameter. + +If docbook.css.source is not blank, +and make.clean.html is nonzero, then +the stylesheet takes the following actions: + + + + The stylesheet uses the XSLT document() + function to open the file specified by the parameter and + load it into a variable. + + + The stylesheet forms an output pathname consisting of the + value of the base.dir parameter (if it is set) + and the value of docbook.css.source, + with the .xml suffix stripped off. + + + + The stylesheet removes the style + wrapper element and writes just the CSS text content to the output file. + + + The stylesheet adds a link element to the + HTML HEAD element to reference the external CSS stylesheet. + For example: + <link rel="stylesheet" href="docbook.css" type="text/css"> + + However, if the docbook.css.link + parameter is set to zero, then no link is written + for the default CSS file. That is useful if a custom + CSS file will import the default CSS stylesheet to ensure + proper cascading of styles. + + + +If the docbook.css.source parameter +is changed from its default docbook.css.xml to blank, +then no default CSS is generated. Likewise if the +make.clean.html parameter is set to zero, +then no default CSS is generated. The +custom.css.source parameter can be used +instead to generate a complete custom CSS file. + +You can use the generate.css.header +parameter to instead write the CSS to each HTML HEAD +element in a style tag instead of an external CSS file. + + + diff --git a/xsl/params/generate.css.header.xml b/xsl/params/generate.css.header.xml new file mode 100644 index 000000000..1d50e1868 --- /dev/null +++ b/xsl/params/generate.css.header.xml @@ -0,0 +1,40 @@ + + +generate.css.header +boolean + + +generate.css.header +Insert generated CSS styles in HEAD element + + + + + + + + +Description + +The stylesheets are capable of generating both default +and custom CSS stylesheet files. The parameters +make.clean.html, +docbook.css.source, and +custom.css.source> control that feature. + +If you require that CSS styles reside in the HTML +HEAD element instead of external CSS files, +then set the generate.css.header +parameter to nonzero (it is zero by default). +Then instead of generating the CSS in external files, +they are wrapped in style elements in +the HEAD element of each HTML output file. + + + + diff --git a/xsl/params/make.clean.html.xml b/xsl/params/make.clean.html.xml new file mode 100644 index 000000000..6676c670b --- /dev/null +++ b/xsl/params/make.clean.html.xml @@ -0,0 +1,51 @@ + + +make.clean.html +boolean + + +make.clean.html +Make HTML conform to modern coding standards + + + + + + + + +Description + +If make.clean.html is true, the stylesheets take +extra effort to ensure that the resulting HTML is conforms to +modern HTML coding standards. In addition to eliminating +excessive and noncompliant coding, it moves presentation +HTML coding to a CSS stylesheet. + +The resulting HTML is dependent on +CSS for formatting, and so the stylesheet is capable of +generating a supporting CSS file. The docbook.css.source +and custom.css.source parameters control +how a CSS file is generated. + +If you require your CSS to reside in the HTML +head element, then the generate.css.header +can be used to do that. + +The make.clean.html parameter is +different from html.cleanup +because the former changes the resulting markup; it does not use extension functions +like the latter to manipulate result-tree-fragments, +and is therefore applicable to any XSLT processor. + +If make.clean.html is set to zero (the default), +then the stylesheet retains its original +old style +HTML formatting features. + +