path: root/en_US/docs-getting-files.xml

<!-- $Id: -->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [

<!-- *************** Bring in Fedora entities *************** -->
<!ENTITY % FEDORA-ENTITIES-EN SYSTEM "fdp-entities.ent">
%FEDORA-ENTITIES-EN;

]>

<chapter id="ch-getting-files">
  <title>Prerequisites</title>

  <para>
    To work on official &FED; documentation you need to install the required
    tools.  The directions below will help you configure your setup.
  </para>

  <section id="ch-getting-files-system-packages">
    <title>System Packages</title>

    <para>
      Install the "Authoring and Publishing" package group, which contains
      required DocBook XML files, stylesheets and scripts:
    </para>

<screen>
<userinput>su -c 'yum groupinstall "Authoring and Publishing"'</userinput>
</screen>

    <para>
      Next, install the <filename>cvs</filename> package, which is used to
      handle revision control on files in the official repository:
    </para>

<screen>
<userinput>su -c 'yum install cvs'</userinput>
</screen>

  </section>

  <section id="ch-getting-files-fdp">
    <title>Fedora Documentation Tools</title>

    <para>
      The &FDP;'s custom scripts and stylesheets are stored in CVS on the
      <systemitem class="fqdomainname">cvs.fedora.redhat.com</systemitem> CVS
      server.  Check them out along with the DocBook XML files for the existing
      docs.
    </para>

<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
cvs login
cvs co docs-common</userinput>
</screen>

    <para>
      At the password prompt, press the <keycap>Enter</keycap> key.
    </para>

    <note>
      <title>Common Files</title>
      <para>
	You need to perform these steps only once.  These files are common to
	all the official documentation.
      </para>
    </note>

    <para>
      To work on existing documents in CVS, refer to <xref linkend="ch-cvs"/>.
    </para>

  </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.
    </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>.  Choose a module name that accurately
        reflects your document's subject, but avoid any name already taken.  Use
        the <command>cvs co -c</command> command to view existing module names.
      </para>
      <important>
	<title>Avoid Redundancy</title>
	<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.
	</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&apos;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
End:
-->