1.3. Naming Conventions

1.3. Naming Conventions
Prev	Chapter 1. Prerequisites	Next

The Fedora Documentation Project 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 Fedora. 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/
about-fedora about-fedora &docs-common
about-fedora-F-7 &about-fedora-F-7-dir &docs-common
about-fedora-F-7-dir -d about-fedora about-fedora/F-7
about-fedora-devel &about-fedora-devel-dir &docs-common
about-fedora-devel-dir -d about-fedora about-fedora/devel
build-docs   infrastructure/build-docs &docs-common
cvsroot      CVSROOT
desktop-up2date desktop-up2date &docs-common
desktop-user-guide desktop-user-guide &docs-common
desktop-user-guide-FC-6 &desktop-user-guide-FC-6-dir &docs-common
desktop-user-guide-FC-6-dir -d desktop-user-guide desktop-user-guide/FC-6
desktop-user-guide-devel &desktop-user-guide-devel-dir &docs-common
desktop-user-guide-devel-dir -d desktop-user-guide desktop-user-guide/devel
developer-guide developer-guide &docs-common
docs         .
docs-common  docs-common
documentation-guide documentation-guide &docs-common

Example 1.1. Partial List of CVS Modules

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 Chapter 8, CVS.

Note in the listing above that the about-fedora module has two branches available. One branch is for Fedora 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 Labeled `-dir`
	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.

1.3.1. Module Names

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 fedora is a reasonable choice in most cases. Use the length descriptors tutorial or guide in the module name where appropriate.

	Avoid Redundancy
	Do not use the word fedora to name modules in the Fedora Documentation Project CVS repository.

Correct Module Naming

Document Name	CVS Module Name
Desktop User Guide	desktop-user-guide
Software Management with Yum	yum-guide
Using Pup	pup-tutorial

1.3.2. File Names

Follow these guidelines for naming files to make collaboration and document reuse easy:

As with module names, avoid using the word fedora 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.

Prev	Up	Next
1.2. Fedora Documentation Tools	Home	Chapter 2. How Modules Work