Preparing packages for Docs Project
From FedoraProject
| 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. |
.png){kind=small}
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.
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, andothercreditelements in the original document - A description in the
translation/titles/descelement for the base language - If your document module includes i18n, an additional
translationelement for each additional language
4. You must also check, and possibly correct, the following:
- In the
changelogelement, 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
workerattribute in theauthorelement is filled from theauthorinitialselement from the original document. This may not totally agree with theinitialsattribute of theworkerelement assigned above in therpm-info.xmlfile'scolophonelement. Change theinitialsandidattribute of any workers who have changelog information to match theworkerattribute of theirauthorelements in thechangelog. (This is not the only solution to the problem, obviously, but may be the easiest.)
- Try and edit the
detailselements 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;
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
