File: daps_user_modularize.xml

package info (click to toggle)
daps 3.3.2%2Bcleaned1-4
links: PTS, VCS
area: main
in suites: bookworm
size: 5,536 kB
sloc: xml: 9,773; sh: 3,059; python: 1,322; lisp: 380; makefile: 239
file content (1322 lines) | stat: -rw-r--r-- 47,391 bytes
parent folder | download | duplicates (3)
<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet
 href="urn:x-daps:xslt:profiling:docbook45-profile.xsl"
 type="text/xml"
 title="Profiling step"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.docbook.org/xml/4.5/docbookx.dtd"
[<!ENTITY % entities SYSTEM "entity-decl.ent">
%entities;
]>
<chapter id="cha.daps.user.modular">
 <title>Modularizing Documentation Projects</title>
 <para>
  This chapter covers the following topics:
  <itemizedlist>
   <listitem>
    <para>
     Modularizing documents by splitting them into XIncludes
    </para>
   </listitem>
   <listitem>
    <para>
     Using a consistent set of entities throughout a documentation
     project
    </para>
   </listitem>
   <listitem>
    <para>
      Creating document variants <remark>dpopov 2016-10-12: editions instead variants?</remark>
      by using profiling
    </para>
   </listitem>
   <listitem>
    <para>
     Combining profiling and entities
    </para>
   </listitem>
  </itemizedlist>
 </para>
 <sect1 id="sec.daps.user.modular.xi">
  <title>Splitting up Documents into XIncludes</title>

  <para>
   Instead of putting the contents of a complete article or book into the
   &main; file, DocBook allows you to divide <remark>dpopov 2016-10-12:
   s/divide/split ?</remark> the text into separate document files. They are
   then assembled in the &main; file using <literal>XIncludes</literal> as
   shown in <xref linkend="ex.daps.main.set"/>. XIncludes can be used for
   splitting up sets, books, articles or chapters into separate files. For
   more information, refer to
   <ulink url="http://www.docbook.org/tdg51/en/html/ch02.html">
   <citetitle>Physical Divisions: Breaking a Document into Separate
   Files</citetitle> </ulink>.
  </para>

  <para>
   XIncludes are fully supported and do not cause any problems with
   &dapsacr;. For example, <command>daps</command> commands like
   <command>linkcheck</command> or <command>spellcheck</command> also follow XIncludes.
  </para>
 </sect1>
 <sect1 id="sec.daps.user.modular.ent.separate">
  <title>Declaring Entities in a Separate File</title>

  <para>
   When maintaining a large number of documents for a product, it can be
   difficult to keep a consistent set of entities if these entities are
   declared in the document type declarations of
   <emphasis>individual</emphasis> XML files. For large documentation
   projects, it is therefore useful to put all entity declarations into a
   separate file and reference that file in the individual XML files.
  </para>

  <example id="ex.daps.ent.decl.separate">
   <title>Separate Entity File <filename>entity-decl.ent</filename></title>
<screen>&lt;?xml version="1.0" encoding="iso-8859-1" ?&gt;
&lt;!ENTITY exampleuser "tux"&gt;
&lt;!ENTITY exampleuserII "wilber"&gt;
&lt;!ENTITY examplegroup "users"&gt;
[...]</screen>
  </example>

  <example id="ex.daps.ent.decl.reference">
   <title>Referencing A Separate Entity File</title>
<screen>&lt;?xml version="1.0"?&gt;
&lt;!DOCTYPE chapter PUBLIC [...]
[
  &lt;!ENTITY % entities SYSTEM "entity-decl.ent"> <co id="co.daps.main.reference.ent"/>
  %entities; <co id="co.daps.main.reference.load"/>
]&gt;
&lt;chapter&gt;
&lt;title&gt;Managing User Accounts&lt;/title&gt;
[...]</screen>
   <calloutlist>
    <callout arearefs="co.daps.main.reference.ent">
     <para>
      Reference to the separate entity declaration file (with the
       <sgmltag class="starttag">!ENTITY</sgmltag> keyword).
     </para>
    </callout>
    <callout arearefs="co.daps.main.reference.load">
      <para>Loads the external entity file declared in the previous line.</para>
     </callout>
   </calloutlist>
  </example>

  <para>
   For more information, refer to
   <ulink url="http://www.sagehill.net/docbookxsl/ModularDoc.html">
   <citetitle>Modular DocBook Files: Shared text entities</citetitle></ulink>.
  </para>

  <para>
   Separate entity files do not cause any problems with &dapsacr;&mdash;
   during generation of output, the entities will be treated equally to
   entities declared in individual XML files.
  </para>
  <para>It is also possible to use multiple entity files by including them into
  the separate entity file that is referenced in the XML file.</para>
  <example id="ex.daps.ent.decl.separate.multi">
   <title>Referencing Entity Files Within an Entity File</title>
  <screen>&lt;?xml version="1.0" encoding="iso-8859-1" ?&gt;
&lt;!ENTITY exampleuser "tux"&gt;
&lt;!ENTITY exampleuserII "wilber"&gt;
&lt;!ENTITY examplegroup "users"&gt;
[...]
&lt;!ENTITY % network-entities SYSTEM "network-decl.ent"> <xref linkend="co.daps.main.reference.ent" xrefstyle="select:label nopage"/>
%network-entities; <xref linkend="co.daps.main.reference.load" xrefstyle="select:label nopage"/>
&lt;!ENTITY % more-entities SYSTEM "another-decl.ent"> <xref linkend="co.daps.main.reference.ent" xrefstyle="select:label nopage"/>
%more-entities; <xref linkend="co.daps.main.reference.load" xrefstyle="select:label nopage"/>
</screen>
<calloutlist>
    <callout arearefs="co.daps.main.reference.ent">
     <para>
      Reference to the separate entity declaration file (with the
       <sgmltag class="starttag">!ENTITY</sgmltag> keyword).
     </para>
    </callout>
    <callout arearefs="co.daps.main.reference.load">
      <para>Loads the external entity file declared in the previous line.</para>
     </callout>
   </calloutlist>
  </example>
 </sect1>
 <sect1 id="sec.daps.user.modular.profile">
  <title>Profiling&mdash;Support for Document Variants</title>
  &db-profiling-intro;
  &db-profiling;

 <sect2 id="sec.daps.user.modular.profile.basics">
   <title>Introduction to DocBook Profiling</title>
   <para>
    DocBook offers profiling attributes for various purposes as illustrated
    in <ulink url="http://www.sagehill.net/docbookxsl/Profiling.html">
    <citetitle>Table 26.1. Profiling attributes</citetitle> </ulink>.
    All of them are supported by &dapsacr;.
    <!--Currently, not all of them are supported by &dapsacr;. For details,
    refer to <xref linkend="sec.daps.user.modular.profile.daps"/>.-->
   </para>
   <para>
    Generally, profiling attributes can be used on many
    elements&mdash;from high-level elements like <sgmltag>book</sgmltag> or
    <sgmltag>chapter</sgmltag> down to low-level elements like
    <sgmltag>para</sgmltag>. With the <sgmltag>phrase</sgmltag> element, you
    can even profile inline elements, like one sentence within a paragraph.
