Documentation/translation FAQ

I added some new package documentation, but the pages don't show up in the compiled manual!

Most likely you forgot to ./configure again. This will make sure that new pages are detected and included.

Another reason could be that you did not add links in the parent page. In en/package/ are the category xml files that contain links to the package documentation files. Add the link to your new pages there.

This also applies if you get a message stating cannot generate system identifier for general entity "package.networking.net-ldap.search".

Compiling the manual shows it on the terminal, but does not generate files!

configure did not find the Docbook DSSSL or XSLT stylesheets. Install them first.

If the style sheets are installed, ./configure will list the found directories like this:


checking for docbook.dsl... autodetected: /path/to/dsssl-stylesheets-x.yz
checking for docbook.xsl... autodetected: /path/to/xsl-stylesheets-x.y.z

Is there a tool to help PEAR manual translators to track files changes?

Working on the translations is not just translating an English file and committing the results. Much of the work is needed to update the already translated ones, to get in sync with the content of the English files. To follow the modifications in the English tree, you should subscribe to the PEAR documentation mailing list to get SVN commit messages, or read the archives. If you never update your files, the translations can get useless.

Updating a foreign language file can get difficult, as you may not know when and who translated that file, so you may not know where you should look for the updates needed. We have one system for tracking the revisions and modification dates of the files in peardoc.

The Revision Comments

Instead of storing all responsibilities in a central file, the revision comment system stores them in the files they provide information about. Information about translator, revision numbers, and status information is stored in the revision comment. Let's see what would be in the header of the example file bookinfo.xml file in this case:

<!-- EN-Revision: 1.16 Maintainer: jane Status: ready -->

We can see the revision number for the last english file used to update the translation (EN-Revision: 1.16), the translator cvs account name. But we can also add some other status information in the case it is needed (eg. "partial" for incomplete translations). This revision comment system is basically about storing the information in the XML files, and not in a central place. This is extremely convenient now, as there are more than 2400 files in the English tree.

Currently, all three fields (English revision, Maintainer, Status) are needed. Maintainer is intended to be a SVN user name, or some nickname without a space, status can be anything without a space. Note, that this header is not updated by SVN (in contrast with $Revision, which is updated automatically). This is only updated when you edit the contents of the comment yourself.

You may see this as a good thing, but using these comments, you lose the quick look on the whole list of your files. No, you do not lose this, but get much more! If you would like to build a full list of you files, you can go to the /peardoc/ directory and run:

./scripts/revcheck_pear.php xx > revcheck.html

Here xx is the imaginary language code. After running this script you'll get a revcheck.html in the same directory. You can find revision comparisons and links to diffs for all the files in this language. You can also add a further restriction parameter, the maintainer name, so the script will only list the files corresponding to the given maintainer.

There are some optional extensions introduced for this script, to be available in this generated HTML page. This is why the translation.xml files are introduced. Here comes a simple translation.xml file for the imaginary xx language :


<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE translation SYSTEM "../dtds/translation.dtd">

<translation>

 <intro>
  This is some introductory text for the xx language translators
  about who is the manager of the translation, and where to find
  more information. This paragraph is printed on the top of the
  generated revcheck.html page.
 </intro>

 <translators>
  <person name="Joe Doe"     email="joe@hotmail.com"
   nick="joedoe" cvs="yes" editor="yes"/>
  <person name="Jane Smith"  email="jsmith@yahoo.com"
   nick="jane"   cvs="yes"/>
  <person name="Joe Forever" email="joe@forever.net"
   nick="joefo"  cvs="no"/>
 </translators>

 <work-in-progress>
  <file name="appendices/aliases.xml" person="joedoe"
   type="working"/>
  <file name="functions/dbx.xml"      person="joefo"
   type="working"/>
 </work-in-progress>

</translation>

In this file, you can add users without a SVN account, and can assign ready documents or work-in-progress files to them. The biggest advantage of using this addon is that all this information is used to generate dynamic tables of translators and files in the revcheck.html file. All translators are linked to from the individual files they are assigned to, and there is a nice table showing the state of files for all the translators. Assigning ready files may be needed if a time consuming update is in progress on that file.

There are two optional parameters you can add to a <file>, if you would like to record it: the date and revision. Date is assumed to be the date when the work was started, revision is the checked out revision of the English file used to start the work (denoted as CO-Revision in the generated table). There is currently no fixed format for the date parameter.

Another addon to this system is just to give credit to all people who worked on one file, and not just the current maintainer. To achieve this goal, we added the credit comments. One credit comment in eg. history.xml may look like this (in case Joe Doe translated the file initially, but Jane followed him to be the maintainer):

<!-- CREDITS: joedoe -->

The credits comment can contain a comma-separated list. These comments only affect the display of the translators table in revcheck.html.

Developer FAQ (Previous) Constitution (Next)
Last updated: Sat, 16 Feb 2019 — Download Documentation
Do you think that something on this page is wrong? Please file a bug report.
View this page in:
  • English

User Notes:

There are no user contributed notes for this page.