Re: [Pkg-shadow-devel] Re: Please push shadow-4.0.3-31sarge2 to sarge

On Wed, 20 Apr 2005, Nicolas [iso-8859-1] François wrote:

> Hi!
> 
> It seems the process is going to be
> 
>    groff -----------> XML ------------> POT
>              (1)               (2)       |
>                                          |  (3)
>                                         \|/
>    groff <----------- XML <------------ PO
>              (5)               (4)
> 

Final graph will be:


(*) XML ----> (using XSLT) roff files (english version)
  |
  +---+  using: xml2po and (*) man/<lang>/<lang>.po 
      |  
     XML (translated) 
      +-- (using XSLT): translated roff files.

Only files marked by (*) are in this grap source files.

> (1): doclifter (+ manual fix)
> (2), (4): xml2po
> (5): ??
> 
> (If there were a tool for (3), I think we would know ;)
> 
> Here are some comments/question on these steps.
> (Tomasz, don't forget I'm a po4a developer, some of the comments may be
> biased;)
> 
> (1): I had a look at some XML generated by doclifter (in upstream CVS)
>      Some commands were not recognized as commands:
>      <emphasis remap=\"B\">chsh</emphasis>
>      The seealso section could be more translator friendly, but it is not
>      a big deal.
>      It has the expected verbosity of XML (not a big deal with cut&paste)
> 
>      It seems the XML generated by (1) needs some manual fixes. It means
>      that the XML file will be the original document (in which we will
>      make modifications). Is this what you plan?
> 
>      Maybe doclifter can be configured to avoid some of the above issues.
>
> (2): I had a look at the PO files generated by xml2po with the XML
>      generated by doclifter.
>      I think the man page is split in too many blocks. This may put
>      difficulties to the translators.
>      It has the expected verbosity of XML (not a big deal with cut&paste).
>      There could be some spaces problem for the step (5). But, well, it
>      will depend on the tool used on (5).
> 
>      Here again, maybe a customization of xml2po is feasible.
> 
>      Also, we should see how (1) + (2) behave after some small
>      modification on the original groff page (does it fuzzy a lot of
>      strings?)
> 
> (4): after the translation, there are some spaces difference with the
>      original XML. This may or may not be a problem depending on (5).
> 
> (5): no tool was found at this time.
>      Maybe there is no need for a tool if texinfo accepts XML (but the DTD
>      will be different, so a tool (maybe XSLT) will anyway be needed)
> 
>      I thought the XML was a docbook DTD, so I tried docbook-to-man and
>      docbook2man, but I failed (maybe it is just a configuration issue)
> 
>      Tomasz pointed xmlroff, I did not tried it at this time.

xmlroff .. as base code for prepare man tool which will allow render roff 
rendered output for pager (like more, less, most) without groff tool :)

> Tomasz, I don't think you should spend too much time on the XML
> conversion, at least while we don't have a tool for (5).

For render now roff files you can use xmlto. This simple SH script and it 
uses manpages/docbook.xsl XSLT sheet and xsltproc tool.
So if you have installed xsltproc and XSLT sheets you can use xsltproc 
directly like me:

[kloczek@v20z-2 man]$ xsltproc /usr/share/sgml/docbook/xsl-stylesheets/manpages/docbook.xsl chage.1.xml
Writing chage.1 for refentry(chage.1)

Also .. Yes I know about doclifter .. it can be used only for generate raw
files which must be reviewed before plug this to planed infrastrucrure.

Now I have some base modifications for automake and I will commit this 
ASAP after release 4.0.8 (so I have few days for prepare this in some
useable form .. it is not so complicated task :)
Please rest some detailed discuss on this subject to monday evning after 
I'll commit this stuff :)

Probably next version (4.0.9) will be very soon (month or so; I have now 
in my work directory few patches for use getopt_long() in few other tools)
and on begining I plan only optionaly eable fully functional translation
infrastructure and still as default will be installad now avalaible roff
version man pages and/or will be possible per language enable generate 
roff documentation (on prepare dist tar ball level).
For me it will be very importand prepare dist tar ball with all this stuff 
not enabled by default but ready for review/use/discuss.

After prepare base/clean XML version man pages I plan release 4.1.0 for 
sign this as kind of milestone on avalabability of infrastructure for 
prepare best quality translated documentation. If base/clean XML version
will be prepared soon it is possible next version will be not 4.0.9 but 
4.1.0 :)

Above will also mean remove in CVS before 4.1.0 all man/*[1358] files and 
also per language man/<lang>/*[1358] after prepare (depending on progess 
prepare man/<lang>/<lang>.po files).

> Now, I will try to defend po4a (you can pass this if you just think I'm a
> po4a extremist ;)
> 
> Here are the 2 main advantages I can see:
>  * po4a allows to reuse the existing translations (I can show it to you on a
>    Polish page; and I can assure you that I won't cheat by translating the PO
>    myself).
>  * It is only one tool (time will tell if it means less bugs)

Like in case xml2po .. so this can't be argument :_)
But .. using po4a do not allow in easier way prapare all documentation in
roff format in one silistics (between source documents :)
Using XML and XSLT sheet you can manage this kind of "property" for
*all* roff documetation in single point :)

> > Seems it is realy much better solution than using po4a 
> > because using XML allow realy keep all ducumentatuon in one/common/good 
> > style.
> 
> Does it means you want to trash the PO after the translation and only keep
> the XML files?

No .. (in CVS repository) XML english SOURCE documentation in man/ 
directory and ONLY man/<lang>/<lang>.po file. This all what is neccessary 
for generate man/<lang>/*xml and from this roff files.
In dist tarball probably on begining wiell be good distribute all files 
(roff files too) because woring with only-source files (english man/*xml 
and man/*/*po files) will require in developer enviroment some software 
which isn't now in all distributions standard installation suits.

> po4a keeps also all the documentations in one/common style, which is the
> one from the original document (roff for man pages, XML for XML documents
> or TeX for TeX documents).

But you must control style all source documetation in diffrent way. Using 
XML/gettex you can completly forget about this because all roff rendered 
documetation stylistics is coded in XSLT sheet which in longer period will
be used not only in shadow :)

[..]
> > For now texinfo tools allow generate XML files from .texi .. after prepare
> > info viewer which will allo operate on XMLed info pages abowe will allow 
> > in future system with documentation in ONE format :)
> 
> If it is the same DTD as the one doclifter uses...
> Do you have any pointer on this subject?

Look at texinfo documetation. Now you can use:

$ makeinfo --xml foo.texi

for generate docbook output.

kloczek
-- 
-----------------------------------------------------------
*Ludzie nie mają problemów, tylko sobie sami je stwarzają*
-----------------------------------------------------------
Tomasz Kłoczko, sys adm @zie.pg.gda.pl|*e-mail: [email protected]*