<!--, see <xref linkend="ex.daps.profiling.inline"/>.-->
   </para>
   <para>
    Based on the conditions that you want to apply <remark>dpopov 2016-10-12:
    define conditions?</remark> , select one or more profiling attributes and
    add them to the text snippets that are conditional. The tagged snippets
    will only be included in the output if the required condition is
    fulfilled. Any content that is valid for <emphasis>all</emphasis>
    conditions does <emphasis>not</emphasis> need any profiling
    attributes. The respective content will always be included in the output
    formats generated from the XML sources. You are free in defining the
    attribute values (<literal>condition="foo"</literal>), but they must be
    used consistently in all files belonging to a documentation project.
   </para>
   <para>
    <xref linkend="ex.daps.profile.one"/> shows how to profile
    product-specific information in a software description. Let us assume we
    need to write documentation for the fictional software <literal>Frog
    Sound Recordings</literal>. The software is available in two editions: a
    basic edition for home users and a professional edition for enterprise
    customers. Both editions share common features, but some features are
    only available in the basic or the professional edition, respectively.
   </para>
   <example id="ex.daps.profile.one">
    <title>Product-specific Profiling (One Attribute)</title>
<screen>&lt;simplelist&gt;
  &lt;member&gt;Common Feature 1&lt;/member&gt;
  &lt;member&gt;Common Feature 2&lt;/member&gt;
  &lt;member&gt;Common Feature 3&lt;/member&gt;
  <emphasis role="strong">&lt;member condition="basic"&gt;Basic Feature 1&lt;/member&gt;
  &lt;member condition="prof"&gt;Professional Feature 1&lt;/member&gt;
  &lt;member condition="prof"&gt;Professional Feature 2&lt;/member&gt;</emphasis>
&lt;/simplelist&gt;</screen>
   </example>
   <para>
    When generated for the basic edition or for the professional edition,
    respectively, the example source code would result in the following
    output:
   </para>
   <table id="tab.daps.profile.output.one" rowsep="1">
    <title>Output of <xref linkend="ex.daps.profile.one" xrefstyle="select:
     label"/></title>
    <tgroup cols="2">
     <colspec colnum="1" colname="1" colwidth="50*"/>
     <colspec colnum="2" colname="2" colwidth="50*"/>
     <thead>
      <row>
       <entry colname="1">
        <para>
         Basic Edition
        </para>
       </entry>
       <entry colname="2">
        <para>
         Professional Edition
        </para>
       </entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry colname="1">
        <para>
         Common Feature 1
        </para>
        <para>
         Common Feature 2
        </para>
        <para>
         Common Feature 3
        </para>
        <para>
         Basic Feature 1
        </para>
       </entry>
       <entry colname="2">
        <para>
         Common Feature 1
        </para>
        <para>
         Common Feature 2
        </para>
        <para>
         Common Feature 3
        </para>
        <para>
         Professional Feature 1
        </para>
        <para>
         Professional Feature 2
        </para>
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
   <para>
    If the profiling attributes are <emphasis>not</emphasis> processed
    during output, the source code in <xref linkend="ex.daps.profile.one"/>
    would result in the following (identical) output for both editions:
   </para>
   <table id="tab.daps.profile.output.one.without" rowsep="1">
    <title>Output of <xref linkend="ex.daps.profile.one" xrefstyle="select:
     label"/> (Without Profiling)</title>
    <tgroup cols="2">
     <colspec colnum="1" colname="1" colwidth="50*"/>
     <colspec colnum="2" colname="2" colwidth="50*"/>
     <thead>
      <row>
       <entry colname="1">
        <para>
         Basic Edition
        </para>
       </entry>
       <entry colname="2">
        <para>
         Professional Edition
        </para>
       </entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry colname="1">
        <para>
         Common Feature 1
        </para>
        <para>
         Common Feature 2
        </para>
        <para>
         Common Feature 3
        </para>
        <para>
         Basic Feature 1
        </para>
        <para>
         Professional Feature 1
        </para>
        <para>
         Professional Feature 2
        </para>
       </entry>
       <entry colname="2">
        <para>
         Common Feature 1
        </para>
        <para>
         Common Feature 2
        </para>
        <para>
         Common Feature 3
        </para>
        <para>
         Basic Feature 1
        </para>
        <para>
         Professional Feature 1
        </para>
        <para>
         Professional Feature 2
        </para>
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
   <para>
    Let us suppose the professional edition of the software is also available
    as OEM (original equipment manufacturer) version by the vendor
    <literal>OEM Company</literal>. It contains additional features that are
    only available in the OEM version:
   </para>
   <example id="ex.daps.profile.two">
    <title>Product-specific Profiling (Multiple Attributes)</title>
<screen>&lt;simplelist&gt;
  &lt;member&gt;Common Feature 1&lt;/member&gt;
  &lt;member&gt;Common Feature 2&lt;/member&gt;
  &lt;member&gt;Common Feature 3&lt;/member&gt;
  &lt;member condition="basic"&gt;Basic Feature 1&lt;/member&gt;
  &lt;member condition="prof"&gt;Professional Feature 1&lt;/member&gt;
  &lt;member condition="prof"&gt;Professional Feature 2&lt;/member&gt;
 <emphasis role="strong"> &lt;member condition="prof" vendor="oemcompany"&gt;OEM Feature 1&lt;/member&gt;</emphasis>
