Chapter 2. How Modules Work

Chapter 2. How Modules Work
Prev		Next

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 Fedora Documentation Project build tools locate resources in the module and use them to build new output such as HTML or RPM packages.

2.1. Structure of a Module

Example 2.1, “Example Module Structure” shows a directory tree of an example module, excluding any CVS folders. Note that this example document does not have branches.

example-doc/
    |
    |-- en_US/
    |       |-- example-doc.xml
    |       |-- para.xml
    |       |-- doc-entities.xml
    |       `-- rpm-info.xml
    |
    |-- figs/
    |       |-- fedora-logo-sprite.eps
    |       `-- fedora-logo-sprite.png
    |
    |-- po/
    |       |-- LINGUAS
    |       |-- de.po
    |       |-- example-doc.pot
    |       `-- pt.po
    |
    `-- Makefile

Example 2.1. Example Module Structure

CVS Module Contents

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^[1].
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 Portable Object, or PO, files created and used by translators. The Fedora Documentation Project 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. The `po/` directory also contains the `LINGUAS` file, which lists the active translation locales, or languages.
Makefile	required	The `Makefile` controls the build process. Its content is discussed in Example 2.2, “Sample Document Makefile”.
`rpm-info.xml`	required	The `rpm-info.xml` file contains document specific metadata

	Common Build Tools
	Never add the `docs-common` build tools directory to an individual module. Special formatting in the module list downloads these tools when a user checks out a document module. For more information, refer to Section 1.3.1, “Module Names”.

^[1]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.

Prev		Next
1.3. Naming Conventions	Home	2.2. The Document Build System