diff options
-rw-r--r-- | en_US/acknowledgments.xml | 4 | ||||
-rw-r--r-- | en_US/docs-getting-files.xml | 333 | ||||
-rw-r--r-- | en_US/docs-module-struct.xml | 348 | ||||
-rw-r--r-- | en_US/documentation-guide.xml | 11 |
4 files changed, 372 insertions, 324 deletions
diff --git a/en_US/acknowledgments.xml b/en_US/acknowledgments.xml index 9a71775..47a3f11 100644 --- a/en_US/acknowledgments.xml +++ b/en_US/acknowledgments.xml @@ -25,8 +25,8 @@ <para> Patches from Gavin Henry (ghenry at suretecsystems.com) have been applied to add the trailing slashes to the <command>figure</command> tag example - in <filename>docs-xml-tags.xml</filename> and to add <xref - linkend="ch-emacs-nxml"></xref>. + in <filename>docs-xml-tags.xml</filename><!-- and to add <xref + linkend="ch-emacs-nxml"></xref>-->. </para> <para> diff --git a/en_US/docs-getting-files.xml b/en_US/docs-getting-files.xml index 6e762ea..c86a6d4 100644 --- a/en_US/docs-getting-files.xml +++ b/en_US/docs-getting-files.xml @@ -1,5 +1,5 @@ <!-- $Id: --> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" +<!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 *************** --> @@ -13,7 +13,7 @@ <para> To work on official &FED; documentation you need to install the required - tools. The directions below will help you configure your setup. + tools. Follow the directions below to configure your system. </para> <section id="ch-getting-files-system-packages"> @@ -44,7 +44,7 @@ <para> The &FDP;'s custom scripts and stylesheets are stored in CVS on the - <systemitem class="fqdomainname">cvs.fedora.redhat.com</systemitem> CVS + <systemitem class="fqdomainname">cvs.fedoraproject.org</systemitem> CVS server. Check them out along with the DocBook XML files for the existing docs. </para> @@ -52,7 +52,7 @@ <screen> <userinput>mkdir <replaceable>my-fedora-docs-sandbox</replaceable> cd <replaceable>my-fedora-docs-sandbox</replaceable> -export CVSROOT=:pserver:anonymous@cvs.fedora.redhat.com:/cvs/docs +export CVSROOT=:ext:<replaceable>username</replaceable>@cvs.fedora.redhat.com:/cvs/docs cvs login cvs co docs-common</userinput> </screen> @@ -64,8 +64,9 @@ cvs co docs-common</userinput> <note> <title>Common Files</title> <para> - You need to perform these steps only once. These files are common to - all the official documentation. + You need to perform this "checkout" step only once, although you may + need to update the files later. These files are common to all the + official documentation. </para> </note> @@ -75,18 +76,14 @@ cvs co docs-common</userinput> </section> - <!-- Starting here, the information is EXTREMELY useful but goes way outside - the scope of the chapter. This stuff needs to be relocated in the redesigned - DocGuide. [PWF, 2006-01-03] --> - <section id="ch-getting-files-filenames"> <title>Filename Conventions</title> <para> &FDP; provides the tools, scripts, and stylesheets to transform your - <abbrev>XML</abbrev> documents into either <abbrev>HTML</abbrev> or - <abbrev>PDF</abbrev> output formats. In addition, these tools can build - your document into an <abbrev>RPM</abbrev> package. To take advantage of - these services, you must follow conventions for naming your files. + <abbrev>XML</abbrev> documents into other output formats such as + <abbrev>HTML</abbrev>. In addition, these tools can build your document + into a <abbrev>RPM</abbrev> package. To take advantage of these + services, you must follow conventions for naming your files. </para> <section id="ch-getting-files-filenames-doc"> <title>Document Filenames</title> @@ -103,320 +100,16 @@ cvs co docs-common</userinput> <para> Do not use the word <wordasword>&FED;</wordasword> in your module name. Since all documents in the repository are &FED; documentation, - using it creates unnecessary confusion. + using this term creates unnecessary confusion. </para> </important> </section> - <section id="ch-getting-files-i18n"> - <title>Anticipating I18N Translation</title> - <para> - The &FDP; includes an active translation team. Project documents are - often translated into several languages. By convention, the translated - files share the directory with the original files. Therefore, filenames - must be unique. - </para> - <para> - To construct a filename, append a dash followed by the - <abbrev>ISO</abbrev> language symbol before any file extension. For - example, a file whose language content is <abbrev>U.S.</abbrev> English - might be named <filename>mydoc-en.xml</filename>, its Chinese - translation named <filename>mydoc-zh_CN.xml</filename>, and so on. - </para> - <para> - To assist this effort, the document build system assumes that each file - is tagged with its <abbrev>I18N</abbrev> locale. Our filename - convention is shown in <xref linkend="ch-getting-files-i18n-table"/>. - </para> - <table id="ch-getting-files-i18n-table"> - <title>&FDP; Filename Conventions</title> - <tgroup cols="2"> - <colspec align="right" colnum="1" colwidth="*1"/> - <colspec colnum="2" colwidth="*5"/> - <thead> - <row> - <entry> - <phrase>Compoment</phrase> - </entry> - <entry> - <phrase>Description</phrase> - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <phrase><replaceable>anything_but_dash</replaceable></phrase> - </entry> - <entry> - <para> - The initial portion of a filename can be anything, as long as - <emphasis>no dash</emphasis> is used. - </para> - </entry> - </row> - <row> - <entry> - <phrase><filename>-</filename></phrase> - </entry> - <entry> - <para> - A dash (<filename>-</filename>) is to be used only to - introduce the <systemitem class="macro">${LANG}</systemitem> - filename component. - </para> - </entry> - </row> - <row> - <entry> - <phrase><systemitem class="macro">${LANG}</systemitem></phrase> - </entry> - <entry> - <para> - The <systemitem class="macro">${LANG}</systemitem> component - identifies the <wordasword>locale</wordasword> for the file - content. - </para> - <para> - In addition to helping classify files according to their - language content, we also use the <systemitem - class="macro">${LANG}</systemitem> value as an - <abbrev>UTF-8</abbrev> locale when rendering the document. - For example, the document - <filename>mydoc-it.xml</filename>will be rendered using - <systemitem class="resource">it.UTF-8</systemitem> as the - language environment. - </para> - <para> - For more information on <abbrev>I18N</abbrev> localization, - visit the <ulink url="http://www.openi18n.org"/> web site. - </para> - </entry> - </row> - </tbody> - </tgroup> - </table> - <warning> - <title>Document Filenames Are Special</title> - <para> - The main file in your document <emphasis>must</emphasis> follow the - file naming convention or the document building system cannot find it. - </para> - </warning> - </section> - </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. - </para> - <para> - 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'n paste. - </para> - <para> - As an example, <xref linkend="ch-getting-files-build-system-makefile"/> shows the whole <filename>Makefile</filename> for a simple document having only one file and one language. - </para> - <example id="ch-getting-files-build-system-makefile"> - <title>Sample Document Makefile</title> -<programlisting width="60"> -DOCBASE = mydoc -LANGUAGES = en -XMLEXTRAFILES-en= -include ../docs-common/Makefile.common -</programlisting> -</example> - <para> - Our main <abbrev>XML</abbrev> file is <filename>mydoc-en.xml</filename>; no translation has been done yet. - </para> - <para> - The <systemitem class="macro">LANGUAGES</systemitem> definition lists the English locale <literal>en</literal>; when other translations become available, their locale will just be appended to this definition. - </para> - <para> - Our document has only the main file <filename>mydoc-en.xml</filename>, but other documents may be split over several files. - The <systemitem class="macro">XMLEXTRAFILES-en</systemitem> definition catalogs these additional files so that the document building system can watch them for changes and rebuild the document when necesssary. - This definition is just a simple list of files. - </para> - <para> - The final line, beginning with <literal>include</literal>, references the main <filename>Makefile</filename> for the build system. - The <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 -sgml-parent-document: ("documentation-guide-en.xml" "book" "chapter") -fill-column: 80 +fill-column: 72 End: --> 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: +--> diff --git a/en_US/documentation-guide.xml b/en_US/documentation-guide.xml index 1d9ae2f..63c719b 100644 --- a/en_US/documentation-guide.xml +++ b/en_US/documentation-guide.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8"?> -<!-- $Id: documentation-guide.xml,v 1.2 2006/11/29 00:29:48 pfrields Exp $ --> +<!-- $Id: documentation-guide.xml,v 1.3 2006/11/29 22:18:53 pfrields Exp $ --> <!-- breaks the build ... <?xml version="1.0" encoding="utf-8"?> --> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [ @@ -25,6 +25,11 @@ <xi:include href="docs-getting-files.xml" xpointer="element(ch-getting-files)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <!-- HOWMODULESWORK --> + <xi:include href="docs-module-struct.xml" + xpointer="element(ch-how-modules-work)" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + <!-- GUIDELINES --> <xi:include href="docs-rh-guidelines.xml" xpointer="element(ch-rh-guidelines)" xmlns:xi="http://www.w3.org/2001/XInclude" /> @@ -34,9 +39,11 @@ xmlns:xi="http://www.w3.org/2001/XInclude" /> <!-- EMACS-NXML --> - <!-- This chapter needs editing, but we can't exclude it now. --> + <!-- This chapter needs editing, so we're excluding it now. --> + <!-- <xi:include href="docs-emacs-nxml.xml" xpointer="element(ch-emacs-nxml)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + --> <!-- VIM --> <xi:include href="docs-vim.xml" xpointer="element(ch-vim)" |