&lt;/simplelist&gt;</screen>
   </example>
   <para>
    When generated for the professional edition or for the professional
    edition in the OEM version, respectively, the example source code would
    result in the following output:
   </para>
   <table id="tab.daps.profile.output.two" rowsep="1">
    <title>Output of <xref linkend="ex.daps.profile.two" xrefstyle="select:
     label"/></title>
    <tgroup cols="2">
     <colspec colnum="1" colname="1" colwidth="50*"/>
     <colspec colnum="2" colname="2" colwidth="50*"/>
     <thead>
      <row>
       <entry colname="1">
        <para>
         Professional Edition
        </para>
       </entry>
       <entry colname="2">
        <para>
         Professional Edition (OEM Version)
        </para>
       </entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry colname="1">
        <para>
         Common Feature 1
        </para>
        <para>
         Common Feature 2
        </para>
        <para>
         Common Feature 3
        </para>
        <para>
         Professional Feature 1
        </para>
        <para>
         Professional Feature 2
        </para>
       </entry>
       <entry colname="2">
        <para>
         Common Feature 1
        </para>
        <para>
         Common Feature 2
        </para>
        <para>
         Common Feature 3
        </para>
        <para>
         Professional Feature 1
        </para>
        <para>
         Professional Feature 2
        </para>
        <para>
         OEM Feature 1
        </para>
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
   <remark>toms 2012-09-25: Maybe describe the use of two or more profiling
    values in _one_ attribute? Could be useful.
    - taroth 2014-10-24: https://trello.com/c/pvdqvCwZ</remark>
  </sect2>

  <sect2 id="sec.daps.user.modular.profile.daps">
   <title>Using Profiling with &dapsacr;</title>
   <para>
    To create multiple documentation variants of the same pool of DocBook
    files with &dapsacr;, the following requirements need to be fulfilled:
   </para>
   <orderedlist>
    <listitem>
<!--XML Files: Profiling Attributes-->
     <para>
      <xref linkend="sec.daps.user.modular.profile.daps.pa" xrefstyle="select:title"/>
     </para>
    </listitem>
    <listitem>
<!--&main; file: Processing Instruction-->
     <para>
      <xref linkend="sec.daps.user.modular.profile.daps.pi" xrefstyle="select: title"/>
     </para>
    </listitem>
    <listitem>
