diff options
Diffstat (limited to 'en_US/docs-module-struct.xml')
| -rw-r--r-- | en_US/docs-module-struct.xml | 348 |
1 files changed, 348 insertions, 0 deletions
diff --git a/en_US/docs-module-struct.xml b/en_US/docs-module-struct.xml new file mode 100644 index 0000000..a751f2b --- /dev/null +++ b/en_US/docs-module-struct.xml @@ -0,0 +1,348 @@ +<!-- $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: +--> |