Archive:Docs/Drafts/DocumentationGuide/Tools/BuildTools

From FedoraProject

Jump to: navigation, search

Build Tools

Building in CVS

To build your document, create a Makefile that follows FDP standards. You can always find a template in the example-tutorial module in CVS. Simply copy that file into your module, and edit the template to provide appropriate values for your document.

  • DOCBASE - the name for your top (parent) XML file. Do not use the word "Fedora" in your file names, since it is unnecessary.
  • PRI_LANG - the language of the original XML file
  • OTHERS - any translations that have been provided for the document.
  • DOC_ENTITIES - if you created any document-specific entities for your document, refer to the entities XML file here. (FIXME: xref to what this means)
  • XMLFILES-${1} - inside the XMLFILES_template, this variable should be set to a list of all substantive XML files that are part of your document. Rules:
  • Prepend ${1}/ to each file, like this: ${1}/my-tutorial.xml
  • Include only your document's XML files, not any document-specific entities files.
  • If you have more than one XML file, list only one per line, with a \ backslash character after each one except the last. This convention allows make to interpret the list correctly but maintains human readability.

Correct Makefile declarations look like the following example, where the document is in US English with translations in German (de) and Brazilian Portugese (pt_BR):

DOCBASE            = my-tutorial
PRI_LANG           = en_US
OTHERS             = de pt_BR
XMLFILES-${1}=${1}/my-tutorial.xml \
${1}/my-tutorial-appendix.xml \
${1}/my-tutorial-colophon.xml

The Makefile template includes the following directive:

include ../docs-common/Makefile.common

By using this directive, your Makefile does not need to contain the numerous build rules required to build your documents. Instead, it reads them from the Makefile.common file that is part of the docs-common module in CVS.

To build your document, simply issue one of the following commands:

make html                 # Build multi-page HTML for all languages
make html-<LANG>          # Build multi-page HTML for one language
make html-nochunks        # Build single-page HTML for all languages
make html-nochunks-<LANG> # Build single-page HTML for one language

To return your document module to its pristine state, use this command:

make distclean

To see a list of all the available make targets, use this command:

make help


Building Externally

(FIXME: This section is for users of the fedora-doc-common package as opposed to CVS.)