<!--&dc; File: Profiling Parameters-->
     <para>
      <xref linkend="sec.daps.user.modular.profile.daps.pp" xrefstyle="select: title"/>
     </para>
    </listitem>
   </orderedlist>
   <para>
    For a comprehensive example showing all requirements in detail, refer to
    <xref linkend="sec.daps.user.modular.profile.daps.ex"/>.
   </para>
   <sect3 id="sec.daps.user.modular.profile.daps.pa">
    <title>XML Files: Profiling Attributes</title>
    <para>
     In &dapsacr;, each profiling attribute has a corresponding profiling parameter to be used in the
     &dc; file, see <xref linkend="sec.daps.user.modular.profile.daps.pp"/>.
     The profiling parameters define which profiling attributes
     and values to interpret during generation of output.
    </para>
    <para>The names of the profiling parameters are derived from the profiling
     attributes, but written in uppercase letters and preceded by the prefix
     <literal>PROF</literal>.
    </para>
     <table id="tab.daps.profiling" rowsep="1">
     <title>Profiling Attributes (DocBook) and Profiling Parameters (&dapsacr;)</title>
     <tgroup cols="3">
      <colspec colnum="1" colname="1" colwidth="20*"/>
      <colspec colnum="2" colname="2" colwidth="50*"/>
      <colspec colnum="3" colname="3" colwidth="30*"/>
      <thead>
       <row>
        <entry colname="1">
         <para>
          Attribute Name
         </para>
        </entry>
        <entry colname="2">
         <para>
          Use
         </para>
        </entry>
        <entry colname="3">
         <para>
          Profiling Parameter
         </para>
        </entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry colname="1">
         <para>
          <sgmltag class="attribute">arch</sgmltag>
         </para>
        </entry>
        <entry colname="2">
         <para>
          Computer or chip architecture, such as <literal>i386</literal>.
         </para>
        </entry>
        <entry colname="3"><parameter>PROFARCH</parameter>
        </entry>
       </row>
       <row>
        <entry colname="1">
         <para>
          <sgmltag class="attribute">audience</sgmltag>
         </para>
        </entry>
        <entry colname="2">
         <para>
          Intended audience of the content, such as <literal>instructor</literal>. Added in DocBook version 5.0.
         </para>
        </entry>
        <entry colname="3"><parameter>PROFAUDIENCE</parameter>
        </entry>
       </row>
       <row>
        <entry colname="1">
         <para>
          <sgmltag class="attribute">condition</sgmltag>
         </para>
        </entry>
        <entry colname="2">
         <para>
          No preassigned semantics, general purpose attribute.
         </para>
        </entry>
        <entry colname="3"><parameter>PROFCONDITION</parameter>
        </entry>
       </row>
       <row>
        <entry colname="1">
         <para>
          <sgmltag class="attribute">conformance</sgmltag>
         </para>
        </entry>
        <entry colname="2">
         <para>
          Conformance to standards, as for example <literal>lsb</literal> (Linux Standards Base).
         </para>
        </entry>
        <entry colname="3"><parameter>PROFCONFORMANCE</parameter>
        </entry>
       </row>
       <row>
        <entry colname="1">
         <para>
          <sgmltag class="attribute">lang</sgmltag>
         </para>
        </entry>
        <entry colname="2">
         <para>
          Language code, such as <literal>de_DE</literal>.
         </para>
        </entry>
        <entry colname="3"><parameter>PROFLANG</parameter>
        </entry>
       </row>
       <row>
        <entry colname="1">
         <para>
          <sgmltag class="attribute">os</sgmltag>
         </para>
        </entry>
        <entry colname="2">
         <para>
          Operating system.
         </para>
        </entry>
        <entry colname="3"><parameter>PROFOS</parameter>
        </entry>
       </row>
       <row>
        <entry colname="1">
         <para>
          <sgmltag class="attribute">outputformat</sgmltag>
         </para>
        </entry>
        <entry colname="2">
         <para>
          Output format to which the element applies (for example, print or
          &epub;). Only available for DocBook 5.1 or later.
         </para>
        </entry>
        <entry colname="3"><parameter>PROFOUTPUTFORMAT</parameter>
        </entry>
       </row>
       <row>
        <entry colname="1">
         <para>
          <sgmltag class="attribute">revision</sgmltag>
         </para>
        </entry>
        <entry colname="2">
         <para>
          Editorial revision, such as <literal>v2.1</literal>.
         </para>
        </entry>
        <entry colname="3"><parameter>PROFREVISION</parameter>
        </entry>
       </row>
       <row>
        <entry colname="1">
         <para>
          <sgmltag class="attribute">revisionflag</sgmltag>
         </para>
        </entry>
        <entry colname="2">
         <para>
          Revision status of the element, such as <literal>changed</literal>. This attribute has a fixed set of values to choose from.
         </para>
        </entry>
        <entry colname="3"><parameter>PROFREVISIONFLAG</parameter>
        </entry>
       </row>
       <row>
        <entry colname="1">
         <para>
          <sgmltag class="attribute">role </sgmltag>
         </para>
        </entry>
        <entry colname="2">
         <para> General purpose attribute, with no preassigned semantics. As the
          role attribute is not solely <quote>reserved</quote> for profiling but
          can be used for other purposes in a document, we would recommend
          to not use this for profiling. For further details, see <ulink
           url="http://sagehill.net/docbookxsl/ProfilingWithRole.html"/>.</para>
        </entry>
        <entry colname="3"><parameter>PROFROLE</parameter>
        </entry>
       </row>
       <row>
        <entry colname="1">
         <para>
          <sgmltag class="attribute">security</sgmltag>
         </para>
        </entry>
        <entry colname="2">
         <para>
          Security level, such as <literal>high</literal>.
         </para>
        </entry>
        <entry colname="3"><parameter>PROFSECURITY</parameter>
        </entry>
       </row>
       <row>
        <entry colname="1">
         <para>
          <sgmltag class="attribute">status</sgmltag>
         </para>
        </entry>
        <entry colname="2">
         <para>
          Editorial or publication status, such as <literal>InDevelopment</literal> or <literal>draft</literal>.
         </para>
        </entry>
        <entry colname="3"><parameter>PROFSTATUS</parameter>
        </entry>
       </row>
       <row>
        <entry colname="1">
         <para>
          <sgmltag class="attribute">userlevel</sgmltag>
         </para>
        </entry>
        <entry colname="2">
         <para>
          Level of user experience, such as <literal>beginner</literal>.
         </para>
        </entry>
        <entry colname="3"><parameter>PROFUSERLEVEL</parameter>
        </entry>
       </row>
       <row>
        <entry colname="1">
         <para>
          <sgmltag class="attribute">vendor</sgmltag>
         </para>
        </entry>
        <entry colname="2">
         <para>
          Product vendor.
         </para>
        </entry>
        <entry colname="3"><parameter>PROFVENDOR</parameter>
        </entry>
       </row>
       <row>
        <entry colname="1">
         <para>
          <sgmltag class="attribute">wordsize</sgmltag>
         </para>
        </entry>
        <entry colname="2">
         <para>
          Word size (width in bits) of the computer architecture, such as <literal>64bit</literal>. Added in DocBook version 4.4.
         </para>
        </entry>
        <entry colname="3"><parameter>PROFWORDSIZE</parameter>
        </entry>
       </row>
      </tbody>
     </tgroup>
    </table>
   </sect3>
   <sect3 id="sec.daps.user.modular.profile.daps.pi">
    <title>&main; File: Processing Instruction</title>
    <para>
     To activate generation of profiled output in &dapsacr;, the following
     processing instruction (PI) must be included in the header of the &main;
     file, before the root element.
    </para>
    <note>
     <title>Adjusting the DocBook Version in the PI</title>
     <para>As the profiling PI includes the DocBook version number, it needs to
      be adjusted according to the DocBook version you use. See <xref
       linkend="ex.daps.user.modular.pi.db4"/> and <xref
       linkend="ex.daps.user.modular.pi.db5"/>.</para>
   </note>
    <example id="ex.daps.user.modular.pi.db4">
     <title>Profiling PI in a DocBook 4.5 File</title>
        <screen>&lt;?xml-stylesheet
  href="urn:x-daps:xslt:profiling:docbook45-profile.xsl"
  type="text/xml" ?></screen>
    </example>

    <example id="ex.daps.user.modular.pi.db5">
     <title>Profiling PI in a DocBook 5.0 File</title>
     <screen>&lt;?xml-stylesheet
  href="urn:x-daps:xslt:profiling:docbook50-profile.xsl"
  type="text/xml" ?></screen>
    </example>
   <para>
     The &main; file of a documentation project is referenced
     by the <parameter>MAIN</parameter> parameter in the &dc; file. If the
     processing instruction is missing in the &main; file, any profiling
     parameters in the &dc; file will be ignored during generation of the
     output.
    </para>
    <tip>
     <title>Include PI in All XML Files</title>
     <para>
      Although &dapsacr; only checks for the profiling PI in the &main; file, it
      is a good idea to  include the PI in all XML files for any projects that
      need profiling. Otherwise you might forget to move
      the PI to the respective &main; file in case of restructuring the XML
      sources. Having the PI in all
      XML files does not hurt: Generation of profiled output is only
      triggered if your &dc; files contain profiling parameters.
     </para>
    </tip>
   </sect3>
   <sect3 id="sec.daps.user.modular.profile.daps.pp">
    <title>&dc; Files: Profiling Parameters</title>
    <para>
     Depending on the profiling attributes used in your XML files, a &dc;
     file may contain multiple profiling parameters, see
     <xref linkend="tab.daps.profiling"/>. Profiling parameters define which
     of the profiling attributes should be interpreted by &dapsacr; when
     generating output. For each profiling parameter, set the respective
     attribute values for which you want to filter during the profiling
     process. The spelling of the values must be the same that is used in
     the XML files.
    </para>
   </sect3>
   <sect3 id="sec.daps.user.modular.profile.daps.ex">
    <title>Profiling Example</title>
    <para>
     In the following, find a comprehensive example that shows the basic
     &dapsacr; profiling requirements in more detail. It is based on the
     examples in <xref linkend="sec.daps.user.modular.profile.basics"/>
     about the fictional software <literal>Frog Sound Recordings</literal>. The
     software is available in a basic edition, a professional edition and a
     professional OEM edition, shipped by an OEM vendor. The following
     example shows <emphasis>all</emphasis> files that you need to consider
     (XML files, &main; file, and &dc; file).
    </para>
    <example id="ex.daps.xml.pa">
     <title>XML File With Profiling Attributes (DocBook 4.x)</title>
