path: root/en_US/docs-module-struct.xml

<!-- $Id: -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [

<!-- *************** Bring in Fedora entities *************** -->
<!ENTITY % FEDORA-ENTITIES-EN SYSTEM "fdp-entities.ent">
%FEDORA-ENTITIES-EN;

]>

<chapter id="ch-how-modules-work">
  <title>How Modules Work</title>
  <para>Documentation modules have a specific structure that enables the
    preconfigured tools to work correctly.  Follow this structure exactly or you
    may have problems building your module.  The &FDP; build tools locate
    resources in the module and use them to build new output such as HTML or RPM
    packages.</para>
  <section id="sn-module-struct">
    <title>Structure of a Module</title>
    <para>The following listing shows a directory tree of an example module,
      excluding any <filename class="directory">CVS</filename> folders:</para>

    <screen><computeroutput><![CDATA[example-doc/
    |-- en_US/
            |-- example-doc.xml
            |-- para.xml
            |-- doc-entities.xml
            |-- rpm-info.xml
    |-- figs/
            |-- fedora-logo-sprite.eps
            |-- fedora-logo-sprite.png
    |-- po/
            |-- de.po
            |-- example-doc.pot
            |-- pt.po
    |-- Makefile]]></computeroutput></screen>
    
    <formalpara>
      <title>Primary language directory (required)</title>
      <para>This is the only directory absolutely required. It is named for the
	original language of the document, such as <filename
	  class="directory">en_US</filename> (US English).  The primary language
	does not have to be US English; all languages are supported.  This
	directory contains all the XML source for the actual document, as well
	as XML source for document-specific
	<firstterm>entities</firstterm><footnote>
	  <para>Think of an XML entity as a predefined snippet of information.
	    It can represent a chunk of XML source, or simply a word or
	    character. If the information changes, it need be replaced only
	    once, in the definition, to fix all usage.</para>
	</footnote>.
      </para>
    </formalpara>
    <formalpara>
      <title>Graphics directory (optional)</title>
      <para>The <filename class="directory">figs/</filename> directory is an
	optional directory where graphics for the document should be stored. If
	graphics are screenshots that are particular to a language, the
	<filename class="directory">figs/</filename> directory can and should be
	stored in a language directory.</para>
    </formalpara>
    <formalpara>
      <title>Translation (PO) directory (optional)</title> 
      <para>The <filename class="directory">po/</filename> directory contains
	specially formatted files created and used by translators. The &FDP;
	build tools use these files to create translated versions of documents.
	The translated documents are not stored in CVS; they are created as
	needed from these PO files.</para>
    </formalpara>
    <formalpara>
      <title>Makefile (required)</title>
      <para>The <filename>Makefile</filename> controls the build process. Its
	content is discussed below. <!-- include xref here --></para>
    </formalpara>
  </section>
  <section id="ch-getting-files-build-system">
    <title>The Document Build System</title>
    <para>
      Common tasks such as rendering the document into either
      <abbrev>HTML</abbrev> or <abbrev>PDF</abbrev> can be performed
      easily using the document building system. The building system
      heavily leverages the <application>make(1)</application> tool and
      shell scripts to automate these activities, but authors need
      <emphasis>no</emphasis> prior experience with either shell scripts
      or a <filename>Makefile</filename>. While individual documents do
      have their own <filename>Makefile</filename>, it is only a few
      lines long and very simple. The document
      <filename>Makefile</filename> content is designed for cut and
      paste operations.
    </para>
    <para>
      <xref
	linkend="ch-getting-files-build-system-makefile"/> below shows the
      whole <filename>Makefile</filename> for a simple document having
      only two files and one language.
    </para>
    <example id="ch-getting-files-build-system-makefile">
      <title>Sample Document Makefile</title>
      <programlisting>
