source: pst/xml/docbook-xsl.xml@ a53c912

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY path "https://github.com/docbook/xslt10-stylesheets/releases/download/release">

  <!ENTITY docbook-xsl-download-http "&path;/&docbook-xsl-version;/docbook-xsl-nons-&docbook-xsl-version;.tar.bz2">
  <!ENTITY docbook-xsl-download-ftp  " ">
  <!ENTITY docbook-xsl-md5sum        "2666d1488d6ced1551d15f31d7ed8c38">
  <!ENTITY docbook-xsl-size          "22 MB">
  <!ENTITY docbook-xsl-buildsize     "58 MB (includes installing optional documentation)">
  <!ENTITY docbook-xsl-time          "less than 0.1 SBU">

  <!ENTITY docbook-xsl-doc-download  "&path;/&docbook-xsl-version;/docbook-xsl-doc-&docbook-xsl-version;.tar.bz2">
  <!ENTITY docbook-xsl-doc-md5sum    "62375ca864fc198cb2b17d98209d0b8c">
  <!ENTITY docbook-xsl-doc-size      "522 KB">
]>

<sect1 id="docbook-xsl"
xreflabel="docbook-xsl-nons-&docbook-xsl-version;">
  <?dbhtml filename="docbook-xsl.html"?>


  <title>docbook-xsl-nons-&docbook-xsl-version;</title>

  <indexterm zone="docbook-xsl">
    <primary sortas="a-DocBook-XSL-Stylesheets">DocBook XSL
    Stylesheets</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to DocBook XSL Stylesheets</title>

    <para>
      The <application>DocBook XSL Stylesheets</application>
      package contains XSL stylesheets. These are useful for
      performing transformations on XML DocBook files.
    </para>

    &lfs120_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&docbook-xsl-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&docbook-xsl-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &docbook-xsl-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &docbook-xsl-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &docbook-xsl-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &docbook-xsl-time;
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing='compact'>
      <listitem>
        <para>
          Required patch: <ulink url=
            "&patch-root;/docbook-xsl-nons-&docbook-xsl-version;-stack_fix-1.patch"/>
        </para>
      </listitem>
    </itemizedlist>

    <itemizedlist spacing="compact">
      <title>Optional documentation</title>
      <listitem>
        <para>
          Download (HTTP): <ulink url="&docbook-xsl-doc-download;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &docbook-xsl-doc-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &docbook-xsl-doc-size;
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">DocBook XSL Stylesheets Dependencies</bridgehead>

    <bridgehead renderas="sect4">Recommended (at runtime)</bridgehead>
    <para role="recommended">
      <xref role="runtime" linkend="libxml2"/>
    </para>

    <bridgehead renderas="sect4">Optional (all used at runtime)</bridgehead>
    <para role="optional">
      <xref role="runtime" linkend="apache-ant"/>
         (to produce <quote>webhelp</quote> documents),
      <xref role="runtime"  linkend="libxslt"/>
         (or any other XSLT processor), to process
          Docbook documents,
      <xref role="runtime" linkend="ruby"/>
         (to utilize the <quote>epub</quote> stylesheets),
      <xref role="runtime" linkend="zip"/>
         (to produce <quote>epub3</quote> documents), and
      <ulink url="https://sourceforge.net/projects/saxon/files/saxon6/">
        Saxon6
      </ulink> and
      <ulink url="http://xerces.apache.org/xerces2-j/">Xerces2 Java</ulink>
         (used with <xref role="runtime" linkend="apache-ant"/>
          to produce <quote>webhelp</quote> documents)
    </para>


  </sect2>

  <sect2 role="installation">
    <title>Installation of DocBook XSL Stylesheets</title>

    <para>
      First, fix a problem that causes stack overflows when doing recursion:
    </para>

