From b7ac7d716b4efd6b02929d54d87b0a1f12d14cee Mon Sep 17 00:00:00 2001 From: "Paul W. Frields" Date: Sat, 16 Dec 2006 22:55:41 +0000 Subject: Slightly reorganize and improve module chapter, including more information on rpm-info and customizing a module. --- en_US/docs-intro.xml | 96 ++++---- en_US/docs-module-struct.xml | 540 ++++++++++++++++++++++++------------------- 2 files changed, 358 insertions(+), 278 deletions(-) diff --git a/en_US/docs-intro.xml b/en_US/docs-intro.xml index 98bc113..2df65f6 100644 --- a/en_US/docs-intro.xml +++ b/en_US/docs-intro.xml @@ -1,5 +1,5 @@ - - + @@ -9,44 +9,54 @@ ]> - - Introduction - - - The goal of the Docs Project is to create easy-to-follow, task-based - documentation for &FC; users and developers. Other than the - &IG;, 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. - - - - The following tools are used: - - - - - DocBook XML v4.1 - - - Custom XSLT stylesheets for both print and HTML versions - - - Custom scripts to generate PDF and HTML output (use xmlto) - - - Emacs with PSGML mode (optional, but recommended) - - - Emacs with nXML mode (optional, but also recommended) - - - - - 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. - - - + + Introduction + + + The goal of the &FDP; is to create easy-to-follow, task-based + documentation for &FED; users and developers. Other than the + &IG;, 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. + + + + The following tools are used: + + + + + DocBook XML v4.4 + + + Custom XSLT stylesheets for both print and HTML + versions + + + Custom scripts to generate HTML output (use + xmlto) + + + Emacs with PSGML mode (optional, but recommended) + + + Emacs with nXML mode (optional) + + + + + 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. + + + + + diff --git a/en_US/docs-module-struct.xml b/en_US/docs-module-struct.xml index a751f2b..cad060f 100644 --- a/en_US/docs-module-struct.xml +++ b/en_US/docs-module-struct.xml @@ -17,24 +17,30 @@ packages.
Structure of a Module - The following listing shows a directory tree of an example module, - excluding any CVS folders: - - shows a directory tree + of an example module, excluding any CVS folders: + + Example Module Structure + - + | |-- de.po + | |-- example-doc.pot + | `-- pt.po + | + `-- Makefile]]> + Primary language directory (required) This is the only directory absolutely required. It is named for the @@ -70,35 +76,39 @@ Makefile (required) The Makefile controls the build process. Its - content is discussed below. + content is discussed in . + + + <filename>rpm-info.xml</filename> (required) + The rpm-info.xml file contains document + specific metadata
The Document Build System - Common tasks such as rendering the document into either - HTML or PDF can be performed - easily using the document building system. The building system - heavily leverages the make(1) tool and - shell scripts to automate these activities, but authors need + The build system can render the document into another format such + as HTML or PDF, using + make(1) and shell scripts. Authors need no prior experience with either shell scripts - or a Makefile. While individual documents do - have their own Makefile, it is only a few - lines long and very simple. The document - Makefile content is designed for cut and - paste operations. - - - below shows the - whole Makefile for a simple document having - only two files and one language. + or a make(1). - - Sample Document Makefile - - + The Document <filename>Makefile</filename> + + Each individual document has its own + Makefile, which only needs to be a few + lines long. The document Makefile content + is designed for cut and paste operations. + + + below shows the whole + Makefile for a simple document with two + files and two translations. + + + Sample Document Makefile + - - +include ../docs-common/Makefile.common]]> + + + Do not be concerned with some of the more complicated syntax + such as the XMLFILES_template stanza. An + explanation for this template appears a few paragraphs + below. + + <systemitem class="macro">DOCBASE</systemitem> + This variable contains the name for the main (parent) XML + document. Follow convention by naming your document after the + module name. + + + <systemitem class="macro">PRI_LANG</systemitem> + This variable contains the ISO code for the original + version of the document, such as + en_US. + + + <systemitem class="macro">OTHERS</systemitem> + This variable contains a listing of ISO codes for any + other versions into which the document has been translated. + The module must contain a po/ directory and a PO file for + any indicated additional languages. + + + <systemitem class="macro">DOC_ENTITIES</systemitem> + 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. + + + <systemitem + class="macro">XMLFILES_template</systemitem> + This template allows the build tools to work with the + document in multiple languages once it is translated. The + ${1} 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 ${1}/, in place of the language + code directory name, to each filename in your document. + + + + Files Exempt From Listing + Do not include the document-specific entities XML file or + the rpm-info.xml file, which will be + discussed later in this guide. + + + The final line, beginning with include, + references the main Makefile for the build + system. This Makefile.common file contains + all the make(1) targets and rules to + actually build the document and the various archives. + +
+
+ The Document <filename>rpm-info.xml</filename> + Each document module's primary language directory contains a + file called rpm-info.xml. 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. + illustrates the content of + this file: + + Example <filename>rpm-info.xml</filename> File + + + + + + + + + + OPL + 1.0 + + + 2006 + John Q. Smith + + My Tutorial + A tutorial about something important + + + +
First draft
+ + +]]> + + 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. +
+ +
+ Build System Actions - Do not be concerned with some of the more complicated syntax (in - particular, the XMLFILES_template stanza). An - explanation for this template appears a few paragraphs - below. + To render the XML document into another format, + use one of the following make targets: + - <varname>DOCBASE</varname> - This variable contains the name for the main (parent) XML document. - Follow convention by naming your document after the module name. + <systemitem class="macro">html</systemitem> + This target builds the "chunked" HTML + document for each defined translation. Output is placed in a + separate directory named ${DOCBASE}-${LANG}/. Each + document section is a separate file within that + directory. - <varname>PRI_LANG</varname> - This variable contains the ISO code for the original version of the - document, such as en_US. + <systemitem + class="macro">html-nochunks</systemitem> + This target builds the "non-chunked" HTML + document for each defined translation. Output is placed in a + single file: ${DOCBASE}-${LANG}.html; no other + files are created. - <varname>OTHERS</varname> - This variable contains a listing of ISO codes for any other versions - into which the document has been translated. The module must contain a - po/ directory and a PO file for - any indicated additional languages. + <systemitem class="macro">pdf</systemitem> + This target builds only the PDF document + for all document languages. PDF production is + currently erratic and may not work for your document. - <varname>DOC_ENTITIES</varname> - 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. + <systemitem class="macro">tarball</systemitem> + This target builds only the tar(1) + archive for all document languages. - <varname>XMLFILES_template</varname> - This template allows the build tools to work with the - document in multiple languages once it is translated. The - ${1} 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 - ${1}/, in place of the language code - directory name, to each filename in your document. - + <systemitem class="macro">all</systemitem> + This target builds all targets listed above. - - Files Exempt From Listing - Do not include the document-specific entities XML file or the - rpm-info.xml file, which will be discussed later in - this guide. - - - - The final line, beginning with include, references the - main Makefile for the build system. This - Makefile.common file contains all the - make(1) targets and rules to actually build the - document and the various archives. - - - Add new document translations by: - - - - - Add the translated document files to the document directory. - Be sure to use the proper ${LANG} filename component to keep the filenames similar, but unique. - - - - - Edit the Makefile to append the new ${LANG} to the LANGUAGES definition. - - - - - Create a new XMLEXTRAFILES-${LANG} definition that references any document files other than the base file. - - - -
- Build System Actions - - To render the XML document into HTML or PDF the command: make html, - make html-nochunk, or make pdf may be used. - - - lists the defined build system targets. - - - Document Building Targets - - - - - - Target - Description - - - - - all - - - Builds the HTML, and the PDF forms of the document in all its defined translations. - - - Also builds the archives, such as tar(1) and rpm(8). - - - - - tarball - - - Builds only the tar(1) archive for all document languages. - - - - - pdf - - - Builds only the PDF document for all document languages. - - - Currently, PDF production is problematic and probably will not work for your document. - - - - - html - - - Builds only the HTML document for each defined translation. - Output is placed in a separate directory: - ${DOCBASE}-${LANG}/; each document section is given its own file within that directory. - - - - - html-nochunks - - - Builds only the HTML document for each defined translation. - Output is placed in a single file: - ${DOCBASE}-${LANG}.html; no other files are created. - - - - - clean - - - Deletes any temporary, or generated files. - Does not erase any HTML, PDF, or archive files. - - - - - distclean - - - Erases all HTML, PDF, and archive files. - Automatically invokes the clean target as well. - - - - - -
+ + <systemitem class="macro">clean</systemitem> + This target deletes any temporary, or generated files, but + does not erase any HTML, + PDF, or archive files. + + + <systemitem class="macro">distclean</systemitem> + This target erases all HTML, + PDF, and archive files. This target + automatically invokes the clean target as + well. + +
+ Adding or Changing Targets - You can add your own special targets and rules by placing them at the bottom of the document Makefile, below the include line. + To add a new target and rules, place them at the bottom of the + document Makefile, below the + include 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. - 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 make(1), + consult the online documentation with the command info + make in a terminal.
Using Document Image Files - Image files, such as .PNG, 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 figs/ subdirectory within your document directory. - In other words, place your image picture.png in the mydoc/figs/picture.png file. + Tutorial documents often make use of images such as .PNG files. Store image files in + a figs/ folder in the + main module directory, as shown in . - - Use PNG Images, Not JPG - - Depending on the output media, sometimes images may be scaled, - streteched, or squashed. - To minimize any distortions, we recommend that you use only - PDF images and avoid JPG files. - - - You may find the convert(1) program, from the ImageMagick RPM package, provides a convenient way to reformat any JPG images you already have. - - - You may organize your image files into as many subdirectories under figs/ as you choose. - The document building system will recreate your image subdirectory structure in the output documents. + Depending on the output media, sometimes images may be scaled, + streteched, or squashed. To minimize any distortions, we + recommend that you use only .PNG images. Avoid .JPG files. The + convert(1) program, from the ImageMagick RPM package, + provides a convenient way to reformat .JPG images into .PNG format. For more information + on formatting images such as screenshots, refer to . - 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 words-en.png separate from words-ru.png is a good practice. - An image file with no text can be named just picture.png, for example. + Image files may be organized into subdirectories under + figs/ if necessary. The document building + system recreates the image subdirectory structure in the output + documents. - 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 figs/Manifest-${LANG} so that the build system can find it as the search for image filenames begins. + 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 + menu-en_US.png. Language-independent + images, such as icon.png, do not need + language codes. - An easy way to create the figs/Manifest-${LANG} file is shown in . + 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 + figs/Manifest-${LANG} so the build system finds + it when searching for image filenames. + + + + demonstrates one way to create this + Manifest file. - Building A Manifest - -rm -f figs/Manifest-en + Building A Manifest + /tmp/manifest -mv /tmp/manifest figs/Manifest-en -vi figs/Manifest-en - - - +mv /tmp/manifest figs/Manifest-en]]> + +
+
+ Adding a New DocBook XML File + To add a new DocBook XML file to an existing document, + follow these steps: + + + Place the new DocBook XML file in the primary language + directory. + + + Edit the Makefile and add the + filename to the XMLFILES-${1} listing. + Append a \ to the last existing line, and + on the next line add an entry for the new file. Remember to + add the ${1}/ prefix as a substitute for + the language directory name. + + +
+
+ Adding a Translation + 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: + + + If the po/ + directory does not exist, create it and add it to + CVS: + + + + If it does not exist, create the POT file: + + + + Add the new translation language to the + OTHERS listing in the + Makefile. + + + Although translators often copy the POT manually to + create the new PO file, the following command also + works: + make po/lang.po + +
-- cgit