The Introduction Section starts with a description of the application. This description is generally short, but for less well known applications, multiple paragraphs summarizing the application's purpose are appropriate.

  <sect2 role="package">
    <title>Introduction to FAM</title>

    <para>The <application>FAM</application> package 
    contains a File Alteration Monitor which is useful for notifying applications of
    changes to the file system.</para>

After the description, package locations and statistics are presented. The entities defined in the header should be used here.

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

Following the statistics, list any additional downloads needed. These files are usually patches. If no patches and/or special downloads are required, this section should be omitted.

        <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing='compact'>
      <listitem>
        <para>Dnotify patch (Recommended): <ulink url="&patch-root;/fam-&fam-version;-dnotify-1.patch"/></para>
      </listitem>
    </itemizedlist>

Next comes dependencies. This is one of the most important parts of each application. Dependencies should be listed as Required or Optional. In many cases both are needed, and in some cases Recommended dependencies can be added. Required dependencies are those packages that are needed to build the application. Since the book assumes that the packages are being built from an LFS system, no LFS packages should be listed. If a package and a required dependency has, in turn, a required dependency in common, the second level dependency should not be listed. However, if a required dependency and the application share an optional dependency, that optional dependency should be listed.

If a package will take advantage of another package after it is built (run-time dependency), it should not be listed as a dependency, however a note may be appropriate. Use the Required, Recommended, and Optional sections as appropriate for the package.

        <bridgehead renderas="sect3">FAM dependencies</bridgehead>
    <bridgehead renderas="sect4">Required</bridgehead>
    <para><xref linkend="portmap"/></para>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para><xref linkend="some-IDREF"/></para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para><xref linkend="some-IDREF"/></para>

  </sect2>

The Installation Section provides the literal instructions needed to build the application. The instructions should be inside a <screen><userinput> construct and each instruction (except the last) should terminate with a double ampersand (&&) to facilitate cut and paste capability for the user. Note that the <screen><userinput> tags need to be on the same line as the first and last instruction with no leading spaces to render properly. Also note that you should keep lines in this (or any other) <screen><userinput> construct to 71 or fewer characters. Any more than this will not render properly in the PDF format.

You'll notice two entries below about any test suite the package may offer. Use one or the other, or in some instances, different instructions to run the package's test suite.

  <sect2 role="installation">
    <title>Installation of FAM</title>

    <para>Install <application>FAM</application> by running the
    following commands:</para>

<screen><userinput>patch -Np1 -i ../fam-&fam-version;-dnotify-1.patch &amp;&amp;
chmod 755 configure &amp;&amp;
autoreconf -f -i &amp;&amp;
./configure --prefix=/usr --sysconfdir=/etc &amp;&amp;
make</userinput></screen>

    <para>This package does not come with a test suite.</para>
    <para>To test the results, issue: <command>make check</command>.</para>

    <para>Now, as the <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>make install</userinput></screen>

  </sect2>

The Explanation Section elaborates on unusual commands and switches. If the instructions are common commands such as configure && make && make install, this section can be omitted. On the other hand, this section is the perfect place to explain why a command or parameter is necessary. If the Installation Section does not include a particular optional command or parameter, an entry can be made here giving the user information about the alternative or supplemental option. Since many packages have a large number of options, this explanation is normally reserved for optional instructions the editor feels are particularly important. For rendering purposes, parameters actually used in the Installation Section must use <parameter> tags. For optional switches, <option> tags should be used.

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para><parameter>--sysconfdir=/etc</parameter>: This
    setting is used to set the configuration file location properly.</para>

    <para><command>patch -Np1 -i ../fam-&fam-version;-dnotify-1.patch</command>: 
    This patch enables <application>FAM</application> to use 
    the Linux kernel dnotify mechanism to inform the calling process of
    file modifications, rather than polling the file system for
    modifications.</para>

    <para><command>chmod 755 configure</command>:
    <command>configure</command> is set to read-only and
    <command>autoreconf</command> will fail if the 
    permissions aren't changed.</para>

    <para><command>autoreconf -f -i</command>: The autotools need
    rebuilding because the dnotify patch affects <filename>configure.ac</filename>
    and <filename>Makefile.am</filename>.</para>

  </sect2>

