path: root/en_US/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><xref linkend="ex-module-structure"/> shows a directory tree
      of an example module, excluding any <filename
	class="directory">CVS</filename> folders:</para>
    <example id="ex-module-structure">
      <title>Example Module Structure</title>
      <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>
    </example>
    <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 in <xref linkend="ex-makefile"/>.</para>
    </formalpara>
    <formalpara>
      <title><filename>rpm-info.xml</filename> (required)</title>
      <para>The <filename>rpm-info.xml</filename> file contains document
	specific metadata</para>
    </formalpara>
  </section>
  <section id="ch-getting-files-build-system">
    <title>The Document Build System</title>
    <para>
      The build system can render the document into another format such
      as <abbrev>HTML</abbrev> or <abbrev>PDF</abbrev>, using
      <command>make(1)</command> and shell scripts.  Authors need
      <emphasis>no</emphasis> prior experience with either shell scripts
      or a <command>make(1)</command>.
    </para>
    <section id="sn-makefile">
      <title>The Document <filename>Makefile</filename></title>
      <para>
	Each individual document has its own
	<filename>Makefile</filename>, which only needs to be a few
	lines long. The document <filename>Makefile</filename> content
	is designed for cut and paste operations.
      </para>
      <para>
	<xref linkend="ex-makefile"/> below shows the whole
	<filename>Makefile</filename> for a simple document with two
	files and two translations.
      </para>
      <example id="ex-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
	such as the <command>XMLFILES_template</command> stanza.  An
	explanation for this template appears a few paragraphs
	below.</para>
      <formalpara>
	<title><systemitem class="macro">DOCBASE</systemitem></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><systemitem class="macro">PRI_LANG</systemitem></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><systemitem class="macro">OTHERS</systemitem></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><systemitem class="macro">DOC_ENTITIES</systemitem></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><systemitem
	    class="macro">XMLFILES_template</systemitem></title>
	<para>This template allows the build tools to work with the
	  document in multiple languages once it is translated.  The
	  <systemitem class="macro">${1}</systemitem> 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 <systemitem
	    class="macro">${1}/</systemitem>, 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>
      <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>
    </section>
    <section>
      <title>The Document <filename>rpm-info.xml</filename></title>
      <para>Each document module's primary language directory contains a
	file called <filename>rpm-info.xml</filename>.  This file
	contains document-specific metadata used to generate revision
	history, copyright, and contributor information.  It follows a
	DTD specification included with the rest of the build system
	tools.</para>
      <para><xref linkend="ex-rpminfo"/> illustrates the content of
	this file:</para>
      <example id="ex-rpminfo">
	<title>Example <filename>rpm-info.xml</filename> File</title>
	<programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE rpm-info SYSTEM "../../docs-common/packaging/rpm-info.dtd">

<rpm-info>
  <colophon>
    <worker surname="Smith" firstname="John" othername="Q." 
      id="JohnSmith" email="jsmith@example.com" 
      wholename="John Q. Smith" initials="JS"/>
  </colophon>
  <author worker="JohnSmith"/>
  <license>
    <rights>OPL</rights>
    <version>1.0</version>
  </license>
  <copyright>
    <year>2006</year>
    <holder>John Q. Smith</holder>
  </copyright>
  <title>My Tutorial</title>
  <desc>A tutorial about something important</desc>
  <changelog order="newest-first">
    <revision date="2006-06-01" number="0.1" role="doc">
      <author worker="JohnSmith"/>
      <details>First draft</details>
    </revision>
  </changelog>
