diff options
Diffstat (limited to 'en_US/docs-getting-files.xml')
| -rw-r--r-- | en_US/docs-getting-files.xml | 333 |
1 files changed, 13 insertions, 320 deletions
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: --> |