<screen><userinput>patch -Np1 -i ../docbook-xsl-nons-&docbook-xsl-version;-stack_fix-1.patch</userinput></screen>

    <para>
      If you downloaded the optional documentation tarball, unpack it
      with the following command:
    </para>

<screen><userinput>tar -xf ../docbook-xsl-doc-&docbook-xsl-version;.tar.bz2 --strip-components=1</userinput></screen>

    <para>
      BLFS does not install the required packages to run the test suite
      and provide meaningful results.
    </para>

    <para>
      Install <application>DocBook XSL Stylesheets</application>
      by running the following commands as the
      <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>install -v -m755 -d /usr/share/xml/docbook/xsl-stylesheets-nons-&docbook-xsl-version; &amp;&amp;

cp -v -R VERSION assembly common eclipse epub epub3 extensions fo        \
         highlighting html htmlhelp images javahelp lib manpages params  \
         profiling roundtrip slides template tests tools webhelp website \
         xhtml xhtml-1_1 xhtml5                                          \
    /usr/share/xml/docbook/xsl-stylesheets-nons-&docbook-xsl-version; &amp;&amp;

ln -s VERSION /usr/share/xml/docbook/xsl-stylesheets-nons-&docbook-xsl-version;/VERSION.xsl &amp;&amp;

install -v -m644 -D README \
                    /usr/share/doc/docbook-xsl-nons-&docbook-xsl-version;/README.txt &amp;&amp;
