From Fedora Project Wiki

(Redirected from DocsProject/PackagePrep)

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.
This page describes the package preparation process for FDP only. If you are interested in packaging for Fedora Extras, refer to Extras/NewPackageProcess instead.

Prepping Your Doc

You can use a special script to generate the skeleton for your rpm-info.xml file. YOU WILL NEED TO EDIT THE SKELETON. It is not currently possible to generate a fully capable rpm-info.xml file automatically. The work required is minimal, although the rpm-info.xml 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 rpm-build package installed on your system, as well as the packages normally required for FDP work -- i.e. the "Authoring and Publishing" group.

You only need to perform this action once, and only for the parent file containing the articleinfo or bookinfo element. Any future revision to this document metadata will be made in the rpm-info.xml file.

1. Update your local CVS copy, including the docs-common module: 

cvs up docs-common my-doc

2. Change directory to the location of your existing document, which must already contain a bookinfo or articleinfo element. Then use db2rpm-info, 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 rpm-info.xml 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 author, editor, and othercredit elements in the original document
  • A description in the translation/titles/desc element for the base language
  • If your document module includes i18n, an additional translation element for each additional language

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

  • In the changelog 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 worker attribute in the author element is filled from the authorinitials element from the original document. This may not totally agree with the initials attribute of the worker element assigned above in the rpm-info.xml file's colophon element. Change the initials and id attribute of any workers who have changelog information to match the worker attribute of their author elements in the changelog. (This is not the only solution to the problem, obviously, but may be the easiest.)
  • Try and edit the details elements into single lines without breaks.

5. Validate your rpm-info.xml file when you are finished. You can use a DTD-aware editor like vi 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 articleinfo or bookinfo element, and replace it with the following entity reference: 

&FDP-INFO;
See the next section for how to define this entity.

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 articleinfo or bookinfo 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 articleinfo or bookinfo 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 article or book 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
Retrieved from "https://fedoraproject.org/w/index.php?title=Preparing_packages_for_Docs_Project&oldid=81459"