Author: pfrields
Update of /cvs/docs/documentation-guide/en_US In directory cvs-int.fedora.redhat.com:/tmp/cvs-serv17851
Modified Files: module-struct.xml Log Message: Yay, segmentedlists for everyone!
Index: module-struct.xml =================================================================== RCS file: /cvs/docs/documentation-guide/en_US/module-struct.xml,v retrieving revision 1.2 retrieving revision 1.3 diff -u -r1.2 -r1.3 --- module-struct.xml 3 Feb 2007 22:29:37 -0000 1.2 +++ module-struct.xml 9 Mar 2007 01:16:05 -0000 1.3 @@ -41,48 +41,62 @@ | `-- 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> + <segmentedlist id="sg-module-contents"> + <title>CVS Module Contents</title> + <segtitle>Component</segtitle> + <segtitle>Type</segtitle> + <segtitle>Usage Notes</segtitle> + <seglistitem> + <seg>Primary language directory</seg> + <seg>required</seg> + <seg>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>.</seg> + </seglistitem> + <seglistitem> + <seg>Graphics directory</seg> + <seg>optional</seg> + <seg>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.</seg> + </seglistitem> + <seglistitem> + <seg>Translation (PO) directory</seg> + <seg>optional</seg> + <seg>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.</seg> + </seglistitem> + <seglistitem> + <seg>Makefile</seg> + <seg>required</seg> + <seg>The <filename>Makefile</filename> controls the build + process. Its content is discussed in <xref + linkend="ex-makefile"/>.</seg> + </seglistitem> + <seglistitem> + <seg><filename>rpm-info.xml</filename></seg> + <seg>required</seg> + <seg>The <filename>rpm-info.xml</filename> file contains + document specific metadata</seg> + </seglistitem> + </segmentedlist> </section> <section id="ch-getting-files-build-system"> <title>The Document Build System</title> @@ -109,7 +123,7 @@ <example id="ex-makefile"> <title>Sample Document Makefile</title> <programlisting><![CDATA[DOCBASE = example-doc -PRI_LANG = en_US +PRI_LANG = en_US OTHERS = de pt DOC_ENTITIES = doc-entities
@@ -125,48 +139,54 @@ 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> + <segmentedlist id="sg-makefile-variables"> + <title>Makefile Variables</title> + <segtitle>Variable</segtitle> + <segtitle>Explanation</segtitle> + <seglistitem> + <seg><systemitem class="macro">DOCBASE</systemitem></seg> + <seg>This variable contains the name for the main (parent) XML + document. Follow convention by naming your document after + the module name.</seg> + </seglistitem> + <seglistitem> + <seg><systemitem class="macro">PRI_LANG</systemitem></seg> + <seg>This variable contains the ISO code for the original + version of the document, such as + <systemitem>en_US</systemitem>.</seg> + </seglistitem> + <seglistitem> + <seg><systemitem class="macro">OTHERS</systemitem></seg> + <seg>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.</seg> + </seglistitem> + <seglistitem> + <seg><systemitem class="macro">DOC_ENTITIES</systemitem></seg> + <seg>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 + --></seg> + </seglistitem> + <seglistitem> + <seg><systemitem + class="macro">XMLFILES_template</systemitem></seg> + <seg>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. + </seg> + </seglistitem> + </segmentedlist> <important> <title>Files Exempt From Listing</title> <para>Do not include the document-specific entities XML file or @@ -233,54 +253,59 @@ 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> + <segmentedlist> + <title>Build Targets</title> + <segtitle>Target</segtitle> + <segtitle>Explanation</segtitle> + <seglistitem> + <seg><systemitem class="macro">html</systemitem></seg> + <seg>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.</seg> + </seglistitem> + <seglistitem> + <seg><systemitem class="macro">html-nochunks</systemitem></seg> + <seg>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.</seg> + </seglistitem> + <seglistitem> + <seg><systemitem class="macro">pdf</systemitem></seg> + <seg>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.</seg> + </seglistitem> + <seglistitem> + <seg><systemitem class="macro">tarball</systemitem></seg> + <seg>This target builds only the <command>tar(1)</command> + archive for all document languages.</seg> + </seglistitem> + <seglistitem> + <seg><systemitem class="macro">all</systemitem></seg> + <seg>This target builds all targets listed above.</seg> + </seglistitem> + <seglistitem> + <seg><systemitem class="macro">clean</systemitem></seg> + <seg>This target deletes any temporary, or generated files, but + does <emphasis>not</emphasis> erase any <abbrev>HTML</abbrev>, + <abbrev>PDF</abbrev>, or archive files.</seg> + </seglistitem> + <seglistitem> + <seg><systemitem class="macro">distclean</systemitem></seg> + <seg>This target erases all <abbrev>HTML</abbrev>, + <abbrev>PDF</abbrev>, and archive files. This target + automatically invokes the <filename>clean</filename> target as + well.</seg> + </seglistitem> + </segmentedlist> <section> <title>Adding or Changing Targets</title> <para>
docs-commits@lists.fedoraproject.org