--- /dev/null
+<refentry xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:src="http://nwalsh.com/xmlns/litprog/fragment"
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ version="5.0" xml:id="custom.css.source">
+ <refmeta>
+ <refentrytitle>custom.css.source</refentrytitle>
+ <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>custom.css.source</refname>
+ <refpurpose>Name of a custom CSS input file</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <src:fragment xml:id="custom.css.source.frag"><xsl:param name="custom.css.source">custom.css.xml</xsl:param></src:fragment>
+ </refsynopsisdiv>
+
+ <refsection><info><title>Description</title></info>
+
+<para>The <parameter>custom.css.source</parameter>
+parameter enables you to add CSS styles to DocBook's
+HTML output.</para>
+
+<para>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 <tag>style</tag> root
+element that contains CSS styles as its text content.
+For example:</para>
+<programlisting><![CDATA[<?xml version="1.0"/>
+<style>
+h2 {
+ font-weight: bold;
+ color: blue;
+}
+...
+</style>
+]]></programlisting>
+
+<para>The filename specified by the parameter
+should have a <literal>.xml</literal>
+filename suffix, although that is not required.
+The default value of this parameter is blank.</para>
+
+<para>If <parameter>custom.css.source</parameter> is not blank, then
+the stylesheet takes the following actions.
+These actions take place regardless of the value of
+the <parameter>make.clean.html</parameter> parameter.</para>
+
+<orderedlist>
+ <listitem>
+ <para>The stylesheet uses the XSLT <literal>document()</literal>
+ function to open the file specified by the parameter and
+ load it into a variable.</para>
+ </listitem>
+ <listitem>
+ <para>The stylesheet forms an output pathname consisting of the
+ value of the <parameter>base.dir</parameter> parameter (if it is set)
+ and the value of <parameter>custom.css.source</parameter>,
+ with the <literal>.xml</literal> suffix stripped off.
+ </para>
+ </listitem>
+ <listitem>
+ <para>The stylesheet removes the <tag>style</tag>
+ wrapper element and writes just the CSS text content to the output file.</para>
+ </listitem>
+ <listitem>
+ <para>The stylesheet adds a <tag>link</tag> element to the
+ HTML <tag>HEAD</tag> element to reference this external CSS stylesheet.
+ For example:
+ <programlisting><link rel="stylesheet" href="custom.css" type="text/css">
+ </programlisting>
+ </para>
+ </listitem>
+</orderedlist>
+
+
+
+<para>If the <parameter>make.clean.html</parameter> parameter is nonzero
+(the default is zero),
+and if the <parameter>docbook.css.source</parameter> parameter
+is not blank (the default is not blank),
+then the stylesheet will also generate a default CSS file
+and add a <tag>link</tag> tag to reference it.
+The <tag>link</tag> to the custom CSS comes after the
+<tag>link</tag> to the default, so it should cascade properly
+in most browsers.
+If you do not want two <tag>link</tag> tags, and
+instead want your custom CSS to import the default generated
+CSS file, then do the following:
+</para>
+
+<orderedlist>
+ <listitem>
+ <para>Add a line like the following to your custom CSS source file:</para>
+ <programlisting>@import url("docbook.css")
+ </programlisting>
+ </listitem>
+ <listitem>
+ <para>Set the <parameter>docbook.css.link</parameter> parameter
+ to zero. This will omit the <tag>link</tag> tag
+ that references the default CSS file.</para>
+ </listitem>
+</orderedlist>
+
+<para>If you set <paramter>make.clean.html</paramter> to nonzero but
+you do not want the default CSS generated, then also set
+the <parameter>docbook.css.source</parameter> parameter to blank.
+Then no default CSS will be generated, and so
+all CSS styles must come from your custom CSS file.</para>
+
+<para>You can use the <parameter>generate.css.header</parameter>
+parameter to instead write the CSS to each HTML <tag>HEAD</tag>
+element in a <tag>style</tag> tag instead of an external CSS file.</para>
+
+ </refsection>
+</refentry>
--- /dev/null
+<refentry xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:src="http://nwalsh.com/xmlns/litprog/fragment"
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ version="5.0" xml:id="docbook.css.link">
+<refmeta>
+<refentrytitle>docbook.css.link</refentrytitle>
+<refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>docbook.css.link</refname>
+<refpurpose>Insert a link referencing the default CSS stylesheet</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment xml:id="docbook.css.link.frag">
+<xsl:param name="docbook.css.link" select="0"/>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsection><info><title>Description</title></info>
+
+<para>The stylesheets are capable of generating a default
+CSS stylesheet file. The parameters
+<parameter>make.clean.html</parameter> and
+<parameter>docbook.css.source</parameter> control that feature.</para>
+
+<para>Normally if a default CSS file is generated, then
+the stylesheet inserts a <tag>link</tag> tag in the HTML
+<tag>HEAD</tag> element to reference it.
+However, you can omit that <tag>link</tag> reference if
+you set the <parameter>docbook.css.link</parameter> to zero
+(1 is the default).</para>
+
+<para>This parameter is useful when you want to import the
+default CSS into a custom CSS file generated using the
+<parameter>custom.css.source</parameter> parameter.
+</para>
+
+</refsection>
+</refentry>
--- /dev/null
+<refentry xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:src="http://nwalsh.com/xmlns/litprog/fragment"
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ version="5.0" xml:id="docbook.css.source">
+ <refmeta>
+ <refentrytitle>docbook.css.source</refentrytitle>
+ <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>docbook.css.source</refname>
+ <refpurpose>Name of the default CSS input file</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <src:fragment xml:id="docbook.css.source.frag"><xsl:param name="docbook.css.source">docbook.css.xml</xsl:param></src:fragment>
+ </refsynopsisdiv>
+
+ <refsection><info><title>Description</title></info>
+
+<para>The <parameter>docbook.css.source</parameter> parameter
+specifies the name of the file containing the default DocBook
+CSS styles. Those styles are necessary when the
+<parameter>make.clean.html</parameter> parameter is nonzero.</para>
+
+<para>The file is a well-formed XML file that
+must consist of a single <tag>style</tag> root
+element that contains CSS styles as its text content.
+The default value of the parameter (and filename)
+is <literal>docbook.css.xml</literal>.
+The stylesheets ship with the default file. You can substitute
+your own and specify its path in this parameter.</para>
+
+<para>If <parameter>docbook.css.source</parameter> is not blank,
+and <parameter>make.clean.html</parameter> is nonzero, then
+the stylesheet takes the following actions:</para>
+
+<orderedlist>
+ <listitem>
+ <para>The stylesheet uses the XSLT <literal>document()</literal>
+ function to open the file specified by the parameter and
+ load it into a variable.</para>
+ </listitem>
+ <listitem>
+ <para>The stylesheet forms an output pathname consisting of the
+ value of the <parameter>base.dir</parameter> parameter (if it is set)
+ and the value of <parameter>docbook.css.source</parameter>,
+ with the <literal>.xml</literal> suffix stripped off.
+ </para>
+ </listitem>
+ <listitem>
+ <para>The stylesheet removes the <tag>style</tag>
+ wrapper element and writes just the CSS text content to the output file.</para>
+ </listitem>
+ <listitem>
+ <para>The stylesheet adds a <tag>link</tag> element to the
+ HTML <tag>HEAD</tag> element to reference the external CSS stylesheet.
+ For example:</para>
+ <programlisting><link rel="stylesheet" href="docbook.css" type="text/css">
+ </programlisting>
+ <para>However, if the <parameter>docbook.css.link</parameter>
+ parameter is set to zero, then no <tag>link</tag> 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.</para>
+ </listitem>
+</orderedlist>
+
+<para>If the <parameter>docbook.css.source</parameter> parameter
+is changed from its default <literal>docbook.css.xml</literal> to blank,
+then no default CSS is generated. Likewise if the
+<parameter>make.clean.html</parameter> parameter is set to zero,
+then no default CSS is generated. The
+<parameter>custom.css.source</parameter> parameter can be used
+instead to generate a complete custom CSS file.</para>
+
+<para>You can use the <parameter>generate.css.header</parameter>
+parameter to instead write the CSS to each HTML <tag>HEAD</tag>
+element in a <tag>style</tag> tag instead of an external CSS file.</para>
+
+ </refsection>
+</refentry>
--- /dev/null
+<refentry xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:src="http://nwalsh.com/xmlns/litprog/fragment"
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ version="5.0" xml:id="generate.css.header">
+<refmeta>
+<refentrytitle>generate.css.header</refentrytitle>
+<refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>generate.css.header</refname>
+<refpurpose>Insert generated CSS styles in HEAD element</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment xml:id="generate.css.header.frag">
+<xsl:param name="generate.css.header" select="0"/>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsection><info><title>Description</title></info>
+
+<para>The stylesheets are capable of generating both default
+and custom CSS stylesheet files. The parameters
+<parameter>make.clean.html</parameter>,
+<parameter>docbook.css.source</parameter>, and
+<parameter>custom.css.source></parameter> control that feature.</para>
+
+<para>If you require that CSS styles reside in the HTML
+<tag>HEAD</tag> element instead of external CSS files,
+then set the <parameter>generate.css.header</parameter>
+parameter to nonzero (it is zero by default).
+Then instead of generating the CSS in external files,
+they are wrapped in <tag>style</tag> elements in
+the <tag>HEAD</tag> element of each HTML output file.
+</para>
+
+</refsection>
+</refentry>
--- /dev/null
+<refentry xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:src="http://nwalsh.com/xmlns/litprog/fragment"
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ version="5.0" xml:id="make.clean.html">
+<refmeta>
+<refentrytitle>make.clean.html</refentrytitle>
+<refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>make.clean.html</refname>
+<refpurpose>Make HTML conform to modern coding standards</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment xml:id="make.clean.html.frag">
+<xsl:param name="make.clean.html" select="0"/>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsection><info><title>Description</title></info>
+
+<para>If <parameter>make.clean.html</parameter> 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.</para>
+
+<para>The resulting HTML is dependent on
+CSS for formatting, and so the stylesheet is capable of
+generating a supporting CSS file. The <parameter>docbook.css.source</parameter>
+and <paramter>custom.css.source</paramter> parameters control
+how a CSS file is generated.</para>
+
+<para>If you require your CSS to reside in the HTML
+<tag>head</tag> element, then the <parameter>generate.css.header</parameter>
+can be used to do that.</para>
+
+<para>The <parameter>make.clean.html</parameter> parameter is
+different from <parameter>html.cleanup</parameter>
+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.</para>
+
+<para>If <parameter>make.clean.html</parameter> is set to zero (the default),
+then the stylesheet retains its original
+<quote>old style</quote>
+HTML formatting features.</para>
+</refsection>
+</refentry>
projects / docbook-dsssl / commitdiff