<screen><?dbsuse-fo font-size="0.70em"?>&lt;?xml version="1.0" encoding="utf-8"?&gt;
[...]

&lt;chapter id="frog.features"&gt;
 [...]
 &lt;simplelist&gt;
   &lt;member&gt;Common Feature 1&lt;/member&gt; <co id="co.daps.xml.no.prof.attr"/>
   &lt;member&gt;Common Feature 2&lt;/member&gt; <xref linkend="co.daps.xml.no.prof.attr" xrefstyle="select:label nopage"/>
   &lt;member&gt;Common Feature 3&lt;/member&gt; <xref linkend="co.daps.xml.no.prof.attr" xrefstyle="select:label nopage"/>
   &lt;member condition="basic"&gt;Basic Feature 1&lt;/member&gt; <co id="co.daps.xml.profcond.value1"/>
   &lt;member condition="prof"&gt;Professional Feature 1&lt;/member&gt; <co id="co.daps.xml.profcond.value2"/>
   &lt;member condition="prof"&gt;Professional Feature 2&lt;/member&gt; <xref linkend="co.daps.xml.profcond.value2" xrefstyle="select:label nopage"/>
   &lt;member condition="prof" vendor="oemcompany"&gt;OEM Feature 1&lt;/member&gt; <co id="co.daps.xml.profcond.profvendor"/>
 &lt;/simplelist&gt;
 [...]
&lt;/chapter&gt;</screen>
     <calloutlist>
      <callout arearefs="co.daps.xml.no.prof.attr">
       <para>
        Unprofiled list items. The common features 1-3 are available in all
        software editions or versions.
       </para>
      </callout>
      <callout arearefs="co.daps.xml.profcond.value1">
       <para>
        List item profiled with attribute
        <sgmltag class="attribute">condition</sgmltag> and attribute value
        <sgmltag class="attvalue">basic</sgmltag>.
        <literal>Basic&nbsp;Feature&nbsp;1</literal> is only available in
        the basic software edition for home users.
       </para>
      </callout>
      <callout arearefs="co.daps.xml.profcond.value2">
       <para>
        List item profiled with attribute
        <sgmltag class="attribute">condition</sgmltag> and attribute value
        <sgmltag class="attvalue">prof</sgmltag>.
        <literal>Professional&nbsp;Feature&nbsp;1</literal> and
        <literal>Professional&nbsp;Feature&nbsp;2</literal> are only
        available in the professional software edition for enterprise
        customers.
       </para>
      </callout>
      <callout arearefs="co.daps.xml.profcond.profvendor">
       <para>
        List item profiled with two attributes: Attribute
        <sgmltag class="attribute">condition</sgmltag> with attribute value
        <sgmltag class="attvalue">prof</sgmltag> and attribute
        <sgmltag class="attribute">vendor</sgmltag> with attribute value
        <sgmltag class="attvalue">oemcompany</sgmltag>.
        <literal>OEM&nbsp;Feature&nbsp;1</literal> is only available in the
        professional OEM software edition for enterprise customers.
       </para>
      </callout>
     </calloutlist>
    </example>

    <example id="ex.daps.main.pi.db4">
     <title>&main; file With PI for Profiling (DocBook 4.5)</title>
<screen>&lt;?xml version="1.0" encoding="utf-8"?&gt;
<emphasis role="strong">&lt;?xml-stylesheet
 href="urn:x-daps:xslt:profiling:docbook45-profile.xsl"
 type="text/xml"
 title="Profiling step"?&gt;</emphasis>
&lt;!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
                         "http://www.docbook.org/xml/4.5/docbookx.dtd"
[&lt;!ENTITY % entities SYSTEM "entity-decl.ent">
%entities;
]&gt;

&lt;!--the following article is contained in the file art_frog.xml--&gt;

&lt;article lang="en" id="art.frog"&gt;
 &lt;title&gt;Frog Sound Recordings&lt;/title&gt;
 &lt;subtitle&gt;Product Description&lt;/subtitle&gt;
 [...]
&lt;/article&gt;</screen>
        <para>
         If the processing instruction (PI)  is
        missing, any profiling parameters in the &dc; file will be ignored.
       </para>
     </example>

<example id="ex.daps.main.pi.db5">
     <title>&main; file With PI for Profiling (DocBook 5.0)</title>
<screen>&lt;?xml version="1.0" encoding="utf-8"?&gt;
<emphasis role="strong">&lt;?xml-stylesheet
 href="urn:x-daps:xslt:profiling:docbook50-profile.xsl"
 type="text/xml"
 title="Profiling step"?&gt;</emphasis>
&lt;!DOCTYPE article
[&lt;!ENTITY % entities SYSTEM "entity-decl.ent">
%entities;
]&gt;

&lt;!--the following article is contained in the file art_frog.xml--&gt;

&lt;article xml:lang="en" xml:id="art.frog"
   xmlns="http://docbook.org/ns/docbook"&gt;
 &lt;title&gt;Frog Sound Recordings&lt;/title&gt;
 &lt;subtitle&gt;Product Description&lt;/subtitle&gt;
 [...]
