dgv2/en_US creating-document.xml,1.1,1.2
Paul W. Frields (pfrields)
fedora-docs-commits at redhat.com
Sun Jun 4 17:42:55 UTC 2006
Author: pfrields
Update of /cvs/docs/dgv2/en_US
In directory cvs-int.fedora.redhat.com:/tmp/cvs-serv10776
Modified Files:
creating-document.xml
Log Message:
Add some more content to document creation chapter
Index: creating-document.xml
===================================================================
RCS file: /cvs/docs/dgv2/en_US/creating-document.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- creating-document.xml 2 Jun 2006 06:09:25 -0000 1.1
+++ creating-document.xml 4 Jun 2006 17:42:53 -0000 1.2
@@ -19,25 +19,27 @@
own separate directory, or <firstterm>module</firstterm>, named
after the content. Each module contains a number of required files
which allow contributors to ensure the document can be easily built
- and published. To create a new document, simply follow these steps.
+ and published. To create a new document, follow these steps.
</para>
<procedure>
<step>
- <title>Checking Out Common Tools</title>
+ <title>Checkout Common Tools</title>
<para>
The <filename class="directory">docs-common</filename> module in
&SCM; contains essential tools and support files. To create a
new document, make a work area and check out this module on your
local system:
</para>
- <screen>
- <command>mkdir ~/fdp</command>
- <command>cd ~/fdp</command>
- <command>&SCM-CMD; -d &SCM-ROOT; co docs-common</command>
- </screen>
+
+<screen>
+<command>mkdir ~/fdp</command>
+<command>cd ~/fdp</command>
+<command>&SCM-CMD; -d &SCM-ROOT; co docs-common</command>
+</screen>
+
</step>
<step>
- <title>Creating a Module Directory</title>
+ <title>Create a Module Directory</title>
<para>
Use a descriptive name, but do not use the word "&FED;" in your
module's name. The following module names are good usage
@@ -55,6 +57,199 @@
</para>
</listitem>
</itemizedlist>
+
+<screen>
+<command>mkdir ~/fdp/<replaceable>my-tutorial</replaceable></command>
+</screen>
+
+ </step>
+ <step>
+ <title>Create a <filename>Makefile</filename></title>
+ <para>
+ The <filename>Makefile</filename> contains information required
+ by &FDP; build tools. To create a
+ <filename>Makefile</filename>, you can copy one from an
+ existing module and change the content for your document. You
+ can also use the template below as a guide.
+ </para>
+
+<screen>
+<computeroutput>DOCBASE = <replaceable>my-tutorial</replaceable>
+PRI_LANG = <replaceable>en_US</replaceable>
+OTHERS = <replaceable>pt</replaceable>
+DOC_ENTITIES = doc-entities
+define XMLFILES_template
+XMLFILES-${1}=${1}/${DOCBASE}.xml
+endef
+include ../docs-common/Makefile.common</computeroutput>
+</screen>
+
+ <para>
+ Be aware of the following details for each of the variables in
+ the <filename>Makefile</filename>:
+ </para>
+ <orderedlist numeration="loweralpha">
+ <listitem>
+ <para>
+ For <varname>DOCBASE</varname> use the name of the main (or
+ <firstterm>parent</firstterm>) document. Most writers and
+ editors use the same name for <varname>DOCBASE</varname> and
+ the module directory for clarity.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ For <varname>PRI_LANG</varname> use the locale code for the
+ language of the original document. The original document
+ does not have to be in English.
+ </para>
+ <important>
+ <title>Do Not Use <literal>en</literal></title>
+ <para>
+ The &FDP; does not use the locale code
+ <literal>en</literal>. Instead, use
+ <literal>en_US</literal>, <literal>en_GB</literal>, or
+ <literal>en_CA</literal>.
+ </para>
+ </important>
+ </listitem>
+ <listitem>
+ <para>
+ For <varname>OTHERS</varname> use the locale code for each
+ language for which a translation is provided. Separate the
+ codes with spaces. To disable a translation, place it
+ behind a comment symbol (<literal>#</literal>). If your
+ document has no translations yet, leave the space after the
+ <literal>=</literal> symbol blank.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ For <varname>DOC_ENTITIES</varname> list the names of any
+ document-specific entity definition files. In general, you
+ only need to create one of these files, although you may use
+ as many as you wish. Most documents only use the standard
+ <filename>doc-entities.xml</filename> file.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ For <varname>XMLFILES-${1}</varname> list the names of any
+ DocBook XML files in your document. Preface each filename
+ with the directory variable <filename
+ class="directory"><varname>${1}</varname>/</filename>. To
+ increase readability, list one file per line and end each
+ line with a backslash (<literal>\</literal>) except the
+ last:
+ </para>
+
+<screen>
+<computeroutput>XMLFILES-${1} = ${1}/my-tutorial.xml \
+ ${1}/my-tutorial-appendix.xml \
+ ${1}/my-tutorial-glossary.xml</computeroutput>
+</screen>
+
+ </listitem>
+ </orderedlist>
+ </step>
+ <step>
+ <title>Create <filename>rpm-info.xml</filename> File</title>
+ <para>
+ The <filename>rpm-info.xml</filename> file contains information
+ required to build your document. Build tools use this
+ information to generate a <sgmltag>bookinfo</sgmltag> or
+ <sgmltag>articleinfo</sgmltag> section for your document. They
+ also might use information in <filename>rpm-info.xml</filename>
+ to create RPM packaging data.
+ </para>
+ <para>
+ This XML file is based on a DTD described in
+ <filename>docs-common/packaging/rpm-info.dtd</filename>. To
+ write this file from scratch, use an editor that will validate
+ against an XML DTD. You can also copy an existing
+ <filename>rpm-info.xml</filename> file from another module and
+ make changes where appropriate.
+ </para>
+ </step>
+ <step>
+ <title>Create <filename>doc-entities.xml</filename> File</title>
+ <para>
+ The <filename>doc-entities.xml</filename> file contains required
+ document-specific entity definitions. These entities include
+ the name and version of the document, and any others you might
+ find useful. You can also group these entities to make this
+ file easier to read. The &FDP; translation process includes
+ this file, so translators can localize the content properly.
+ </para>
+ <para>
+ This XML file is based on a DTD described in
+ <filename>docs-common/common/entities/entities.dtd</filename>.
+ To write this file from scratch, use an editor that will
+ validate against an XML DTD. You can also copy an existing
+ <filename>doc-entities.xml</filename> file from another module
+ and make changes where appropriate.
+ </para>
+ <para>
+ You <emphasis>must</emphasis> include at least the following
+ entities in your document. Each entity's <sgmltag
+ class="attribute">kind</sgmltag> attribute must be the default
+ value of <sgmltag class="attvalue">term</sgmltag>, with the
+ <sgmltag class="element">text</sgmltag> element contents as
+ follows:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>DOCNAME</term>
+ <listitem>
+ <para>
+ Use the value of <varname>DOCBASE</varname> in your
+ <filename>Makefile</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>DOCVERSION</term>
+ <listitem>
+ <para>
+ Use a versioning number such as <literal>0.3.1</literal>.
+ Remember that this is not a normal decimal number, so the
+ value <literal>0.3.10</literal> is
+ <emphasis>greater</emphasis> than
+ <literal>0.3.9</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>DOCDATE</term>
+ <listitem>
+ <para>
+ Use the last revision date in ISO format (YYYY-MM-DD).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>DOCID</term>
+ <listitem>
+ <para>
+ This entity is the same in any document's
+ <filename>doc-entities.xml</filename> file:
+ </para>
+
+<screen>
+<computeroutput><![CDATA[<use entity="DOCNAME"/>-<use entity="DOCVERSION"/> (<use entity="DOCDATE"/>)]]></computeroutput>
+</screen>
+
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </step>
+ <step>
+ <title>Create Content</title>
+ <para></para>
+ </step>
+ <step>
+ <title>Create L10N Support</title>
+ <para></para>
</step>
</procedure>
</chapter>
More information about the docs-commits
mailing list