install -v -m644    RELEASE-NOTES* NEWS* \
                    /usr/share/doc/docbook-xsl-nons-&docbook-xsl-version;</userinput></screen>

    <para>
      If you downloaded the optional documentation tarball, install the
      documentation by issuing the following command as the
      <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>cp -v -R doc/* /usr/share/doc/docbook-xsl-nons-&docbook-xsl-version;</userinput></screen>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring DocBook XSL Stylesheets</title>

    <sect3 id="docbook-xsl-config">
      <title>Config Files</title>

      <para>
        <filename>/etc/xml/catalog</filename>
      </para>

      <indexterm zone="docbook-xsl docbook-xsl-config">
        <primary sortas="e-etc-xml-catalog">/etc/xml/catalog</primary>
      </indexterm>

    </sect3>

    <sect3>
      <title>Configuration Information</title>

      <note>
        <para>
          If you are installing the current version of docbook-xsl-nons
          over a previous version of docbook-xsl, then remove the old
          rewrite entries in the catalog as the <systemitem
          class="username">root</systemitem> user:
        </para>

<screen role="nodump"><userinput>sed -i '/rewrite/d' /etc/xml/catalog</userinput></screen>
      </note>

      <para>
        Create (or append) and populate the XML catalog file using the
        following commands as the <systemitem
        class="username">root</systemitem> user (both <emphasis>http</emphasis>
        and <emphasis>https</emphasis> forms are used because upstream
        have had both in their documentation):
      </para>

<screen role="root"><userinput>if [ ! -d /etc/xml ]; then install -v -m755 -d /etc/xml; fi &amp;&amp;
if [ ! -f /etc/xml/catalog ]; then
    xmlcatalog --noout --create /etc/xml/catalog
fi &amp;&amp;

xmlcatalog --noout --add "rewriteSystem" \
           "http://cdn.docbook.org/release/xsl-nons/&docbook-xsl-version;" \
           "/usr/share/xml/docbook/xsl-stylesheets-nons-&docbook-xsl-version;" \
    /etc/xml/catalog &amp;&amp;

xmlcatalog --noout --add "rewriteSystem" \
           "https://cdn.docbook.org/release/xsl-nons/&docbook-xsl-version;" \
           "/usr/share/xml/docbook/xsl-stylesheets-nons-&docbook-xsl-version;" \
    /etc/xml/catalog &amp;&amp;

xmlcatalog --noout --add "rewriteURI" \
           "http://cdn.docbook.org/release/xsl-nons/&docbook-xsl-version;" \
           "/usr/share/xml/docbook/xsl-stylesheets-nons-&docbook-xsl-version;" \
    /etc/xml/catalog &amp;&amp;

xmlcatalog --noout --add "rewriteURI" \
           "https://cdn.docbook.org/release/xsl-nons/&docbook-xsl-version;" \
           "/usr/share/xml/docbook/xsl-stylesheets-nons-&docbook-xsl-version;" \
    /etc/xml/catalog &amp;&amp;

xmlcatalog --noout --add "rewriteSystem" \
           "http://cdn.docbook.org/release/xsl-nons/current" \
           "/usr/share/xml/docbook/xsl-stylesheets-nons-&docbook-xsl-version;" \
    /etc/xml/catalog &amp;&amp;

xmlcatalog --noout --add "rewriteSystem" \
           "https://cdn.docbook.org/release/xsl-nons/current" \
           "/usr/share/xml/docbook/xsl-stylesheets-nons-&docbook-xsl-version;" \
    /etc/xml/catalog &amp;&amp;

xmlcatalog --noout --add "rewriteURI" \
           "http://cdn.docbook.org/release/xsl-nons/current" \
           "/usr/share/xml/docbook/xsl-stylesheets-nons-&docbook-xsl-version;" \
    /etc/xml/catalog &amp;&amp;

xmlcatalog --noout --add "rewriteURI" \
           "https://cdn.docbook.org/release/xsl-nons/current" \
           "/usr/share/xml/docbook/xsl-stylesheets-nons-&docbook-xsl-version;" \
    /etc/xml/catalog &amp;&amp;

xmlcatalog --noout --add "rewriteSystem" \
           "http://docbook.sourceforge.net/release/xsl/current" \
           "/usr/share/xml/docbook/xsl-stylesheets-nons-&docbook-xsl-version;" \
    /etc/xml/catalog &amp;&amp;

xmlcatalog --noout --add "rewriteURI" \
           "http://docbook.sourceforge.net/release/xsl/current" \
           "/usr/share/xml/docbook/xsl-stylesheets-nons-&docbook-xsl-version;" \
    /etc/xml/catalog</userinput></screen>

      <para>
        Occasionally, you may find the need to install other versions of the
        XSL stylesheets as some projects reference a specific version. One
        example is BLFS-6.0, which required the 1.67.2 version. In these
        instances you should install any other required version in its own
        versioned directory and create catalog entries as follows (substitute
        the desired version number for
        <replaceable>&lt;version&gt;</replaceable>):
      </para>

<screen role="nodump"><userinput>xmlcatalog --noout --add "rewriteSystem" \
           "http://docbook.sourceforge.net/release/xsl/<replaceable>&lt;version&gt;</replaceable>" \
           "/usr/share/xml/docbook/xsl-stylesheets-<replaceable>&lt;version&gt;</replaceable>" \
    /etc/xml/catalog &amp;&amp;

xmlcatalog --noout --add "rewriteURI" \
           "http://docbook.sourceforge.net/release/xsl/<replaceable>&lt;version&gt;</replaceable>" \
           "/usr/share/xml/docbook/xsl-stylesheets-<replaceable>&lt;version&gt;</replaceable>" \
    /etc/xml/catalog</userinput></screen>

    </sect3>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Files</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>/usr/share/xml/docbook/xsl-stylesheets-nons-&docbook-xsl-version;/*/*.xsl</seg>
        <seg>/usr/share/xml/docbook/xsl-stylesheets-nons-&docbook-xsl-version; and
        /usr/share/doc/docbook-xsl-nons-&docbook-xsl-version;</seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="xsl-stylesheets">
        <term><filename>XSL Stylesheets</filename></term>
        <listitem>
          <para>
            are used for performing transformations on XML files
          </para>
          <indexterm zone="docbook-xsl xsl-stylesheets">
            <primary sortas="g-XSL-Stylesheets">XSL Stylesheets</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>