&lt;/article&gt;</screen>
        <para>
         If the processing instruction (PI)  is
        missing, any profiling parameters in the &dc; file will be ignored.
       </para>
       <para>
        Use the PI <sgmltag class="pi">xml-stylesheet
 href="urn:x-daps:xslt:profiling:docbook51-profile.xsl"
 type="text/xml" title="Profiling step"</sgmltag> for DocBook version 5.1.
       </para>
     </example>

    <example id="ex.daps.dc.pa.home">
     <title>&dc; File with Profiling for Home Edition</title>
<screen>## Doc Config File for Frog Sound Recordings
## (Home Edition)

## Mandatory Parameters
MAIN="art_frog.xml" <co id="co.dc.pa.main1"/>

## Profiling
PROFCONDITION="basic" <co id="co.dc.pa.profcond.basic"/>
[...]</screen>
     <calloutlist>
      <callout arearefs="co.dc.pa.main1">
       <para>
        <parameter>MAIN</parameter> parameter referencing the &main; file. See
        <xref linkend="ex.daps.main.pi.db4" xrefstyle="select:label"/>
        (DocBook&nbsp;4) or <xref
         linkend="ex.daps.main.pi.db5" xrefstyle="select:label"/> (DocBook&nbsp;5).
       </para>
      </callout>
      <callout arearefs="co.dc.pa.profcond.basic">
       <para>
        &dapsacr; profiling parameter for the
        <sgmltag class="attribute">condition</sgmltag> profiling attribute.
        It defines that XML elements tagged with
        <sgmltag class="attribute">condition="basic"</sgmltag> are included
        in the output.
       </para>
      </callout>
     </calloutlist>
    </example>
    <example id="ex.daps.dc.pa.prof">
     <title>&dc; File with Profiling for Professional Edition</title>
<screen>## Doc Config File for Frog Sound Recordings
## (Professional Edition)

## Mandatory Parameters
MAIN="art_frog.xml" <co id="co.dc.pa.main2"/>

## Profiling
PROFCONDITION="prof" <co id="co.dc.pa.profcond.prof1"/>
[...]</screen>
     <calloutlist>
      <callout arearefs="co.dc.pa.main2">
       <para>
        <parameter>MAIN</parameter> parameter referencing the &main; file. See
        <xref linkend="ex.daps.main.pi.db4" xrefstyle="select:label"/>
        (DocBook&nbsp;4) or <xref
         linkend="ex.daps.main.pi.db5" xrefstyle="select:label"/> (DocBook&nbsp;5).
       </para>
      </callout>
      <callout arearefs="co.dc.pa.profcond.prof1">
       <para>
        &dapsacr; profiling parameter for the
        <sgmltag class="attribute">condition</sgmltag> profiling attribute.
        It defines that XML elements tagged with
        <sgmltag class="attribute">condition="prof"</sgmltag> are included
        in the output.
       </para>
      </callout>
     </calloutlist>
    </example>
    <example id="ex.daps.dc.pa.prof.oem">
     <title>&dc; File with Profiling for Professional Edition (OEM Version)</title>
<screen>## Doc Config File for Frog Sound Recordings
## (Professional Edition, OEM Version)

## Mandatory Parameters
MAIN="art_frog.xml" <co id="co.dc.pa.main3"/>

## Profiling
PROFCONDITION="prof" <co id="co.dc.pa.profcond.prof2"/>
PROFVENDOR="oemcompany" <co id="co.dc.pa.profvendor.oem"/>
[...]</screen>
     <calloutlist>
      <callout arearefs="co.dc.pa.main3">
       <para>
        <parameter>MAIN</parameter> parameter referencing the &main; file. See
        <xref linkend="ex.daps.main.pi.db4"/> or <xref
         linkend="ex.daps.main.pi.db5"/> .
       </para>
      </callout>
      <callout arearefs="co.dc.pa.profcond.prof2">
       <para>
        &dapsacr; profiling parameter for the
        <sgmltag class="attribute">condition</sgmltag> profiling attribute.
        It defines that XML elements tagged with
        <sgmltag class="attribute">condition="prof"</sgmltag> are included
        in the output.
       </para>
      </callout>
      <callout arearefs="co.dc.pa.profvendor.oem">
       <para>
        &dapsacr; profiling parameter for the
        <sgmltag class="attribute">vendor</sgmltag> profiling attribute. It
        defines that XML elements tagged with
        <sgmltag class="attribute">vendor="oemcompany"</sgmltag> are
        included in the output.
       </para>
      </callout>
     </calloutlist>
    </example>
   </sect3>
  </sect2>
 </sect1>
 <sect1 id="sec.daps.user.modular.productentities">
  <title>Combining Entities and Profiling</title>

  <para>
   For maximum flexibility in generating documentation variants from the
   same source, &dapsacr; also supports the combination of entities and
   profiling. As you already learned in
   <xref linkend="sec.daps.user.modular.ent.separate"/>, it is useful for
   modularization purposes to declare entities in a separate file and to
   re-use it in multiple documentation projects. </para>
  <para>For multiple use of entities like <literal>&amp;productname;</literal> or
   <literal>&amp;productnumber;</literal>, declare them in a separate file
   and add profiling within the entities as shown in
   <xref linkend="ex.daps.ent.decl.profiling" xrefstyle="select:label"/>. During generation of
   output, &dapsacr; then automatically replaces the entities with different
   values during output, depending on the context.
  </para>

  <example id="ex.daps.ent.decl.profiling">
   <title>Separate Entity File with Profiling Attributes (DocBook 5.0)</title>
<screen><?dbsuse-fo font-size="0.60em"?>&lt;!--the following declarations are contained in the file entity-decl.ent --&gt;

&lt;!ENTITY productname
 <emphasis role="strong">'&lt;phrase cond="basic"&gt;Frog Sound Recordings (Basic)&lt;/phrase&gt;
  &lt;phrase cond="prof"&gt;Frog Sound Recordings (Professional)&lt;/phrase&gt;
  &lt;phrase cond="prof" vendor="oemcompany"&gt;Gecko Sound Recordings (Professional)&lt;/phrase&gt;'&gt;</emphasis>

