%FEDORA-ENTITIES-EN; ]> Documentation modules have a specific structure that enables the preconfigured tools to work correctly. Follow this structure exactly or you may have problems building your module. The &FDP; build tools locate resources in the module and use them to build new output such as HTML or RPM packages.

shows a directory tree of an example module, excluding any CVS folders: Component Type Usage Notes Primary language directory required This is the only directory absolutely required. It is named for the original language of the document, such as en_US (US English). The primary language does not have to be US English; all languages are supported. This directory contains all the XML source for the actual document, as well as XML source for document-specific entities Think of an XML entity as a predefined snippet of information. It can represent a chunk of XML source, or simply a word or character. If the information changes, it need be replaced only once, in the definition, to fix all usage. . Graphics directory optional The figs/ directory is an optional directory where graphics for the document should be stored. If graphics are screenshots that are particular to a language, the figs/ directory can and should be stored in a language directory. Translation (PO) directory optional The po/ directory contains specially formatted files created and used by translators. The &FDP; build tools use these files to create translated versions of documents. The translated documents are not stored in CVS; they are created as needed from these PO files. Makefile required The Makefile controls the build process. Its content is discussed in . rpm-info.xml required The rpm-info.xml file contains document specific metadata

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 make(1).

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. 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. Variable Explanation DOCBASE This variable contains the name for the main (parent) XML document. Follow convention by naming your document after the module name. PRI_LANG This variable contains the ISO code for the original version of the document, such as en_US. OTHERS 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. DOC_ENTITIES 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. XMLFILES_template 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. 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 section, beginning with define, locates the main Makefile.common 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.

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: OPL 1.0 2006 John Q. Smith 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.

To render the XML document into another format, use one of the following make targets: Target Explanation html 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. html-nochunks 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. pdf This target builds only the PDF document for all document languages. PDF production is currently erratic and may not work for your document. tarball This target builds only the tar(1) archive for all document languages. all This target builds all targets listed above. clean This target deletes any temporary, or generated files, but does not erase any HTML, PDF, or archive files. distclean This target erases all HTML, PDF, and archive files. This target automatically invokes the clean target as well.

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. For more information on using make(1), consult the online documentation with the command info make in a terminal.

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 . 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 . Image files may be organized into subdirectories under figs/ if necessary. The document building system recreates the image subdirectory structure in the output documents. 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. 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. /tmp/manifest mv /tmp/manifest figs/Manifest-en]]>

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.

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