documentation-guide/en_US docs-intro.xml, 1.1, 1.2 docs-module-struct.xml, 1.1, 1.2
Paul W. Frields (pfrields)
fedora-docs-commits at redhat.com
Sat Dec 16 22:55:43 UTC 2006
- Previous message (by thread): homepage/devel/en_US rpm-info.xml,1.1,1.2
- Next message (by thread): documentation-guide/en_US acknowledgments.xml, 1.3, 1.4 docs-emacs.xml, 1.1, 1.2 docs-rh-guidelines.xml, 1.1, 1.2 docs-style.xml, 1.1, 1.2 docs-tutorial.xml, 1.1, 1.2 docs-vim.xml, 1.1, 1.2 docs-xml-tags.xml, 1.1, 1.2 documentation-guide.xml, 1.3, 1.4
- Messages sorted by:
[ date ]
[ thread ]
[ subject ]
[ author ]
Author: pfrields
Update of /cvs/docs/documentation-guide/en_US
In directory cvs-int.fedora.redhat.com:/tmp/cvs-serv21759
Modified Files:
docs-intro.xml docs-module-struct.xml
Log Message:
Slightly reorganize and improve module chapter, including more information on rpm-info and customizing a module.
Index: docs-intro.xml
===================================================================
RCS file: /cvs/docs/documentation-guide/en_US/docs-intro.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- docs-intro.xml 23 Nov 2006 02:24:17 -0000 1.1
+++ docs-intro.xml 16 Dec 2006 22:55:41 -0000 1.2
@@ -1,5 +1,5 @@
<!-- $Id$ -->
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!-- *************** Bring in Fedora entities *************** -->
@@ -9,44 +9,54 @@
]>
- <preface id="ch-intro">
- <title>Introduction</title>
+<preface id="ch-intro">
+ <title>Introduction</title>
- <para>
- The goal of the Docs Project is to create easy-to-follow, task-based
- documentation for &FC; users and developers. Other than the
- <citetitle>&IG;</citetitle>, each tutorial should be in DocBook XML
- article format, with one article per topic. This way, writers can
- contribute documentation about a specific topic without having to worry
- about how it fits into a manual or how it flows with other topics.
- </para>
-
- <para>
- The following tools are used:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>DocBook XML v4.1</para>
- </listitem>
- <listitem>
- <para>Custom XSLT stylesheets for both print and HTML versions</para>
- </listitem>
- <listitem>
- <para>Custom scripts to generate PDF and HTML output (use <command>xmlto</command>)</para>
- </listitem>
- <listitem>
- <para>Emacs with PSGML mode (optional, but recommended)</para>
- </listitem>
- <listitem>
- <para>Emacs with nXML mode (optional, but also recommended)</para>
- </listitem>
- </itemizedlist>
-
- <para>
- The purpose of this document is to explain the tools used by the Docs
- Project as well as to provide writing and tagging guidelines so that the
- documentation is consistent and easy-to-follow.
- </para>
-
- </preface>
+ <para>
+ The goal of the &FDP; is to create easy-to-follow, task-based
+ documentation for &FED; users and developers. Other than the
+ <citetitle>&IG;</citetitle>, each tutorial should be in DocBook XML
+ article format, with one article per topic. This way, writers can
+ contribute documentation about a specific topic without having to
+ worry about how it fits into a manual or how it flows with other
+ topics.
+ </para>
+
+ <para>
+ The following tools are used:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>DocBook XML v4.4</para>
+ </listitem>
+ <listitem>
+ <para>Custom XSLT stylesheets for both print and HTML
+ versions</para>
+ </listitem>
+ <listitem>
+ <para>Custom scripts to generate HTML output (use
+ <command>xmlto</command>)</para>
+ </listitem>
+ <listitem>
+ <para>Emacs with PSGML mode (optional, but recommended)</para>
+ </listitem>
+ <listitem>
+ <para>Emacs with nXML mode (optional)</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ This document explains the tools used by the &FDP; and provides
+ writing and tagging guidelines to make &FED; documentation is
+ consistent and easy-to-follow.
+ </para>
+
+</preface>
+
+<!--
+Local variables:
+mode: xml
+fill-column: 72
+End:
+-->
Index: docs-module-struct.xml
===================================================================
RCS file: /cvs/docs/documentation-guide/en_US/docs-module-struct.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- docs-module-struct.xml 29 Nov 2006 22:18:53 -0000 1.1
+++ docs-module-struct.xml 16 Dec 2006 22:55:41 -0000 1.2
@@ -17,24 +17,30 @@
packages.</para>
<section id="sn-module-struct">
<title>Structure of a Module</title>
- <para>The following listing shows a directory tree of an example module,
- excluding any <filename class="directory">CVS</filename> folders:</para>
-
- <screen><computeroutput><![CDATA[example-doc/
+ <para><xref linkend="ex-module-structure"/> shows a directory tree
+ of an example module, excluding any <filename
+ class="directory">CVS</filename> folders:</para>
+ <example id="ex-module-structure">
+ <title>Example Module Structure</title>
+ <screen><computeroutput><![CDATA[example-doc/
+ |
|-- en_US/
- |-- example-doc.xml
- |-- para.xml
- |-- doc-entities.xml
- |-- rpm-info.xml
+ | |-- example-doc.xml
+ | |-- para.xml
+ | |-- doc-entities.xml
+ | `-- rpm-info.xml
+ |
|-- figs/
- |-- fedora-logo-sprite.eps
- |-- fedora-logo-sprite.png
+ | |-- fedora-logo-sprite.eps
+ | `-- fedora-logo-sprite.png
+ |
|-- po/
- |-- de.po
- |-- example-doc.pot
- |-- pt.po
- |-- Makefile]]></computeroutput></screen>
-
+ | |-- de.po
+ | |-- example-doc.pot
+ | `-- pt.po
+ |
+ `-- Makefile]]></computeroutput></screen>
+ </example>
<formalpara>
<title>Primary language directory (required)</title>
<para>This is the only directory absolutely required. It is named for the
@@ -70,35 +76,39 @@
<formalpara>
<title>Makefile (required)</title>
<para>The <filename>Makefile</filename> controls the build process. Its
- content is discussed below. <!-- include xref here --></para>
+ content is discussed in <xref linkend="ex-makefile"/>.</para>
+ </formalpara>
+ <formalpara>
+ <title><filename>rpm-info.xml</filename> (required)</title>
+ <para>The <filename>rpm-info.xml</filename> file contains document
+ specific metadata</para>
</formalpara>
</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. The building system
- heavily leverages the <application>make(1)</application> tool and
- shell scripts to automate these activities, but authors need
+ 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
<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 and
- paste operations.
- </para>
- <para>
- <xref
- linkend="ch-getting-files-build-system-makefile"/> below shows the
- whole <filename>Makefile</filename> for a simple document having
- only two files and one language.
+ or a <command>make(1)</command>.
</para>
- <example id="ch-getting-files-build-system-makefile">
- <title>Sample Document Makefile</title>
- <programlisting>
-<![CDATA[
-DOCBASE = example-doc
+ <section id="sn-makefile">
+ <title>The Document <filename>Makefile</filename></title>
+ <para>
+ Each individual document has its own
+ <filename>Makefile</filename>, which only needs to be a few
+ lines long. The document <filename>Makefile</filename> content
+ is designed for cut and paste operations.
+ </para>
+ <para>
+ <xref linkend="ex-makefile"/> below shows the whole
+ <filename>Makefile</filename> for a simple document with two
+ files and two translations.
+ </para>
+ <example id="ex-makefile">
+ <title>Sample Document Makefile</title>
+ <programlisting><![CDATA[DOCBASE = example-doc
PRI_LANG = en_US
OTHERS = de pt
DOC_ENTITIES = doc-entities
@@ -108,234 +118,294 @@
${1}/para.xml
endef
-include ../docs-common/Makefile.common
-]]>
- </programlisting>
- </example>
- <para>
- Do not be concerned with some of the more complicated syntax (in
- particular, the <command>XMLFILES_template</command> stanza). An
- explanation for this template appears a few paragraphs
- below.</para>
- <formalpara>
- <title><varname>DOCBASE</varname></title>
- <para>This variable contains the name for the main (parent) XML document.
- Follow convention by naming your document after the module name.</para>
- </formalpara>
- <formalpara>
- <title><varname>PRI_LANG</varname></title>
- <para>This variable contains the ISO code for the original version of the
- document, such as <systemitem>en_US</systemitem>.</para>
- </formalpara>
- <formalpara>
- <title><varname>OTHERS</varname></title>
- <para>This variable contains a listing of ISO codes for any other versions
- into which the document has been translated. The module must contain a
- <filename class="directory">po/</filename> directory and a PO file for
- any indicated additional languages.</para>
- </formalpara>
- <formalpara>
- <title><varname>DOC_ENTITIES</varname></title>
- <para>This variable contains a listing of any files containing entity
- definitions. The &FDP; uses a special XML format to record
- document-specific entities, so they can be translated and built on the
- fly like any other XML document. An example is shown later in this
- guide. <!-- need xref here --></para>
- </formalpara>
- <formalpara>
- <title><varname>XMLFILES_template</varname></title>
- <para>This template allows the build tools to work with the
- document in multiple languages once it is translated. The
- <varname>${1}</varname> marking is a variable used to substitute
- the appropriate language. This template is not terribly
- complicated. For a new module, duplicate this section exactly
- except for the actual filenames. Prepend the text
- <varname>${1}/</varname>, in place of the language code
- directory name, to each filename in your document.
- </para>
- </formalpara>
- <important>
- <title>Files Exempt From Listing</title>
- <para>Do not include the document-specific entities XML file or the
- <filename>rpm-info.xml</filename> file, which will be discussed later in
- this guide.<!-- include xref --></para>
- </important>
- <!-- TEMP MARKER - PWF finished here Nov 28 2006 -->
- <para>
- The final line, beginning with <literal>include</literal>, references the
- main <filename>Makefile</filename> for the build system. This
- <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>
+include ../docs-common/Makefile.common]]></programlisting>
+ </example>
+ <para>
+ Do not be concerned with some of the more complicated syntax
+ such as the <command>XMLFILES_template</command> stanza. An
+ explanation for this template appears a few paragraphs
+ below.</para>
+ <formalpara>
+ <title><systemitem class="macro">DOCBASE</systemitem></title>
+ <para>This variable contains the name for the main (parent) XML
+ document. Follow convention by naming your document after the
+ module name.</para>
+ </formalpara>
+ <formalpara>
+ <title><systemitem class="macro">PRI_LANG</systemitem></title>
+ <para>This variable contains the ISO code for the original
+ version of the document, such as
+ <systemitem>en_US</systemitem>.</para>
+ </formalpara>
+ <formalpara>
+ <title><systemitem class="macro">OTHERS</systemitem></title>
+ <para>This variable contains a listing of ISO codes for any
+ other versions into which the document has been translated.
+ The module must contain a <filename
+ class="directory">po/</filename> directory and a PO file for
+ any indicated additional languages.</para>
+ </formalpara>
+ <formalpara>
+ <title><systemitem class="macro">DOC_ENTITIES</systemitem></title>
+ <para>This variable contains a listing of any files containing
+ entity definitions. The &FDP; uses a special XML format to
+ record document-specific entities, so they can be translated and
+ built on the fly like any other XML document. An example is
+ shown later in this guide. <!-- need xref here --></para>
+ </formalpara>
+ <formalpara>
+ <title><systemitem
+ class="macro">XMLFILES_template</systemitem></title>
+ <para>This template allows the build tools to work with the
+ document in multiple languages once it is translated. The
+ <systemitem class="macro">${1}</systemitem> marking is a
+ variable used to substitute the appropriate language. This
+ template is not terribly complicated. For a new module,
+ duplicate this section exactly except for the actual
+ filenames. Prepend the text <systemitem
+ class="macro">${1}/</systemitem>, in place of the language
+ code directory name, to each filename in your document.
+ </para>
+ </formalpara>
+ <important>
+ <title>Files Exempt From Listing</title>
+ <para>Do not include the document-specific entities XML file or
+ the <filename>rpm-info.xml</filename> file, which will be
+ discussed later in this guide.<!-- include xref --></para>
+ </important>
+ <para>
+ The final line, beginning with <literal>include</literal>,
+ references the main <filename>Makefile</filename> for the build
+ system. This <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>
+ </section>
+ <section>
+ <title>The Document <filename>rpm-info.xml</filename></title>
+ <para>Each document module's primary language directory contains a
+ file called <filename>rpm-info.xml</filename>. This file
+ contains document-specific metadata used to generate revision
+ history, copyright, and contributor information. It follows a
+ DTD specification included with the rest of the build system
+ tools.</para>
+ <para><xref linkend="ex-rpminfo"/> illustrates the content of
+ this file:</para>
+ <example id="ex-rpminfo">
+ <title>Example <filename>rpm-info.xml</filename> File</title>
+ <programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE rpm-info SYSTEM "../../docs-common/packaging/rpm-info.dtd">
+
+<rpm-info>
+ <colophon>
+ <worker surname="Smith" firstname="John" othername="Q."
+ id="JohnSmith" email="jsmith at example.com"
+ wholename="John Q. Smith" initials="JS"/>
+ </colophon>
+ <author worker="JohnSmith"/>
+ <license>
+ <rights>OPL</rights>
+ <version>1.0</version>
+ </license>
+ <copyright>
+ <year>2006</year>
+ <holder>John Q. Smith</holder>
+ </copyright>
+ <title>My Tutorial</title>
+ <desc>A tutorial about something important</desc>
+ <changelog order="newest-first">
+ <revision date="2006-06-01" number="0.1" role="doc">
+ <author worker="JohnSmith"/>
+ <details>First draft</details>
+ </revision>
+ </changelog>
+</rpm-info>]]></programlisting>
+ </example>
+ <para>If you are not familiar with XML editing, copy and paste
+ this file from an existing module and then edit the values for
+ the various elements as appropriate. Consult &FDP; members and
+ help channels for more assistance if needed.</para>
+ </section>
+ </section>
+ <section id="ch-getting-files-build-system-targets">
+ <title>Build System Actions</title>
<para>
- Add new document translations by:
+ To render the <abbrev>XML</abbrev> document into another format,
+ use one of the following <command>make</command> targets:
</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>
+ <formalpara>
+ <title><systemitem class="macro">html</systemitem></title>
+ <para>This target builds the "chunked" <abbrev>HTML</abbrev>
+ document for each defined translation. Output is placed in a
+ separate directory named <filename class="directory"><systemitem
+ class="macro">${DOCBASE}</systemitem>-<systemitem
+ class="macro">${LANG}</systemitem>/</filename>. Each
+ document section is a separate file within that
+ directory.</para>
+ </formalpara>
+ <formalpara>
+ <title><systemitem
+ class="macro">html-nochunks</systemitem></title>
+ <para>This target builds the "non-chunked" <abbrev>HTML</abbrev>
+ document for each defined translation. Output is placed in a
+ single file: <filename><systemitem
+ class="macro">${DOCBASE}</systemitem>-<systemitem
+ class="macro">${LANG}</systemitem>.html</filename>; no other
+ files are created.</para>
+ </formalpara>
+ <formalpara>
+ <title><systemitem class="macro">pdf</systemitem></title>
+ <para>This target builds only the <abbrev>PDF</abbrev> document
+ for all document languages. <abbrev>PDF</abbrev> production is
+ currently erratic and may not work for your document.</para>
+ </formalpara>
+ <formalpara>
+ <title><systemitem class="macro">tarball</systemitem></title>
+ <para>This target builds only the <command>tar(1)</command>
+ archive for all document languages.</para>
+ </formalpara>
+ <formalpara>
+ <title><systemitem class="macro">all</systemitem></title>
+ <para>This target builds all targets listed above.</para>
+ </formalpara>
+ <formalpara>
+ <title><systemitem class="macro">clean</systemitem></title>
+ <para>This target deletes any temporary, or generated files, but
+ does <emphasis>not</emphasis> erase any <abbrev>HTML</abbrev>,
+ <abbrev>PDF</abbrev>, or archive files.</para>
+ </formalpara>
+ <formalpara>
+ <title><systemitem class="macro">distclean</systemitem></title>
+ <para>This target erases all <abbrev>HTML</abbrev>,
+ <abbrev>PDF</abbrev>, and archive files. This target
+ automatically invokes the <filename>clean</filename> target as
+ well.</para>
+ </formalpara>
+ <section>
+ <title>Adding or Changing Targets</title>
<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.
+ To add a new target and rules, place them at the bottom of the
+ document <filename>Makefile</filename>, below the
+ <literal>include</literal> line. Follow your target definitions
+ with a double colon, not a single colon. The double colon
+ allows you to specify additional rules for existing targets, or
+ to write rules for a new target.
</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.
+ For more information on using <command>make(1)</command>,
+ consult the online documentation with the command <command>info
+ make</command> in a terminal.
</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.
+ Tutorial documents often make use of images such as <filename
+ class="extension">.PNG</filename> files. Store image files in
+ a <filename class="directory">figs/</filename> folder in the
+ main module directory, as shown in <xref
+ linkend="ex-module-structure"/>.
</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"/>.
+ Depending on the output media, sometimes images may be scaled,
+ streteched, or squashed. To minimize any distortions, we
+ recommend that you use only <filename
+ class="extension">.PNG</filename> images. Avoid <filename
+ class="extension">.JPG</filename> files. The
+ <command>convert(1)</command> program, from the <package
+ role="rpm">ImageMagick</package> <abbrev>RPM</abbrev> package,
+ provides a convenient way to reformat <filename
+ class="extension">.JPG</filename> images into <filename
+ class="extension">.PNG</filename> format. For more information
+ on formatting images such as screenshots, refer to <xref
+ linkend="s1-screenshots"/>.
+ </para>
+ <para>
+ Image files may be organized into subdirectories under
+ <filename>figs/</filename> if necessary. The document building
+ system recreates the image subdirectory structure in the output
+ documents.
+ </para>
+ <para>
+ Images often contain labels or other text which may need to be
+ localized. A screenshot of a program, for example, may require
+ a version for each translated language. Name language-dependent
+ image files such as program screenshots by adding the language
+ code to the filename, such as
+ <filename>menu-en_US.png</filename>. Language-independent
+ images, such as <filename>icon.png</filename>, do not need
+ language codes.
+ </para>
+ <para>
+ Sometimes, a document may require images that do not follow the
+ naming convention. To use these images with the document
+ building system, create an ordinary text file containing the
+ image filenames. This file must be named
+ <filename>figs/Manifest-</filename><systemitem
+ class="macro">${LANG}</systemitem> so the build system finds
+ it when searching for image filenames.
+ </para>
+ <para>
+ <xref linkend="ch-getting-files-build-system-manifest"/>
+ demonstrates one way to create this
+ <filename>Manifest</filename> file.
</para>
<example id="ch-getting-files-build-system-manifest">
- <title>Building A Manifest</title>
-<programlisting>
-rm -f figs/Manifest-en
+ <title>Building A Manifest</title>
+ <programlisting><![CDATA[rm -f figs/Manifest-en
find figs -print >/tmp/manifest
-mv /tmp/manifest figs/Manifest-en
-vi figs/Manifest-en
-</programlisting>
-</example>
-
+mv /tmp/manifest figs/Manifest-en]]></programlisting>
+ </example>
+ </section>
+ <section>
+ <title>Adding a New DocBook XML File</title>
+ <para>To add a new DocBook XML file to an existing document,
+ follow these steps:</para>
+ <procedure>
+ <step>
+ <para>Place the new DocBook XML file in the primary language
+ directory.</para>
+ </step>
+ <step>
+ <para>Edit the <filename>Makefile</filename> and add the
+ filename to the <varname>XMLFILES-${1}</varname> listing.
+ Append a <keycap>\</keycap> to the last existing line, and
+ on the next line add an entry for the new file. Remember to
+ add the <literal>${1}/</literal> prefix as a substitute for
+ the language directory name.</para>
+ </step>
+ </procedure>
+ </section>
+ <section>
+ <title>Adding a Translation</title>
+ <para>Translations are stored as PO (portable object) files, which
+ the toolchain transforms into translated documents. Each PO
+ file is based on the POT (PO template) for the document and
+ translated by the &FED; Translation Project. To add a
+ translation, follow these steps:</para>
+ <procedure>
+ <step>
+ <para>If the <filename class="directory">po/</filename>
+ directory does not exist, create it and add it to
+ CVS:</para>
+ <screen><![CDATA[mkdir po && cvs add po/]]></screen>
+ </step>
+ <step>
+ <para>If it does not exist, create the POT file:</para>
+ <screen><![CDATA[make pot]]></screen>
+ </step>
+ <step>
+ <para>Add the new translation language to the
+ <varname>OTHERS</varname> listing in the
+ <filename>Makefile</filename>.</para>
+ </step>
+ <step>
+ <para>Although translators often copy the POT manually to
+ create the new PO file, the following command also
+ works:</para>
+ <screen>make po/<replaceable>lang</replaceable>.po</screen>
+ </step>
+ </procedure>
</section>
</section>
</chapter>
- Previous message (by thread): homepage/devel/en_US rpm-info.xml,1.1,1.2
- Next message (by thread): documentation-guide/en_US acknowledgments.xml, 1.3, 1.4 docs-emacs.xml, 1.1, 1.2 docs-rh-guidelines.xml, 1.1, 1.2 docs-style.xml, 1.1, 1.2 docs-tutorial.xml, 1.1, 1.2 docs-vim.xml, 1.1, 1.2 docs-xml-tags.xml, 1.1, 1.2 documentation-guide.xml, 1.3, 1.4
- Messages sorted by:
[ date ]
[ thread ]
[ subject ]
[ author ]
More information about the Fedora-docs-commits
mailing list