]> git.stg.codes - stg.git/blob - doc/xslt/params/custom.css.source.xml
Use namespace instead of prefix.
[stg.git] / doc / xslt / params / custom.css.source.xml
1 <refentry xmlns="http://docbook.org/ns/docbook"
2           xmlns:xlink="http://www.w3.org/1999/xlink"
3           xmlns:xi="http://www.w3.org/2001/XInclude"
4           xmlns:src="http://nwalsh.com/xmlns/litprog/fragment"
5           xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
6           version="5.0" xml:id="custom.css.source">
7   <refmeta>
8     <refentrytitle>custom.css.source</refentrytitle>
9     <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
10   </refmeta>
11   <refnamediv>
12     <refname>custom.css.source</refname>
13     <refpurpose>Name of a custom CSS input file</refpurpose>
14   </refnamediv>
15
16   <refsynopsisdiv>
17     <src:fragment xml:id="custom.css.source.frag"><xsl:param name="custom.css.source"></xsl:param></src:fragment>
18   </refsynopsisdiv>
19
20   <refsection><info><title>Description</title></info>
21
22 <para>The <parameter>custom.css.source</parameter>
23 parameter enables you to add CSS styles to DocBook's
24 HTML output.</para>
25
26 <para>The parameter
27 specifies the name of a file containing custom
28 CSS styles.  The file must be a well-formed XML file that
29 consists of a single <tag>style</tag> root
30 element that contains CSS styles as its text content.
31 For example:</para>
32 <programlisting><![CDATA[<?xml version="1.0"?>
33 <style>
34 h2 {
35   font-weight: bold;
36   color: blue;
37 }
38 ...
39 </style>
40 ]]></programlisting>
41
42 <para>The filename specified by the parameter
43 should have a <literal>.xml</literal>
44 filename suffix, although that is not required.
45 The default value of this parameter is blank.</para>
46
47 <para>If <parameter>custom.css.source</parameter> is not blank, then
48 the stylesheet takes the following actions.
49 These actions take place regardless of the value of
50 the <parameter>make.clean.html</parameter> parameter.</para>
51
52 <orderedlist>
53   <listitem>
54     <para>The stylesheet uses the XSLT <literal>document()</literal>
55     function to open the file specified by the parameter and
56     load it into a variable.</para>
57   </listitem>
58   <listitem>
59     <para>The stylesheet forms an output pathname consisting of the
60     value of the <parameter>base.dir</parameter> parameter (if it is set)
61     and the value of <parameter>custom.css.source</parameter>,
62     with the <literal>.xml</literal> suffix stripped off.
63     </para>
64   </listitem>
65   <listitem>
66     <para>The stylesheet removes the <tag>style</tag>
67     wrapper element and writes just the CSS text content to the output file.</para>
68   </listitem>
69   <listitem>
70     <para>The stylesheet adds a <tag>link</tag> element to the
71     HTML <tag>HEAD</tag> element to reference this external CSS stylesheet.
72     For example:
73     <programlisting>&lt;link rel="stylesheet" href="custom.css" type="text/css"&gt;
74     </programlisting>
75     </para>
76   </listitem>
77 </orderedlist>
78
79
80
81 <para>If the <parameter>make.clean.html</parameter> parameter is nonzero
82 (the default is zero),
83 and if the <parameter>docbook.css.source</parameter> parameter
84 is not blank (the default is not blank),
85 then the stylesheet will also generate a default CSS file
86 and add a <tag>link</tag> tag to reference it.
87 The <tag>link</tag> to the custom CSS comes after the 
88 <tag>link</tag> to the default, so it should cascade properly
89 in most browsers.
90 If you do not want two <tag>link</tag> tags, and
91 instead want your custom CSS to import the default generated
92 CSS file, then do the following:
93 </para>
94
95 <orderedlist>
96   <listitem>
97     <para>Add a line like the following to your custom CSS source file:</para>
98     <programlisting>@import url("docbook.css")
99     </programlisting>
100   </listitem>
101   <listitem>
102     <para>Set the <parameter>docbook.css.link</parameter> parameter 
103     to zero. This will omit the <tag>link</tag> tag
104     that references the default CSS file.</para>
105   </listitem>
106 </orderedlist>
107
108 <para>If you set <parameter>make.clean.html</parameter> to nonzero but
109 you do not want the default CSS generated, then also set
110 the <parameter>docbook.css.source</parameter> parameter to blank.
111 Then no default CSS will be generated, and so
112 all CSS styles must come from your custom CSS file.</para>
113
114 <para>You can use the <parameter>generate.css.header</parameter>
115 parameter to instead write the CSS to each HTML <tag>HEAD</tag>
116 element in a <tag>style</tag> tag instead of an external CSS file.</para>
117
118   </refsection>
119 </refentry>