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
1. 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
1. 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
, andothercredit
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
1. 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 theauthor
element is filled from theauthorinitials
element from the original document. This may not totally agree with theinitials
attribute of theworker
element assigned above in therpm-info.xml
file'scolophon
element. Change theinitials
andid
attribute of any workers who have changelog information to match theworker
attribute of theirauthor
elements in thechangelog
. (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.
1. 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.
1. 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