documentation-guide/en_US getting-files.xml, 1.4, 1.5 module-struct.xml, 1.5, 1.6 rpm-info.xml, 1.5, 1.6 writing-guidelines.xml, 1.7, 1.8
Paul W. Frields (pfrields)
fedora-docs-commits at redhat.com
Fri Jun 29 00:11:02 UTC 2007
Author: pfrields
Update of /cvs/docs/documentation-guide/en_US
In directory cvs-int.fedora.redhat.com:/tmp/cvs-serv22086/en_US
Modified Files:
getting-files.xml module-struct.xml rpm-info.xml
writing-guidelines.xml
Log Message:
Some content updates, push new bugfix rev 0.3.0.1, no publishing needed yet
Index: getting-files.xml
===================================================================
RCS file: /cvs/docs/documentation-guide/en_US/getting-files.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- getting-files.xml 26 Jun 2007 01:28:46 -0000 1.4
+++ getting-files.xml 29 Jun 2007 00:10:59 -0000 1.5
@@ -16,7 +16,7 @@
tools. Follow the directions below to configure your system.
</para>
- <section id="ch-getting-files-system-packages">
+ <section id="sn-system-packages">
<title>System Packages</title>
<para>
@@ -59,42 +59,114 @@
</section>
- <section id="ch-getting-files-filenames">
- <title>Filename Conventions</title>
+ <section id="sn-getting-files-names">
+ <title>Naming Conventions</title>
<para>
- The &FDP; provides the tools, scripts, and stylesheets to transform your
- <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.
+ The &FDP; provides the tools, scripts, and stylesheets to
+ transform your <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, follow the conventions in this
+ section to name your files.
</para>
- <section id="ch-getting-files-filenames-doc">
- <title>Document Filenames</title>
- <para>
- Each document lives in a peer directory to the
- <filename>docs-common</filename> directory you extracted from the &FED;
- archive earlier. On the CVS server, these directories are called
- <firstterm>modules</firstterm>. Use
- the <command>cvs co -c</command> command to view existing module names.
- </para>
- <example>
- <title>Partial List of CVS Modules</title>
- <screen><userinput>cd ~/localrepo/fedora-docs/</userinput>
-<computeroutput>developer-guide developer-guide
+ <para>On the CVS server, directories that contain document files are
+ called <firstterm>modules</firstterm>. Each module represents a
+ single document. Each document may consist of several
+ <firstterm>branches</firstterm> if that document changes with each
+ release of &DISTRO;. Contributors can check out single branches
+ of these modules or the entire module. Each document or branch
+ may contain multiple XML source files.</para>
+ <para>Use the <command>cvs co -c</command> command to view existing
+ module names.</para>
+ <example>
+ <title>Partial List of CVS Modules</title>
+ <screen><userinput>cd ~/localrepo/fedora-docs/</userinput>
+<computeroutput><![CDATA[about-fedora about-fedora &docs-common
+about-fedora-F-7 &about-fedora-F-7-dir &docs-common
+about-fedora-F-7-dir -d about-fedora about-fedora/F-7
+about-fedora-devel &about-fedora-devel-dir &docs-common
+about-fedora-devel-dir -d about-fedora about-fedora/devel
+build-docs infrastructure/build-docs &docs-common
+cvsroot CVSROOT
+desktop-up2date desktop-up2date &docs-common
+desktop-user-guide desktop-user-guide &docs-common
+desktop-user-guide-FC-6 &desktop-user-guide-FC-6-dir &docs-common
+desktop-user-guide-FC-6-dir -d desktop-user-guide desktop-user-guide/FC-6
+desktop-user-guide-devel &desktop-user-guide-devel-dir &docs-common
+desktop-user-guide-devel-dir -d desktop-user-guide desktop-user-guide/devel
+developer-guide developer-guide &docs-common
docs .
docs-common docs-common
-documentation-guide documentation-guide
-example-tutorial example-tutorial</computeroutput></screen>
- </example>
+documentation-guide documentation-guide &docs-common]]></computeroutput></screen>
+ </example>
+ <para>The leftmost entry in each line is the name of a module you
+ can check out from CVS. The rest of the line ensures that
+ checkouts include the proper branch of a document and the common
+ build tools. For more information on CVS, refer to <xref
+ linkend="ch-cvs"/>.</para>
+ <para>Note in the listing above that the
+ <systemitem>about-fedora</systemitem> module has two branches
+ avalable. One branch is for &DISTRO; 7 and one is for forward
+ development to match the current work of developers. On the other
+ hand, the <systemitem>documentation-guide</systemitem> module is
+ not branched.</para>
+ <section id="ch-getting-files-naming-modules">
+ <title>Module Names</title>
<para>Choose a module name that accurately reflects your
- document's subject, but avoid any name already taken.</para>
+ document's subject, but avoid any name already taken. The
+ document title without any use of the word
+ <wordasword>&FEDLC;</wordasword> is a reasonable choice in most
+ cases. Use the length descriptors
+ <wordasword>tutorial</wordasword> or
+ <wordasword>guide</wordasword> in the module name where
+ appropriate.</para>
<important>
<title>Avoid Redundancy</title>
<para>
- Do not use the word <wordasword>&FED;</wordasword> to name
+ Do not use the word <wordasword>&FEDLC;</wordasword> to name
modules in the &FDP; CVS repository.
</para>
</important>
+ <segmentedlist id="sl-correct-module-naming">
+ <title>Correct Module Naming</title>
+ <segtitle>Document Name</segtitle>
+ <segtitle>CVS Module Name</segtitle>
+ <seglistitem>
+ <seg>Desktop User Guide</seg>
+ <seg>desktop-user-guide</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg>Software Management with
+ <application>Yum</application></seg>
+ <seg>yum-guide</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg>Using <application>Pup</application></seg>
+ <seg>pup-tutorial</seg>
+ </seglistitem>
+ </segmentedlist>
+ </section>
+ <section>
+ <title>File Names</title>
+ <para>Follow these guidelines for naming files to make
+ collaboration and document reuse easy:</para>
+ <itemizedlist>
+ <listitem>
+ <para>As with module names, avoid using the word
+ <wordasword>&FEDLC;</wordasword> in file names since it is
+ redundant.</para>
+ </listitem>
+ <listitem>
+ <para>If the document is comprised of many XML files, avoid
+ repeating the name of the document when naming the
+ constituent files.</para>
+ </listitem>
+ <listitem>
+ <para>Avoid numbering files to show order, since editors and
+ authors often rearrange documents or reuse their files in
+ other documents.</para>
+ </listitem>
+ </itemizedlist>
</section>
</section>
</chapter>
Index: module-struct.xml
===================================================================
RCS file: /cvs/docs/documentation-guide/en_US/module-struct.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- module-struct.xml 23 Jun 2007 05:24:16 -0000 1.5
+++ module-struct.xml 29 Jun 2007 00:10:59 -0000 1.6
@@ -19,7 +19,8 @@
<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>
+ class="directory">CVS</filename> folders. Note that this
+ example document does not have branches.</para>
<example id="ex-module-structure">
<title>Example Module Structure</title>
<screen><computeroutput><![CDATA[example-doc/
@@ -77,11 +78,11 @@
<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>
+ contains specially formatted Portable Object, or
+ <acronym>PO</acronym>, 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>
@@ -97,13 +98,29 @@
document specific metadata</seg>
</seglistitem>
</segmentedlist>
+ <important>
+ <title>Common Build Tools</title>
+ <para>Never add the <systemitem>docs-common</systemitem> build
+ tools directory to an individual module. Special formatting in
+ the module list downloads these tools when a user checks out a
+ document module. For more information, refer to <xref
+ linkend="ch-getting-files-naming-modules"/>.</para>
+ </important>
</section>
<section id="sn-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
+ <command>make(1)</command><footnote>
+ <para>In Linux and &DISTRO; documentation, references to
+ commands often include a number inside parentheses. This
+ number represents the section of
+ <firstterm>manpages</firstterm> that includes documentation
+ for that command. To read the manpage for
+ <command>make(1)</command>, use the command <command>man 1
+ make</command>.</para>
+ </footnote> and shell scripts. Authors need
<emphasis>no</emphasis> prior experience with either shell scripts
or a <command>make(1)</command>.
</para>
Index: rpm-info.xml
===================================================================
RCS file: /cvs/docs/documentation-guide/en_US/rpm-info.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- rpm-info.xml 23 Jun 2007 05:40:57 -0000 1.5
+++ rpm-info.xml 29 Jun 2007 00:10:59 -0000 1.6
@@ -33,6 +33,10 @@
<title>Fedora Documentation Guide</title>
<desc>Guidelines and procedures for producing documentation for Fedora</desc>
<changelog order="newest-first">
+ <revision date="2007-06-28" number="0.3.0.1">
+ <author worker="PaulWFrields"/>
+ <details>Assorted fixes to reflect newer version of reality</details>
+ </revision>
<revision date="2007-06-23" number="0.3.0">
<author worker="PaulWFrields"/>
<author worker="TammyFox"/>
Index: writing-guidelines.xml
===================================================================
RCS file: /cvs/docs/documentation-guide/en_US/writing-guidelines.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- writing-guidelines.xml 8 Mar 2007 03:00:44 -0000 1.7
+++ writing-guidelines.xml 29 Jun 2007 00:10:59 -0000 1.8
@@ -34,6 +34,26 @@
<ulink url="http://www.docbook.org/tdg/en/html/docbook.html"/>.
</para>
+ <section id="sn-xml-guidelines-header">
+ <title>File Header</title>
+ <section id="sn-xml-header-xml">
+ <title>XML Header</title>
+ <para>In accordance with good XML practices, the first line in any
+ DocBook XML source files should identify the file as XML. Use
+ the following line as the first line of any new XML file:</para>
+ <screen><![CDATA[<?xml version="1.0" encoding="UTF-8"?>]]></screen>
+ </section>
+ <section id="sn-xml-header-cvs">
+ <title>CVS Id Header</title>
+ <para>All the files must contain the CVS Id header. Use the
+ following line as the second line of any new XML file:</para>
+ <screen><![CDATA[<!-- $Id: -->]]></screen>
+ <para>Any time the file is committed to CVS, the line is updated
+ automatically to include information about the file. For
+ example:</para>
+ <screen><![CDATA[<!-- $Id$ -->]]></screen>
+ </section>
+ </section>
<section id="sn-id-naming-conventions">
<title>ID Naming Conventions</title>
@@ -132,7 +152,9 @@
<title>How To Fold Laundry</title>
<section id="sn-folding-shirts">
<title>Folding Shirts</title>]]></screen>
-
+ </section>
+ <section id="sn-xml-tags">
+ <title>XML Tags</title>
<indexterm>
<primary>xml tags</primary>
<secondary>caveats</secondary>
@@ -157,28 +179,31 @@
cannot be changed via the stylesheet.</para>
<para>Instead, use the <sgmltag>trademark</sgmltag> tag and its
- associates classes as follows:
- </para>
- <itemizedlist>
- <listitem>
- <para><sgmltag
- class="starttag">trademark</sgmltag>trademark symbol after
- me<sgmltag class="endtag">trademark</sgmltag>
- </para>
- </listitem>
- <listitem>
- <para><sgmltag class="starttag">trademark
- class="registered"</sgmltag>registered trademark symbol
- after me<sgmltag class="endtag">trademark</sgmltag>
- </para>
- </listitem>
- <listitem>
- <para><sgmltag class="starttag">trademark
- class="copyright"</sgmltag>copyright symbol after
- me<sgmltag class="endtag">trademark</sgmltag></para>
- </listitem>
- </itemizedlist>
- </listitem>
+ associates classes as follows:</para>
+ <segmentedlist>
+ <segtitle>DocBook XML source</segtitle>
+ <segtitle>Rendered content</segtitle>
+ <seglistitem>
+ <seg><code><![CDATA[<trademark>trademark symbol after
+ me</trademark>]]></code></seg>
+ <seg><trademark>trademark symbol after
+ me</trademark></seg>
+ </seglistitem>
+ <seglistitem>
+ <seg><code><![CDATA[<trademark
+ class="registered">registered trademark symbol after
+ me</trademark>]]></code></seg>
+ <seg><trademark class="registered">registered trademark
+ symbol after me</trademark></seg>
+ </seglistitem>
+ <seglistitem>
+ <seg><code><![CDATA[<trademark class="copyright">copyright
+ symbol after me</trademark>]]></code></seg>
+ <seg><trademark class="copyright">copyright symbol after
+ me</trademark></seg>
+ </seglistitem>
+ </segmentedlist>
+ </listitem>
</varlistentry>
<varlistentry>
<term>Content inside <sgmltag>para</sgmltag> tags</term>
@@ -239,22 +264,6 @@
</section>
- <section id="sn-xml-guidelines-header">
- <title>File Header</title>
-
- <para>All the files must contain the CVS Id header. If you create a
- new file, the first line must be:</para>
-
- <screen><![CDATA[<!-- $Id: -->]]></screen>
-
- <para>The first time it is committed to CVS (and every time it is
- committed to CVS) the line is updated automatically to include
- information about the file. For example:</para>
-
- <screen><![CDATA[<!-- $Id$ -->]]></screen>
-
- </section>
-
<section id="sn-xml-admon">
<title>Admonitions</title>
More information about the Fedora-docs-commits
mailing list