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.