External Docbook XSLT: status update

[Luigi Toscano]

Hi,
as many of you probably know, I'm working on removing the embedded copy of 
Docbook XSLT (previous episodes here:
http://kde.markmail.org/thread/rp6gj6evd3zwgl3j ,
we are now at step 2).

Most of the work was already committed in 4.5.x; the only big issue is 
translation handling.

In the past, every change/customization was committed directly to 
kdelibs/kdoctools/docbook/xsl/common/<langcode>.xml and XSLT stylesheets for 
new languages have been committed directly to that directory. In the (near) 
future kdelibs/kdoctools/docbook (our internal copy of XSLT stylesheets) will 
be removed and all the remaining customization will be moved to 
kdelibs/kdoctools/customization.
You can already see some localization files under customization/xsl/, but it's 
a leftover from the past and those XSLT files were never used, so they will 
replaced.

= Technical notes (please skip it if you are not interested):
After the removal of docbook/xsl directory we will use the upstream version of 
docbook-xsl stylesheet. But don't be scared, because they are flexible enough 
to handle custom translations: it is possible to define a custom xml file 
(with the same structure of docbook/xsl/common/l10n.xml) with the list of 
localized files containing the customizations.
Unfortunately this is not enough for us, because using that file it is 
possible to define customization files only for those languages defined in the 
main list of languages, but we support languages which are not shipped with 
docbook-xsl (e.g. nds). In order to solve this issue, a custom program will 
generate two special files during the compilation of kdelibs: the list of 
complete languages (which will be used instead of xsl/common/l10n.xml) and the 
list of customization files (see the attached patch).

= How will this impact translators' work?
- XSL stylesheet will still be customizable, but the changes must be saved 
under kdelibs/kdoctools/customization/xsl/<lang-code>.xml.
- we will be able to handle customization for existing languages and 
completely new languages, but it will be better to push them upstream 
(http://docbook.sourceforge.net/).
- I will populate the initial structure of customization file extracting the 
most important custom strings from the current docbook/xsl/common/<lang>.xml, 
with the proper credits in the comments (from svn log - is it enough?). After 
this commit, please please check if something is missing.

= Drawbacks
The generated man pages have some differences (see the attached example) and 
few warnings are emitted, maybe some docbook files should be fixed. But I'd 
like to commit the changes as soon as possible and tune the system on the fly, 
in order to test them properly before the freeze of SC 4.6

Comments/ideas/suggestions?

Regards
-- 
Luigi

-------------- next part --------------
An embedded and charset-unspecified text was scrubbed...
Name: ark.1.new
URL: <http://mail.kde.org/pipermail/kde-core-devel/attachments/20101004/071c1ebe/attachment.ksh>
-------------- next part --------------
An embedded and charset-unspecified text was scrubbed...
Name: checkXML.1.new
URL: <http://mail.kde.org/pipermail/kde-core-devel/attachments/20101004/071c1ebe/attachment-0001.ksh>
-------------- next part --------------
An embedded and charset-unspecified text was scrubbed...
Name: kded4.8.new
URL: <http://mail.kde.org/pipermail/kde-core-devel/attachments/20101004/071c1ebe/attachment-0002.ksh>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: xslt_externalonly.diff
Type: text/x-patch
Size: 23630 bytes
Desc: not available
URL: <http://mail.kde.org/pipermail/kde-core-devel/attachments/20101004/071c1ebe/attachment.bin>