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

[Tomasz Kłoczko]

  This message is in MIME format.  The first part should be readable text,
  while the remaining parts are likely unreadable without MIME-aware tools.

--568760595-1411286523-1114036941=:6082
Content-Type: TEXT/PLAIN; charset=ISO-8859-2
Content-Transfer-Encoding: QUOTED-PRINTABLE

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

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

Final graph will be:


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

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

> (1): doclifter (+ manual fix)
> (2), (4): xml2po
> (5): ??
>=20
> (If there were a tool for (3), I think we would know ;)
>=20
> Here are some comments/question on these steps.
> (Tomasz, don't forget I'm a po4a developer, some of the comments may be
> biased;)
>=20
> (1): I had a look at some XML generated by doclifter (in upstream CVS)
>      Some commands were not recognized as commands:
>      <emphasis remap=3D\"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)
>=20
>      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?
>=20
>      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)=
=2E
>      There could be some spaces problem for the step (5). But, well, it
>      will depend on the tool used on (5).
>=20
>      Here again, maybe a customization of xml2po is feasible.
>=20
>      Also, we should see how (1) + (2) behave after some small
>      modification on the original groff page (does it fuzzy a lot of
>      strings?)
>=20
> (4): after the translation, there are some spaces difference with the
>      original XML. This may or may not be a problem depending on (5).
>=20
> (5): no tool was found at this time.
>      Maybe there is no need for a tool if texinfo accepts XML (but the DT=
D
>      will be different, so a tool (maybe XSLT) will anyway be needed)
>=20
>      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)
>=20
>      Tomasz pointed xmlroff, I did not tried it at this time.

xmlroff .. as base code for prepare man tool which will allow render roff=
=20
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=
=20
uses manpages/docbook.xsl XSLT sheet and xsltproc tool.
So if you have installed xsltproc and XSLT sheets you can use xsltproc=20
directly like me:

[kloczek@v20z-2 man]$ xsltproc /usr/share/sgml/docbook/xsl-stylesheets/manp=
ages/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=20
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=20
I'll commit this stuff :)

Probably next version (4.0.9) will be very soon (month or so; I have now=20
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=20
roff documentation (on prepare dist tar ball level).
For me it will be very importand prepare dist tar ball with all this stuff=
=20
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=20
sign this as kind of milestone on avalabability of infrastructure for=20
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=20
4.1.0 :)

Above will also mean remove in CVS before 4.1.0 all man/*[1358] files and=
=20
also per language man/<lang>/*[1358] after prepare (depending on progess=20
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 ;)
>=20
> Here are the 2 main advantages I can see:
>  * po4a allows to reuse the existing translations (I can show it to you o=
n a
>    Polish page; and I can assure you that I won't cheat by translating th=
e 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=20
> > because using XML allow realy keep all ducumentatuon in one/common/good=
=20
> > style.
>=20
> Does it means you want to trash the PO after the translation and only kee=
p
> the XML files?

No .. (in CVS repository) XML english SOURCE documentation in man/=20
directory and ONLY man/<lang>/<lang>.po file. This all what is neccessary=
=20
for generate man/<lang>/*xml and from this roff files.
In dist tarball probably on begining wiell be good distribute all files=20
(roff files too) because woring with only-source files (english man/*xml=20
and man/*/*po files) will require in developer enviroment some software=20
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=
=20
XML/gettex you can completly forget about this because all roff rendered=20
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 prep=
are
> > info viewer which will allo operate on XMLed info pages abowe will allo=
w=20
> > in future system with documentation in ONE format :)
>=20
> 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
--=20
-----------------------------------------------------------
*Ludzie nie maj=B1 problem=F3w, tylko sobie sami je stwarzaj=B1*
-----------------------------------------------------------
Tomasz K=B3oczko, sys adm @zie.pg.gda.pl|*e-mail: kloczek@rudy.mif.pg.gda.p=
l*
--568760595-1411286523-1114036941=:6082--