Preparing packages for Docs Project

= Prepping Your Doc =

You can use a special script to generate the skeleton for your  file. YOU WILL NEED TO EDIT THE SKELETON. It is not currently possible to generate a fully capable   file automatically. The work required is minimal, although the  file must have i18n information added by translators.

ASSUMPTIONS: Your document is in Fedora Docs CVS, and can be built already (i.e. "make" works correctly). You must have the  package installed on your system, as well as the packages normally required for FDP work -- i.e. the "Authoring and Publishing" group.

1. Update your local CVS copy, including the  module: cvs up docs-common my-doc 2. Change directory to the location of your existing document, which must already contain a  or   element. Then use, one of the FDP common scripts, to process the document. It automatically cleans up the output as well. cd my-doc ../docs-common/bin/db2rpm-info my-doc-en.xml > rpm-info.xml 3. Now edit the resulting  file. There are several comments which direct you to the proper locations. You may remove these comments after your editing is finished. You must currently add the following information:


 * Contributors not listed in,  , and   elements in the original document
 * A description in the  element for the base language
 * If your document module includes i18n, an additional  element for each additional language

4. You must also check, and possibly correct, the following:


 * In the  element, look for proper date and version order - although the XSL stylesheet tries to do the right thing with regard to ordering, it may put things in the wrong order if (A) you don't use "YYYY-MM-DD" revision dates in your document's revision history, or (B) you have multiple revisions on a single date where the version number format is too complex


 * The  attribute in the   element is filled from the   element from the original document.  This may not totally agree with the   attribute of the   element assigned above in the   file's   element.  Change the   and   attribute of any workers who have changelog information to match the   attribute of their   elements in the  .  (This is not the only solution to the problem, obviously, but may be the easiest.)


 * Try and edit the  elements into single lines without breaks.

5. Validate your  file when you are finished. You can use a DTD-aware editor like  or Emacs, or the following command:

xmllint --noout --valid rpm-info.xml

{X} Any error messages indicate a non-valid XML file. Correct them before you continue.

6. Finally, remove the ENTIRE  or   element, and replace it with the following entity reference:

&FDP-INFO;

When you finish this process, your doc should be compliant with package building  standards.

= Beginning A New Document =

Documents which do not yet validate, or which do not yet have a  or   element should be handled differently. The "docs-common/packaging/rpm-info.dtd" file defines the correct structure needed to author an "rpm-info.xml" file.

To use the "rpm-info.xml" file to generate the necessary  or   XML, add an entity definition to the "<!DOCTYPE>" element, that references a file that will be automatically build shortly. An element such as this:

<!ENTITY FDP-INFO SYSTEM "fdp-info-en.xml" >

and immediately after your  or   element, insert the entity reference:

&FDP-INFO;

Save the file, and type this command to extract the document information from the "rpm-info.xml" file:

make fdp-info