&lt;!ENTITY productnumber
 <emphasis role="strong">'&lt;phrase cond="basic"&gt;1.0&lt;/phrase&gt;
  &lt;phrase cond="prof"&gt;4.2&lt;/phrase&gt;
  &lt;phrase cond="prof" vendor="oemcompany"&gt;4.21&lt;/phrase&gt;'&gt;</emphasis></screen>
  </example>

  <remark>taroth 2012-12-06: open issue - check with fs and toms why/if we
    need productname/productnumber in setinfo/bookinfo/articleinfo - toms' answer:
    https://github.com/openSUSE/daps/issues/48</remark>


   <procedure id="pro.daps.modular.productentities">
   <title>Using Product Entities with Profiling in XML Files</title>
   <para> After declaring the entities as shown in <xref
     linkend="ex.daps.ent.decl.profiling" xrefstyle="select:label"/> you can use
    them throughout your documents. For &dapsacr; to process them correctly,
    you only need to <quote>introduce</quote> the entities once within the
     <sgmltag>*info</sgmltag> element of each document as described below. For
    examples showing the result, see <xref linkend="ex.daps.main.pi.db4"
     xrefstyle="select:label"/> (DocBook&nbsp;4) or <xref
     linkend="ex.daps.main.pi.db5" xrefstyle="select:label"/>
    (DocBook&nbsp;5).</para>

   <step>
    <para>Open the XML file that contains the root element for your respective
     document (<sgmltag>set</sgmltag>, <sgmltag>book</sgmltag>, or
     <sgmltag>article</sgmltag>).
     <remark>taroth 2012-12-07: toms, fs: if I have a set, do the product*
    entities need to be in all *info elements (setinfo, bookinfo, articleinfo)?
    - taroth 2015-04-29: according to toms: yes</remark>
    </para>
   </step>
   <step>
    <para>If you use DocBook 4, insert a <sgmltag>setinfo</sgmltag>,
      <sgmltag>bookinfo</sgmltag>, or <sgmltag>articleinfo</sgmltag> element,
     (respectively) within the root element.</para>
    <para>If you use DocBook 5, insert the generic <sgmltag>info</sgmltag>
     element within the root element of your documentation. (DocBook 5 does no
     longer distinguish between <sgmltag>setinfo</sgmltag>,
      <sgmltag>bookinfo</sgmltag>, or <sgmltag>articleinfo</sgmltag>).</para>
   </step>
   <step>
    <para>
     Within <emphasis>all</emphasis> of the <sgmltag>*info</sgmltag> elements in your documentation,
     add the following elements: <sgmltag>productname</sgmltag> and
     <sgmltag>productnumber</sgmltag>.
    </para>
   </step>
   <step>
    <para>
     Within the <sgmltag>productname</sgmltag> elements, add the
     <literal>&amp;productname;</literal> entity.
    </para>
   </step>
    <step>
    <para>Within the <sgmltag>productnumber</sgmltag> elements, add the
      <literal>&amp;productnumber;</literal> entity. </para>
    </step>
  </procedure>

  <para>Now that you have <quote>introduced</quote> the entities for each
   document, use the entities in the text wherever you need them. </para>

  <example id="ex.daps.art.prof.ent.db4">
   <title>XML File with <literal>&amp;productname;</literal> and
    <literal>&amp;productnumber;</literal> Entities (DocBook 4.5)</title>
<screen><?dbsuse-fo font-size="0.65em"?>
&lt;?xml version="1.0" encoding="utf-8"?&gt;

<emphasis role="strong">&lt;?xml-stylesheet
 href="urn:x-daps:xslt:profiling:docbook45-profile.xsl"
 type="text/xml"
 title="Profiling step"?&gt;</emphasis> <co id="co.daps.main.pi.profiling2"/>

<emphasis role="strong">&lt;!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
                         "http://www.docbook.org/xml/4.5/docbookx.dtd"
[&lt;!ENTITY % entities SYSTEM "entity-decl.ent">
%entities;
 ]&gt;</emphasis> <co id="co.daps.main.reference.ent2"/>

&lt;!--the following article is contained in the file art_frog.xml--&gt;

&lt;article lang="en" id="art.frog"&gt;
 &lt;title&gt;Frog Sound Recordings&lt;/title&gt;
 &lt;subtitle&gt;Product Description&lt;/subtitle&gt;
  &lt;articleinfo&gt; <co id="co.daps.articleinfo"/>
   &lt;productname&gt;&amp;productname;&lt;/productname&gt; <co id="co.daps.articleinfo.productname"/>
   &lt;productnumber&gt;&amp;productnumber;&lt;/productnumber&gt; <co id="co.daps.articleinfo.productnumber"/>
 &lt;/articleinfo&gt;
  &lt;abstract&gt;
   &lt;para&gt;
    &amp;productname; &amp;productnumber; is a software for recording, editing, <co id="co.daps.main.product.entities"/>
    and mixing audio data.
   &lt;/para&gt;
  &lt;/abstract&gt;
 [...]
&lt;/article&gt;</screen>
   <calloutlist>
    <callout arearefs="co.daps.main.pi.profiling2">
     <para>
      Processing instruction (PI) in the header of the &main; file. If it is
      missing, any profiling parameters in the &dc; file will be ignored.
     </para>
    </callout>
    <callout arearefs="co.daps.main.reference.ent2">
     <para>
      Reference to the separate entity declaration file (with a parameter
      entity).
     </para>
    </callout>
    <callout arearefs="co.daps.articleinfo">
     <para>
      Element <sgmltag>articleinfo</sgmltag>.
     </para>
    </callout>
    <callout arearefs="co.daps.articleinfo.productname">
     <para>
      Element <sgmltag>productname</sgmltag> and entity
      <literal>&amp;productname;</literal>.
     </para>
    </callout>
    <callout arearefs="co.daps.articleinfo.productnumber">
     <para>
      Element <sgmltag>productnumber</sgmltag> and entity
      <literal>&amp;productnumber;</literal>.
     </para>
    </callout>
    <callout arearefs="co.daps.main.product.entities">
     <para>
      Paragraph containing the entities <literal>&amp;productname;</literal>
      and <literal>&amp;productnumber;</literal>.
     </para>
    </callout>
   </calloutlist>
  </example>

 <example id="ex.daps.art.prof.ent.db5">
   <title>XML File with <literal>&amp;productname;</literal> and
    <literal>&amp;productnumber;</literal> Entities (DocBook 5.0)</title>
