[ 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@php.net, for example). CVS commits go to these mailinglists (the commits to the main en/ tree go to phpdoc@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
At 03:02 30/12/2003, Jan Fabry wrote:
[ 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.
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.
Hi Jan. I'm curious what you mean by 'LiveDocs'?
Any further info please?
regards DaveP.
Dave Pawson wrote:
Hi Jan. I'm curious what you mean by 'LiveDocs'?
The PHP Manual is written in DocBook. DocBook gives you lots of tags and the conversion is done with DSSSL or XSL, but this has the drawback that compilation can take a long time. Because only a subset of these tags is actually used in the PHP Manual, someone had the idea of doing the conversion from DocBook XML to HTML by a PHP script. This is LiveDocs.
At first, LiveDocs was only meant as a quick viewer for people working on the manual. Because the compilation step is monolitic, when you change one file now, you have to recompile the whole tree. With LiveDocs, you would only need to generate a small XML index file, and LiveDocs is then able to display the requested page, and all relevant links (previous, next, cross-links, ...).
But then more features were added to LiveDocs (search, XHTML compatibility, ...) and now the plans are to do the whole online manual straight from LiveDocs. This would also give extra possibilities like user-specific viewings and fancy things like that.
Some extra links:
- LiveDocs homepage: [ http://thebrainroom.com/opensource/livedocs.php ] - LiveDocs CVS view: [ http://projects.thebrainroom.net:8008/oss/dir?d=livedocs ] - Discussion notes, see part 4, 'Buildsystem' for the discussion about LiveDocs [ http://cvs.php.net/co.php/phpdoc/RFC/2003_meeting_findings.txt?r=1.1 ] - Some info from Goba, the PHP Manual project leader [ http://news.php.net/article.php?group=php.doc&article=969357731 ]
Greetings,
Jan Fabry