This section describes any actions the user needs to take to configure the application. If no configuration is required, then it can be omitted. Note that in some cases lines in <screen> sections can be very long. Sometimes this cannot be avoided.

  <sect2 role="configuration">
    <title>Configuring FAM</title>

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

      <para><filename>/etc/rpc</filename>,
        <filename>/etc/fam.conf</filename>,
        <filename>/etc/inetd.conf</filename>, and
        <filename>/etc/xinetd.d/fam</filename> or
        <filename>/etc/xinetd.conf</filename>
      </para>

      <indexterm zone="fam fam-config">
        <primary sortas="e-etc-rpc">/etc/rpc</primary>
      </indexterm>
      <indexterm zone="fam fam-config">
        <primary sortas="e-etc-fam.conf">/etc/fam.conf</primary>
      </indexterm>
      <indexterm zone="fam fam-config">
        <primary sortas="e-etc-inetd.conf">/etc/inetd.conf</primary>
      </indexterm>
      <indexterm zone="fam fam-config">
        <primary sortas="e-etc-xinetd.conf">/etc/xinetd.conf</primary>
      </indexterm>
      <indexterm zone="fam fam-config">
        <primary sortas="e-etc-xinetd.d-sgi_fam">/etc/xinetd.d/sgi_fam</primary>
      </indexterm>
    </sect3>

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

      <para>Configuring the file alteration monitor.</para>

      <para>If you use <application>inetd</application>, add the <application>FAM</application> 
      entry to <filename>/etc/inetd.conf</filename> with the following command:</para>

<screen role="root"><userinput>echo "sgi_fam/1-2 stream  rpc/tcp wait root /usr/sbin famd fam" \
    &gt;&gt; /etc/inetd.conf</userinput></screen>

      <para>If you use <application>xinetd</application>, add an entry to
      <filename>/etc/xinetd.conf</filename> with the following command (be
      sure the "nogroup" group exists):</para>

<screen role="root"><userinput>cat &gt;&gt; /etc/xinetd.conf &lt;&lt; "EOF"
<literal># description: FAM - file alteration monitor
    service sgi_fam
    {
        type            = RPC UNLISTED
        socket_type     = stream
        user            = root
        group           = nogroup
        server          = /usr/sbin/famd
        wait            = yes
        protocol        = tcp
        rpc_version     = 2
        rpc_number      = 391002
    }</literal>
EOF</userinput></screen>
    </sect3>

    <sect3 id="fam-boot">
      <title>Boot Scripts</title>

      <para>If you do not have an <command>inetd</command> daemon installed and have 
      no wish to install one, you can also start <command>famd</command> during 
      system startup by installing the <filename>/etc/rc.d/init.d/fam</filename>
      init script included in the
      <xref linkend="bootscripts"/> package.</para>

<screen role="root"><userinput>make install-fam</userinput></screen>

      <indexterm zone="fam fam-boot">
        <primary sortas="f-fam">fam</primary>
      </indexterm>

    </sect3>
  </sect2>

The final section describes the contents of the application.

  <sect2>
    <title>Contents</title>
    <segmentedlist>
      <segtitle>Installed Program</segtitle>
      <segtitle>Installed Library</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>famd</seg>
        <seg>libfam.[so,a]</seg>
        <seg>None</seg>
      </seglistitem>
    </segmentedlist>

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

    <varlistentry id="famd">
      <term><command>famd</command></term>
      <listitem>
        <para>is the file alteration monitor daemon.</para>
        <indexterm zone="fam famd">
          <primary sortas="b-famd">famd</primary>
        </indexterm>
      </listitem>
    </varlistentry>

    <varlistentry id="libfam">
      <term><filename class='libraryfile'>libfam.[so,a]</filename></term>
      <listitem>
        <para>contains functions that support the file allocation monitor.</para>
        <indexterm zone="fam libfam">
          <primary sortas="c-libfam">libfam.[so,a]</primary>
        </indexterm>
        </listitem>
      </varlistentry>
    </variablelist>

  </sect2>
</sect1>

As you can see above, there are several places where indexing tags are placed into the page. The tagging has the following format:

<indexterm zone="id-start id-end">
  <primary sortas="X-sortterm">indexed-item</primary>
</indexterm>

The zone attribute has two values. The first will always be to the IDREF in the first <sect1> of the page. The first a- entry for packages will only have one IDREF. The other entries will have two IDREFS. The first will still be the page IDREF and the second will be an IDREF for the tag defining the start of the discussion of the item. The index will have two links for these references: one to the package and one to the specific section discussing the item.

The 'X' value in the sortas attribute has a specific meaning for the BLFS XSL stylesheets. It refers to the section of the index where the entry will be placed. The values are:

The value after the dash in the sortas attribute is how the index item will be sorted within its section. It is not case sensitive.