<screen><?dbsuse-fo font-size="0.65em"?>
&lt;?xml version="1.0" encoding="utf-8"?&gt;

<emphasis role="strong">&lt;?xml-stylesheet
 href="urn:x-daps:xslt:profiling:docbook50-profile.xsl"
 type="text/xml"
 title="Profiling step"?&gt;</emphasis> <co id="co.daps.main.pi.profiling3"/>

<emphasis role="strong">&lt;!DOCTYPE article
[&lt;!ENTITY % entities SYSTEM "entity-decl.ent">
%entities;
]&gt;</emphasis> <co id="co.daps.main.reference.ent3"/>

&lt;!--the following article is contained in the file art_frog.xml--&gt;

&lt;article xml:lang="en" xml:id="art.frog"
   xmlns="http://docbook.org/ns/docbook"&gt;
 &lt;title&gt;Frog Sound Recordings&lt;/title&gt;
 &lt;subtitle&gt;Product Description&lt;/subtitle&gt;
  &lt;info&gt; <co id="co.daps.info"/>
   &lt;productname&gt;&amp;productname;&lt;/productname&gt; <xref
    linkend="co.daps.articleinfo.productname" xrefstyle="select:nopage"/>
   &lt;productnumber&gt;&amp;productnumber;&lt;/productnumber&gt; <xref
    linkend="co.daps.articleinfo.productnumber" xrefstyle="select:nopage"/>
 &lt;/info&gt;
  &lt;abstract&gt;
   &lt;para&gt;
    &amp;productname; &amp;productnumber; is a software for recording, editing, <xref linkend="co.daps.main.product.entities"
     xrefstyle="select:nopage"/>
    and mixing audio data.
   &lt;/para&gt;
  &lt;/abstract&gt;
 [...]
&lt;/article&gt;</screen>
 <calloutlist>
    <callout arearefs="co.daps.main.pi.profiling3">
     <para>
      Processing instruction (PI) in the header of the &main; file. If it is
      missing, any profiling parameters in the &dc; file will be ignored.
     </para>
    </callout>
    <callout arearefs="co.daps.main.reference.ent3">
     <para>
      Reference to the separate entity declaration file (with a parameter
      entity).
     </para>
    </callout>
    <callout arearefs="co.daps.articleinfo">
     <para>
      Element <sgmltag>info</sgmltag>.
     </para>
    </callout>
    <callout arearefs="co.daps.articleinfo.productname">
     <para>
      Element <sgmltag>productname</sgmltag> and entity
      <literal>&amp;productname;</literal>.
     </para>
    </callout>
    <callout arearefs="co.daps.articleinfo.productnumber">
     <para>
      Element <sgmltag>productnumber</sgmltag> and entity
      <literal>&amp;productnumber;</literal>.
     </para>
    </callout>
    <callout arearefs="co.daps.main.product.entities">
     <para>
      Paragraph containing the entities <literal>&amp;productname;</literal>
      and <literal>&amp;productnumber;</literal>.
     </para>
    </callout>
   </calloutlist>
  </example>
  <para>
   In any output format, the entities
   (<xref linkend="co.daps.articleinfo.productname" xrefstyle="select:label nopage"/>,
   <xref linkend="co.daps.articleinfo.productnumber" xrefstyle="select:label nopage"/>,
   <xref linkend="co.daps.main.product.entities" xrefstyle="select:label nopage"/>)
   will automatically be replaced with different values. The actual values
   depend on the profiling parameters contained in the &dc; file that you use for
   generating the output. For an example, refer to
   <xref linkend="tab.daps.profile.output.four" xrefstyle="select:label"/>.
   It shows output variants that can be generated from the XML code in
   <xref linkend="ex.daps.art.prof.ent.db4" xrefstyle="select:label"/> or <xref
    linkend="ex.daps.art.prof.ent.db5" xrefstyle="select:label"/> plus the
   entity declaration in
   <xref linkend="ex.daps.ent.decl.profiling" xrefstyle="select:label"/> by
   using different &dc; files.
  </para>

  <table id="tab.daps.profile.output.four" rowsep="1">
   <title>Output Variants of <xref linkend="ex.daps.art.prof.ent.db4"
    xrefstyle="select:label"/> / <xref linkend="ex.daps.art.prof.ent.db5"
    xrefstyle="select:label"/> Combined With <xref
     linkend="ex.daps.ent.decl.profiling" xrefstyle="select:label"/></title>
   <tgroup cols="2">
    <colspec colnum="1" colname="1" colwidth="50*"/>
    <colspec colnum="2" colname="2" colwidth="50*"/>
    <thead>
     <row>
      <entry colname="1">
       <para>
        &dc; File
       </para>
      </entry>
      <entry colname="2">
       <para>
        Output
       </para>
      </entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>
       <para>
        <xref linkend="ex.daps.dc.pa.home" xrefstyle="select:title"/>
       </para>
      </entry>
      <entry>
       <para>
        Frog Sound Recordings (Basic)&nbsp;1.0 is a software for recording,
        editing, and mixing audio data.
       </para>
      </entry>
     </row>
     <row>
      <entry>
       <para>
        <xref linkend="ex.daps.dc.pa.prof" xrefstyle="select:title"/>
       </para>
      </entry>
      <entry>
       <para>
        Frog Sound Recordings (Professional)&nbsp;4.2 is a software for
        recording, editing, and mixing audio data.
       </para>
      </entry>
     </row>
     <row>
      <entry>
       <para>
        <xref linkend="ex.daps.dc.pa.prof.oem" xrefstyle="select:title"/>
       </para>
      </entry>
      <entry>
       <para>
        Gecko Sound Recordings (Professional)&nbsp;4.21 is a software for
        recording, editing, and mixing audio data.
       </para>
      </entry>
     </row>
    </tbody>
   </tgroup>
  </table>
 </sect1>
</chapter>