Building packages for Docs Project

= How Docs Packaging Works =

The majority of required files are in the  module under the   folder. The packaging process uses a special  file which contains document metadata such as copyright, licensing, authorship, revision information, and package changelog data. The DTD for this info is in  as well, so you can edit with XML-aware editors and have your file validated properly.

The files needed are all created from the  file using XSLT and stylesheets prepared by FDP contributors:


 * Document info ( or ) in  package, the official Fedora documentation will appear on the top-level index page.

To use the new build system, you will have to first prep your document.

= The  File =

Although the DTD is the authoritative description for this file, the following information might be helpful to those contributors who are not comfortable reading it themselves. A proper  file is constructed in this fashion, surrounded by   tags. Not all required attributes are discussed here, but important usage is noted.


 * A  element containing one or more   elements (describing contributors)
 * The  attribute is used to reference contributors in later sections
 * The  attribute is used to populate a document's revision history
 * At least one  element with a   attribute pointing to someone in the   by
 * Any number of  and   elements, each with a   attribute pointing to someone in the   by
 * A  element containing   and   elements
 * One or more  elements containing   and   elements
 * A  element containing one or more   elements, one for each i18n lang containing:
 * A  element with the translated title of the document (e.g. Example Tutorial)
 * A  element containing a translated description of the document, no more than a sentence please! (e.g. A tutorial that gives examples of standard FDP usage conventions)
 * A  element containing one or more , in newest-first order.  Each   has:
 * a  of either doc or rpm, which tells the reader whether that revision information is for the document's DocBook revision history section or the document's RPM changelog
 * A  attribute, in the proper format for that revision (for doc revisions, YYYY-MM-DD; for rpm revisions, Fri Jan 6 2006)


 * A  attribute, which is for doc revisions a version number, and for rpm revisions a release number

= XSLT =

We use XSLT (eXtensible Stylesheet Language Transformation), a language for transforming XML documents into other XML documents, to create all the other files required for an RPM package. The process uses the  program to process the   file with an XSL stylesheet. If you want to learn more about XSLT, start here for an excellent tutorial, authored in part by Norman Walsh, the primary developer of DocBook.