</rpm-info>]]></programlisting>
      </example>
      <para>If you are not familiar with XML editing, copy and paste
	this file from an existing module and then edit the values for
	the various elements as appropriate.  Consult &FDP; members and
	help channels for more assistance if needed.</para>
    </section>
  </section>
  <section id="ch-getting-files-build-system-targets">
    <title>Build System Actions</title>
    <para>
      To render the <abbrev>XML</abbrev> document into another format,
      use one of the following <command>make</command> targets:
    </para>
    <formalpara>
      <title><systemitem class="macro">html</systemitem></title>
      <para>This target builds the "chunked" <abbrev>HTML</abbrev>
	document for each defined translation.  Output is placed in a
	separate directory named <filename class="directory"><systemitem
	    class="macro">${DOCBASE}</systemitem>-<systemitem
	    class="macro">${LANG}</systemitem>/</filename>. Each
	document section is a separate file within that
	directory.</para>
    </formalpara>
    <formalpara>
      <title><systemitem
	  class="macro">html-nochunks</systemitem></title>
      <para>This target builds the "non-chunked" <abbrev>HTML</abbrev>
	document for each defined translation. Output is placed in a
	single file: <filename><systemitem
	    class="macro">${DOCBASE}</systemitem>-<systemitem
	    class="macro">${LANG}</systemitem>.html</filename>; no other
	files are created.</para>
    </formalpara>
    <formalpara>
      <title><systemitem class="macro">pdf</systemitem></title>
      <para>This target builds only the <abbrev>PDF</abbrev> document
	for all document languages. <abbrev>PDF</abbrev> production is
	currently erratic and may not work for your document.</para>
    </formalpara>
    <formalpara>
      <title><systemitem class="macro">tarball</systemitem></title>
      <para>This target builds only the <command>tar(1)</command>
	archive for all document languages.</para>
    </formalpara>
    <formalpara>
      <title><systemitem class="macro">all</systemitem></title>
      <para>This target builds all targets listed above.</para>
    </formalpara>
    <formalpara>
      <title><systemitem class="macro">clean</systemitem></title>
      <para>This target deletes any temporary, or generated files, but
	does <emphasis>not</emphasis> erase any <abbrev>HTML</abbrev>,
	<abbrev>PDF</abbrev>, or archive files.</para>
    </formalpara>
    <formalpara>
      <title><systemitem class="macro">distclean</systemitem></title>
      <para>This target erases all <abbrev>HTML</abbrev>,
	<abbrev>PDF</abbrev>, and archive files.  This target
	automatically invokes the <filename>clean</filename> target as
	well.</para>
    </formalpara>
    <section>
      <title>Adding or Changing Targets</title>
      <para>
        To add a new target and rules, place them at the bottom of the
	document <filename>Makefile</filename>, below the
	<literal>include</literal> line.  Follow your target definitions
	with a double colon, not a single colon.  The double colon
	allows you to specify additional rules for existing targets, or
	to write rules for a new target.
      </para>
      <para>
	For more information on using <command>make(1)</command>,
	consult the online documentation with the command <command>info
	  make</command> in a terminal.
      </para>
    </section>
    <section id="ch-getting-files-build-system-images">
      <title>Using Document Image Files</title>
      <para>
        Tutorial documents often make use of images such as <filename
	  class="extension">.PNG</filename> files.  Store image files in
	a <filename class="directory">figs/</filename> folder in the
	main module directory, as shown in <xref
	  linkend="ex-module-structure"/>.
      </para>
      <para>
	Depending on the output media, sometimes images may be scaled,
	streteched, or squashed. To minimize any distortions, we
	recommend that you use only <filename
	  class="extension">.PNG</filename> images.  Avoid <filename
	  class="extension">.JPG</filename> files.  The
	<command>convert(1)</command> program, from the <package
	  role="rpm">ImageMagick</package> <abbrev>RPM</abbrev> package,
	provides a convenient way to reformat <filename
	  class="extension">.JPG</filename> images into <filename
	class="extension">.PNG</filename> format.  For more information
	on formatting images such as screenshots, refer to <xref
	linkend="s1-screenshots"/>.
      </para>
      <para>
        Image files may be organized into subdirectories under
	<filename>figs/</filename> if necessary. The document building
	system recreates the image subdirectory structure in the output
	documents.
      </para>
      <para>
	Images often contain labels or other text which may need to be
	localized.  A screenshot of a program, for example, may require
	a version for each translated language.  Name language-dependent
	image files such as program screenshots by adding the language
	code to the filename, such as
	<filename>menu-en_US.png</filename>.  Language-independent
	images, such as <filename>icon.png</filename>, do not need
	language codes.
      </para>
      <para>
        Sometimes, a document may require images that do not follow the
	naming convention.  To use these images with the document
	building system, create an ordinary text file containing the
	image filenames.  This file must be named
	<filename>figs/Manifest-</filename><systemitem
	  class="macro">${LANG}</systemitem> so the build system finds
	it when searching for image filenames.
      </para>
      <para>
	<xref linkend="ch-getting-files-build-system-manifest"/>
	demonstrates one way to create this
	<filename>Manifest</filename> file.
      </para>
      <example id="ch-getting-files-build-system-manifest">
	<title>Building A Manifest</title>
	<programlisting><![CDATA[rm -f figs/Manifest-en
find figs -print >/tmp/manifest
mv /tmp/manifest figs/Manifest-en]]></programlisting>
      </example>
    </section>
    <section>
      <title>Adding a New DocBook XML File</title>
      <para>To add a new DocBook XML file to an existing document,
	follow these steps:</para>
      <procedure>
	<step>
	  <para>Place the new DocBook XML file in the primary language
	    directory.</para>
	</step>
	<step>
	  <para>Edit the <filename>Makefile</filename> and add the
	    filename to the <varname>XMLFILES-${1}</varname> listing.
	    Append a <keycap>\</keycap> to the last existing line, and
	    on the next line add an entry for the new file.  Remember to
	    add the <literal>${1}/</literal> prefix as a substitute for
	    the language directory name.</para>
	</step>
      </procedure>
    </section>
    <section>
      <title>Adding a Translation</title>
      <para>Translations are stored as PO (portable object) files, which
	the toolchain transforms into translated documents.  Each PO
	file is based on the POT (PO template) for the document and
	translated by the &FED; Translation Project.  To add a
	translation, follow these steps:</para>
      <procedure>
	<step>
	  <para>If the <filename class="directory">po/</filename>
	    directory does not exist, create it and add it to
	    CVS:</para>
	  <screen><![CDATA[mkdir po && cvs add po/]]></screen>
	</step>
	<step>
	  <para>If it does not exist, create the POT file:</para>
	  <screen><![CDATA[make pot]]></screen>
	</step>
	<step>
	  <para>Add the new translation language to the
	    <varname>OTHERS</varname> listing in the
	    <filename>Makefile</filename>.</para>
	</step>
	<step>
	  <para>Although translators often copy the POT manually to
	    create the new PO file, the following command also
	    works:</para>
	  <screen>make po/<replaceable>lang</replaceable>.po</screen>
	</step>
      </procedure>
    </section>
  </section>
</chapter>

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