%FEDORA-ENTITIES-EN; ]> To work on official &FED; documentation you need to install the required tools. Follow the directions below to configure your system.

Install the "Authoring and Publishing" package group, which contains required DocBook XML files, stylesheets and scripts: su -c 'yum groupinstall "Authoring and Publishing"' Next, install the cvs package, which is used to handle revision control on files in the official repository: su -c 'yum install cvs' If you plan to use Emacs to edit DocBook XML documentation, install psgml, which adds helpful and time-saving functionality to maximize editing efficiency: su -c 'yum install psgml'

The &FDP;'s custom scripts and stylesheets are stored in CVS on the cvs.fedoraproject.org CVS server. When you check out a document module from CVS, the tools are included in the module inside the docs-common/ directory. To work on existing documents in CVS, refer to . The most powerful component in the &FDP; toolbox is DocBook XML. DocBook XML is a specific scheme for authoring technical documentation using Extensible Markup Language, or XML. XML allows authors to mark pieces of content with descriptive tags. The following output is an example of DocBook XML: This very short article is a demonstration of DocBook XML in its simplest form. Notice how the tags describe the content they surround, and how that content fits into the meaning of the text as a written work. ]]> This example article, entitled A Very Short Article, consists of only a single paragraph. The tags, or markup, surround elements of content to define the sense in which they are used. A paragraph, for example, is marked with para tags. Text that requires emphasis is marked with emphasis tags. The author does not worry about the visual formatting such as italics or font size. &FDP; build tools automatically perform all formatting tasks. The custom tools built by the &FDP; render DocBook source into a variety of formats for publication and distribution. They also allow translators to create localized versions of the XML documents for &DISTRO; users around the world. The flexibility of XML allows for a single document to be used many times for many purposes, like reusable code for a programmer. DocBook is itself very well documented. For more information about DocBook, visit . The DocBook site also features complete copies of DocBook: The Definitive Guide to browse and download, the canonical source for DocBook information. DocBook XML, like a computer program, has version numbers. The version used by &FDP; right now is &DBVER;. The DocBook web site may document a slightly newer version, but the majority of the schema still applies. Contributors who use the Microsoft Windows operating system can still make use of DocBook tools. For more information, refer to .

The &FDP; provides the tools, scripts, and stylesheets to transform your XML documents into other output formats such as HTML. In addition, these tools can build your document into a RPM package. To take advantage of these services, follow the conventions in this section to name your files. On the CVS server, directories that contain document files are called modules. Each module represents a single document. Each document may consist of several branches if that document changes with each release of &DISTRO;. Contributors can check out single branches of these modules or the entire module. Each document or branch may contain multiple XML source files. Use the cvs co -c command to view existing module names. cd ~/localrepo/fedora-docs/ The leftmost entry in each line is the name of a module you can check out from CVS. The rest of the line ensures that checkouts include the proper branch of a document and the common build tools. For more information on CVS, refer to . Note in the listing above that the about-fedora module has two branches available. One branch is for &DISTRO; 7 and one is for forward development to match the current work of developers. On the other hand, the documentation-guide module is not branched. Modules ending with the suffix -dir are not usually helpful to checkout directly. These modules do not include the common build tools and thus do not provide many of the functions contributors require.

Choose a module name that accurately reflects your document's subject, but avoid any name already taken. The document title without any use of the word &FEDLC; is a reasonable choice in most cases. Use the length descriptors tutorial or guide in the module name where appropriate. Do not use the word &FEDLC; to name modules in the &FDP; CVS repository. Document Name CVS Module Name Desktop User Guide desktop-user-guide Software Management with Yum yum-guide Using Pup pup-tutorial

Follow these guidelines for naming files to make collaboration and document reuse easy: As with module names, avoid using the word &FEDLC; in file names since it is redundant. If the document is comprised of many XML files, avoid repeating the name of the document when naming the constituent files. Avoid numbering files to show order, since editors and authors often rearrange documents or reuse their files in other documents.