Ideas for the translations

[Jan Fabry]

[ sorry if this is posted twice - my fault ]

Hello,

I think it is time to do some research on how we should handle the
translations. There were some messages about this in the past, but we
should also look at other projects and how they handled it. I suggest
you reply to this message with information about other translation
efforts, so we can learn from them.


I'll start with a description of the PHP Manual, since I spend some of
my time there.

The whole documentation [ http://php.net/manual ] is a DocBook document,
split over many files. Every function is kept in a single file, and all
those files are then merged in the build process. Many entities exist,
especially for URL's.

A summary of the directory tree, sorted for clarity:

RFC/		-> internal discussion
howto/		-> documentation for newcomers
scripts/	-> scripts giving info about the manual
images/		-> all images
dtds/		-> the docbook XML 4.1.2 dtd, with some extensions
entities/	-> all used entities
dsssl/		-> DSSSL files, for converting the DocBook source
xsl/		-> XSL files, for converting to some newer formats
chm/		-> information to make CHM (Windows help) files
htmlhelp/	-> same, but newer (I think)
en/		-> the xml sources
LICENSE		-\
README		--> Some info about the stuff you downloaded
TODO		-/
contacts.txt	-> main contact for each translation
Makefile[.in]	-\
configure[.in]	--> Need to explain these?
manual.xml[.in]	-> the main file, which holds everything together

The main documentation tree resides in en/. Other translations use the
same directory structure (filenames!) and entities (references!), but in
their own directory (nl/, fr/, ...). If a file or entity is missing, the
English version is used.

When running ./configure, some scripts are run to fill up the missing
entities, and create the manual.xml file. The makefile then executes
(open)jade or other XML tools, depending on the requested output format.
Because the transformation can take a long time (30-150 mins per format,
about 6 formats, about 30 languages), the real site isn't updated that
often. They want to change from the 'real' DocBook conversion to a
homemade 'LiveDocs' project, that would convert the pages on-the-fly.


All translations have their own mailinglist (phpdoc-nl at php.net, for
example). CVS commits go to these mailinglists (the commits to the main
en/ tree go to phpdoc at php.net). Bugs that are filed in the Documentation
category also end up here. Normal discussions also take place in these
mailinglists.

All translators have CVS access to their directory tree, and to the main
tree. This way, they can clean up errors in the main text as they find
them while translating.


The CVS tree can be viewed at [ http://cvs.php.net ].

Greetings,

Jan Fabry