documentation-guide Makefile, 1.10, 1.11 acknowledgments-en.xml, 1.8, 1.9 docs-getting-files-en.xml, 1.8, 1.9 documentation-guide-en.xml, 1.21, 1.22 docs-converting-en.xml, 1.1, NONE docs-converting-zh_CN.xml, 1.1, NONE
Tommy Reynolds (jtr)
fedora-docs-commits at redhat.com
Tue Dec 13 21:56:32 UTC 2005
Author: jtr
Update of /cvs/docs/documentation-guide
In directory cvs-int.fedora.redhat.com:/tmp/cvs-serv1242
Modified Files:
Makefile acknowledgments-en.xml docs-getting-files-en.xml
documentation-guide-en.xml
Removed Files:
docs-converting-en.xml docs-converting-zh_CN.xml
Log Message:
Added documentation about the document building system. Dropped the
one-line "converting" chapter by creating a "Prerequisites" section
in the "getting-files" section.
Index: Makefile
===================================================================
RCS file: /cvs/docs/documentation-guide/Makefile,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- Makefile 10 Dec 2005 20:21:04 -0000 1.10
+++ Makefile 13 Dec 2005 21:56:24 -0000 1.11
@@ -1,15 +1,19 @@
-###############################################################################
+#######################################################################
# Makefile for RHLP docs project
# Created by: Tammy Fox <tfox at redhat.com>
# Last edited by: Tammy Fox <tfox at redhat.com>
# WARNING: need passivetex 1.24 for pdf generation to work
# License: GPL
# Copyright 2003 Tammy Fox, Red Hat, Inc.
-###############################################################################
+#######################################################################
LANGUAGES = en zh_CN
DOCBASE = documentation-guide
-XMLEXTRAFILES-en =
+XMLEXTRAFILES-en=acknowledgments-en.xml docs-emacs-en.xml \
+ docs-emacs-nxml-en.xml docs-getting-files-en.xml \
+ docs-intro-en.xml docs-rh-guidelines-en.xml docs-style-en.xml \
+ docs-tutorial-en.xml docs-vim-en.xml docs-xml-tags-en.xml \
+ documentation-guide-en.xml
######################################################
include ../docs-common/Makefile.common
Index: acknowledgments-en.xml
===================================================================
RCS file: /cvs/docs/documentation-guide/acknowledgments-en.xml,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- acknowledgments-en.xml 13 Sep 2004 02:14:06 -0000 1.8
+++ acknowledgments-en.xml 13 Dec 2005 21:56:24 -0000 1.9
@@ -37,4 +37,9 @@
linkend="s1-xml-tags-screen"></xref>.
</para>
+ <para>
+ A patch from Tommy Reynolds (Tommy.Reynolds at MegaCoder.com) has been
+ applied to more fully explaing the document building system.
+ </para>
+
</chapter>
Index: docs-getting-files-en.xml
===================================================================
RCS file: /cvs/docs/documentation-guide/docs-getting-files-en.xml,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- docs-getting-files-en.xml 19 Sep 2005 00:00:31 -0000 1.8
+++ docs-getting-files-en.xml 13 Dec 2005 21:56:24 -0000 1.9
@@ -1,83 +1,389 @@
<!-- $Id: -->
<!--
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
- <!ENTITY BOILERPLATE "This header makes editing XML easier" >
+<!ENTITY BOILERPLATE "This header makes editing XML easier" >
+<!ENTITY FDPX "Fedora Docs Project" >
+<!ENTITY FED "Fedora" >
]>
-->
<chapter id="ch-getting-files">
- <title>Getting the Files</title>
+ <title>Prerequisites</title>
+ <para>
+ Before you being working with the &FED; documents, you must have certain tools and packages installed on your system.
+ The directions below will help you configure your setup.
+ </para>
+
+ <section id="ch-getting-files-system-packages">
+ <title>System Packages</title>
<para>
- To start working on the Docs Project, you will need the appropriate
- DocBook XML files, stylesheets, and scripts. The following packages are
- required:
- </para>
+ To start working on the Docs Project, you will need the appropriate DocBook XML files, stylesheets, and scripts.
+ The following packages are required:
+ </para>
<itemizedlist>
<listitem>
- <para><filename>xmlto</filename> — for producing HTML and PDF outputs</para>
+ <para>
+ <filename>xmlto</filename> — for producing HTML and PDF outputs.
+ </para>
</listitem>
<listitem>
- <para><filename>docbook-style-xsl</filename> — for the default XSLT stylesheets we
- build on</para>
+ <para>
+ <filename>docbook-style-xsl</filename> — for the default XSLT stylesheets we build on.
+ </para>
</listitem>
<listitem>
- <para><filename>docbook-dtds</filename> — XML versions of the DocBook DTD</para>
+ <para>
+ <filename>docbook-dtds</filename> — XML versions of the DocBook DTD
+ </para>
</listitem>
</itemizedlist>
<para>
- The custom scripts and stylesheets used are all stored in CVS on the
- <computeroutput>cvs.fedora.redhat.com</computeroutput> CVS server.
- You need to check them out along with the DocBook XML files for the
- existing docs.
- </para>
+ You can verify these packages are on your system by:
+ </para>
+
+ <screen>
+ <userinput>
+rpm -q xmlto
+rpm -q docbook-style-xsl
+rpm -q docbook-dtds
+</userinput>
+ </screen>
<para>
- You should perform these steps only once, when you first make a checkout
- from docs CVS. When you see the password prompt, press the
- <keycap>Enter</keycap> key.
- </para>
+ Any missing package can be installed using <application>yum(8)</application> this way:
+ </para>
+
+ <screen>
+ <userinput>
+su -c 'yum install xmlto'
+su -c 'yum install docbook-style-xsl'
+su -c 'yum install docbook-dtds'
+</userinput>
+ </screen>
+ </section>
+ <section id="ch-getting-files-fdp">
+ <title>Fedora Documentation Tools</title>
+
+ <para>
+ You need perform these steps only once.
+ These files are common to all the &FDPX; documents.
+ </para>
+
+ <para>
+ The custom scripts and stylesheets used are all stored in CVS on the <computeroutput>cvs.fedora.redhat.com</computeroutput> CVS server.
+ You need to check them out along with the DocBook XML files for the existing docs.
+ </para>
-<screen>
-<userinput>mkdir my-fedora-docs
-cd my-fedora-docs
+ <para>
+ When you see the password prompt, press the <keycap>Enter</keycap> key.
+ In the example below, we also show how to obtain a copy of an existing &FDPX; document.
+ </para>
+
+ <screen>
+<userinput>mkdir my-fedora-docs-sandbox
+cd my-fedora-docs-sandbox
export CVSROOT=:pserver:anonymous at cvs.fedora.redhat.com:/cvs/docs
cvs login
cvs co docs-common
cvs co example-tutorial</userinput>
</screen>
-
+ </section>
+ <section id="ch-getting-files-filenames">
+ <title>Filename Conventions</title>
<para>
- When you perform an anonymous CVS checkout, you can view the files and
- retreive the latest versions. You cannot add (commit) any updates or new
- files back to the repository. To commit changes to CVS, you must have
- <abbrev>CVS</abbrev> write access. Refer to <ulink
- url="http://fedoraproject.org/wiki/DocsProject/NewWriters"/> to learn
- about getting write access to <abbrev>CVS</abbrev>.
+ &FDPX; 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, your document can automatically be built into an <abbrev>RPM</abbrev> package.
</para>
-
<para>
- To see a list of the available documents:
+ To take advantage of these services, you should follow our conventions for naming your files.
+ While you may choose whatever filenames you like, adopting our practices will make your life simpler.
+ Of course, if you are bringing your own document into our building system, changing hundreds of filenames may seem quite a burden; relax, we can use your filenames with just a little work on your part.
+ Read on to find out how.
</para>
-
-<screen><userinput>cvs co -c</userinput></screen>
-
+ <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.
+ Name your document directory something related to its subject, just avoid any name already taken.
+ The <userinput>cvs co -c</userinput> command mentioned earlier will show you the names already taken.
+ </para>
+ </section>
+ <section id="ch-getting-files-i18n">
+ <title>Anticipating I18N Translation</title>
+ <para>
+ The &FDPX; 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; filenames must be unique.
+ </para>
+ <para>
+ &FDPX; filenames are constructed appending a dash followed by the <abbrev>ISO</abbrev> language symbol before any file extention.
+ For example, a file whose language content is <abbrev>US</abbrev> English could be named <filename>mydoc-en.xml</filename>; the file containing its Chinese translation would then be 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>&FDPX; 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>
- Pick your document of interest and then download it to your working directory:
+ 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>
-
-<screen><userinput>cvs co example-tutorial</userinput></screen>
-
<para>
- Except for the <citetitle>&IG;</citetitle>, all documentation in CVS must
- be tutorials written in DocBook XML article format using the template in
- the <filename>example-tutorial</filename> directory. Each tutorial
- <emphasis>must</emphasis> be in its own directory. No XML files should be
- in the root directory.
+ 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's paste.
</para>
-
- </chapter>
+ <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>Finding 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>
+ <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.
+ </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>
Index: documentation-guide-en.xml
===================================================================
RCS file: /cvs/docs/documentation-guide/documentation-guide-en.xml,v
retrieving revision 1.21
retrieving revision 1.22
diff -u -r1.21 -r1.22
--- documentation-guide-en.xml 19 Sep 2005 00:00:31 -0000 1.21
+++ documentation-guide-en.xml 13 Dec 2005 21:56:24 -0000 1.22
@@ -22,7 +22,6 @@
<!ENTITY VIM SYSTEM "docs-vim-en.xml">
<!ENTITY TAGS SYSTEM "docs-xml-tags-en.xml">
<!ENTITY TUTORIAL SYSTEM "docs-tutorial-en.xml">
-<!ENTITY CONVERTING SYSTEM "docs-converting-en.xml">
<!ENTITY CVS SYSTEM "../docs-common/common/cvs-en.xml">
<!ENTITY ACKNOWLEDGMENTS SYSTEM "acknowledgments-en.xml">
<!ENTITY STYLE SYSTEM "docs-style-en.xml">
@@ -76,8 +75,6 @@
&STYLE;
- &CONVERTING;
-
&CVS;
&ACKNOWLEDGMENTS;
--- docs-converting-en.xml DELETED ---
--- docs-converting-zh_CN.xml DELETED ---
More information about the Fedora-docs-commits
mailing list