<![CDATA[
DOCBASE         = example-doc
PRI_LANG      	= en_US
OTHERS          = de pt
DOC_ENTITIES    = doc-entities

define XMLFILES_template
XMLFILES-${1}   = ${1}/example-doc.xml \
                  ${1}/para.xml
endef

include ../docs-common/Makefile.common
]]>
      </programlisting>
    </example>
    <para>
      Do not be concerned with some of the more complicated syntax (in
      particular, the <command>XMLFILES_template</command> stanza).  An
      explanation for this template appears a few paragraphs
      below.</para>
    <formalpara>
      <title><varname>DOCBASE</varname></title>
      <para>This variable contains the name for the main (parent) XML document.
	Follow convention by naming your document after the module name.</para>
    </formalpara>
    <formalpara>
      <title><varname>PRI_LANG</varname></title>
      <para>This variable contains the ISO code for the original version of the
	document, such as <systemitem>en_US</systemitem>.</para>
    </formalpara>
    <formalpara>
      <title><varname>OTHERS</varname></title>
      <para>This variable contains a listing of ISO codes for any other versions
	into which the document has been translated.  The module must contain a
	<filename class="directory">po/</filename> directory and a PO file for
	any indicated additional languages.</para>
    </formalpara>
    <formalpara>
      <title><varname>DOC_ENTITIES</varname></title>
      <para>This variable contains a listing of any files containing entity
	definitions.  The &FDP; uses a special XML format to record
	document-specific entities, so they can be translated and built on the
	fly like any other XML document.  An example is shown later in this
	guide. <!-- need xref here --></para>
    </formalpara>
    <formalpara>
      <title><varname>XMLFILES_template</varname></title>
      <para>This template allows the build tools to work with the
	document in multiple languages once it is translated.  The
	<varname>${1}</varname> marking is a variable used to substitute
	the appropriate language.  This template is not terribly
	complicated.  For a new module, duplicate this section exactly
	except for the actual filenames.  Prepend the text
	<varname>${1}/</varname>, in place of the language code
	directory name, to each filename in your document.
      </para>
    </formalpara>
    <important>
      <title>Files Exempt From Listing</title>
      <para>Do not include the document-specific entities XML file or the
	<filename>rpm-info.xml</filename> file, which will be discussed later in
	this guide.<!-- include xref --></para>
    </important>
    <!-- TEMP MARKER - PWF finished here Nov 28 2006 -->
    <para>
      The final line, beginning with <literal>include</literal>, references the
      main <filename>Makefile</filename> for the build system. This
      <filename>Makefile.common</filename> file contains all the
      <application>make(1)</application> targets and rules to actually build the
      document and the various archives.
    </para>
    <para>
      Add new document translations by:
    </para>
    <orderedlist>
      <listitem>
        <para>
          Add the translated document files to the document directory.
          Be sure to use the proper <systemitem class="macro">${LANG}</systemitem> filename component to keep the filenames similar, but unique.
        </para>
      </listitem>
      <listitem>
        <para>
          Edit the <filename>Makefile</filename> to append the new <systemitem class="macro">${LANG}</systemitem> to the <systemitem class="macro">LANGUAGES</systemitem> definition.
        </para>
      </listitem>
      <listitem>
        <para>
          Create a new <systemitem class="macro">XMLEXTRAFILES-${LANG}</systemitem> definition that references any document files other than the base file.
        </para>
      </listitem>
    </orderedlist>
    <section id="ch-getting-files-build-system-targets">
      <title>Build System Actions</title>
      <para>
        To render the <abbrev>XML</abbrev> document into <abbrev>HTML</abbrev> or <abbrev>PDF</abbrev> the command: <userinput>make html</userinput>,
        <userinput>make html-nochunk</userinput>, or <userinput>make pdf</userinput> may be used.
      </para>
      <para>
        <xref linkend="ch-getting-files-build-system-targets-table"/> lists the defined build system targets.
      </para>
      <table id="ch-getting-files-build-system-targets-table">
        <title>Document Building Targets</title>
        <tgroup cols="2">
          <colspec align="right" colnum="1" colwidth="*1"/>
          <colspec colnum="2" colwidth="*5"/>
          <thead>
            <row>
              <entry><phrase>Target</phrase></entry>
              <entry><phrase>Description</phrase></entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry><phrase><filename>all</filename></phrase></entry>
              <entry>
                <para>
                  Builds the <abbrev>HTML</abbrev>, and the <abbrev>PDF</abbrev> forms of the document in all its defined translations.
                </para>
                <para>
                  Also builds the archives, such as <application>tar(1)</application> and <application>rpm(8)</application>.
                </para>
              </entry>
            </row>
            <row>
              <entry><phrase><filename>tarball</filename></phrase></entry>
              <entry>
                <para>
                  Builds only the <application>tar(1)</application> archive for all document languages.
                </para>
              </entry>
            </row>
            <row>
              <entry><phrase><filename>pdf</filename></phrase></entry>
              <entry>
                <para>
                  Builds only the <abbrev>PDF</abbrev> document for all document languages.
                </para>
                <para>
                  Currently, <abbrev>PDF</abbrev> production is problematic and probably will not work for your document.
                </para>
              </entry>
            </row>
            <row>
              <entry><phrase><filename>html</filename></phrase></entry>
              <entry>
                <para>
                  Builds only the <abbrev>HTML</abbrev> document for each defined translation.
                  Output is placed in a separate directory:
                  <systemitem class="macro">${DOCBASE}</systemitem><filename>-</filename><systemitem class="macro">${LANG}</systemitem><filename>/</filename>; each document section is given its own file within that directory.
                </para>
              </entry>
            </row>
            <row>
              <entry><phrase><filename>html-nochunks</filename></phrase></entry>
              <entry>
                <para>
                  Builds only the <abbrev>HTML</abbrev> document for each defined translation.
                  Output is placed in a single file:
                  <systemitem class="macro">${DOCBASE}</systemitem><filename>-</filename><systemitem class="macro">${LANG}</systemitem><filename>.html</filename>; no other files are created.
                </para>
              </entry>
            </row>
            <row>
              <entry><phrase><filename>clean</filename></phrase></entry>
              <entry>
                <para>
                  Deletes any temporary, or generated files.
                  Does <emphasis>not</emphasis> erase any <abbrev>HTML</abbrev>, <abbrev>PDF</abbrev>, or archive files.
                </para>
              </entry>
            </row>
            <row>
              <entry><phrase><filename>distclean</filename></phrase></entry>
              <entry>
                <para>
                  Erases all <abbrev>HTML</abbrev>, <abbrev>PDF</abbrev>, and archive files.
                  Automatically invokes the <filename>clean</filename> target as well.
                </para>
              </entry>
            </row>
          </tbody>
        </tgroup>
      </table>
      <para>
        You can add your own special targets and rules by placing them at the bottom of the document <filename>Makefile</filename>, below the <literal>include</literal> line.
      </para>
      <para>
        Be sure to follow your target definitions with a double colon, not just one.
        This will allow you to supply extra steps for the defined targets.
      </para>
    </section>
    <section id="ch-getting-files-build-system-images">
      <title>Using Document Image Files</title>
      <para>
        Image files, such as <filename>.PNG</filename>, are often used in documents.
        While your image files may be placed anywhere you like, we recommend that you store your image files in a <filename>figs/</filename> subdirectory within your document directory.
        In other words, place your image <filename>picture.png</filename> in the <filename>mydoc/figs/picture.png</filename> file.
      </para>
      <note>
      <title>Use PNG Images, Not JPG</title>
        <para>
            Depending on the output media, sometimes images may be scaled,
            streteched, or squashed.
            To minimize any distortions, we recommend that you use only
            <wordasword>PDF</wordasword> images and avoid <wordasword>JPG</wordasword> files.
        </para>
        <para>
          You may find the <systemitem class="filesystem">convert(1)</systemitem> program, from the <application>ImageMagick</application> <abbrev>RPM</abbrev> package, provides a convenient way to reformat any <wordasword>JPG</wordasword> images you already have.
        </para>
      </note>
      <para>
        You may organize your image files into as many subdirectories under <filename>figs/</filename> as you choose.
        The document building system will recreate your image subdirectory structure in the output documents.
      </para>
      <para>
        In addition, we recommend that you follow our convention on naming the image.
        For example, an image often contains a caption or other text.
        This text should be translated along with the document content, so keeping <filename>words-en.png</filename> separate from <filename>words-ru.png</filename> is a good practice.
        An image file with no text can be named just <filename>picture.png</filename>, for example.
      </para>
      <para>
        Sometimes, a document may require images that do not follow the naming convention.
        You may still use these images with the document building system, but it requires that you create an ordinary text file containing the image filenames you want to use.
        This file must be named <filename>figs/Manifest-</filename><systemitem class="macro">${LANG}</systemitem> so that the build system can find it as the search for image filenames begins.
      </para>
      <para>
        An easy way to create the <filename>figs/Manifest-</filename><systemitem class="macro">${LANG}</systemitem> file is shown in <xref linkend="ch-getting-files-build-system-manifest"/>.
      </para>
      <example id="ch-getting-files-build-system-manifest">
  <title>Building A Manifest</title>
<programlisting>
rm -f figs/Manifest-en
find figs -print >/tmp/manifest
mv /tmp/manifest figs/Manifest-en
vi figs/Manifest-en
</programlisting>
</example>

    </section>
  </section>
</chapter>

<!--
Local variables:
mode: xml
fill-column: 72
End:
-->