Archive:Building packages for Docs Project

Old page
This page has been marked as "old", and likely contains content that is irrelevant or incorrect. If you can, please update this page. This page will be deleted if action is not taken.

All current modules in Docs CVS already follow these policies. The information in this page needs to be subsumed into the Documentation Guide, and references redirected thereto.

How Docs Packaging Works

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

The files needed are all created from the rpm-info.xml file using XSLT and stylesheets prepared by FDP contributors:

• Document info (<articleinfo> or <bookinfo>) in fdp-info-${LANG}.xml' file
• RPM spec file
• Scrollkeeper OMF for GNOME yelp
• Specialized HTML files and .desktop file for KDE khelpcenter
• .desktop file for Main Menu

Thanks to the maintainers of Fedora's yelp 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 rpm-info.xml 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 rpm-info.xml file is constructed in this fashion, surrounded by <rpm-info> tags. Not all required attributes are discussed here, but important usage is noted.

• A colophon element containing one or more worker elements (describing contributors)
• The id attribute is used to reference contributors in later sections
• The initials attribute is used to populate a document's revision history
• At least one author element with a worker attribute pointing to someone in the colophon by id
• Any number of editor and translator elements, each with a worker attribute pointing to someone in the colophon by id
• A license element containing rights and version elements
• One or more copyright elements containing year and holder elements
• A titles element containing one or more translation elements, one for each i18n lang containing:
• A title element with the translated title of the document (e.g. Example Tutorial)
• A desc 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 changelog element containing one or more revisions, in newest-first order. Each revision has:
• a role of either doc or rpm, which tells the reader whether that revision information is for the document's Doc'Book revision history section or the document's RPM changelog
• A date attribute, in the proper format for that revision (for doc revisions, YYYY-MM-DD; for rpm revisions, Fri Jan 6 2006)

It is not possible to "enforce" the date ordering or formatting in this file; the document maintainers are responsible for that. If it's not done right, the document might build, but RPM packages will not, so any problems will be apparent. Remember, newest change first!

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

Once you create a rpm-info.xml file, all revision history and RPM changelog information is entered into that file.

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 xsltproc program to process the rpm-info-xml 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 Doc'Book.