Re: translations of documentation
IIRC, last year Christian Leutloff (hi!) proposed a mechanism for this
based on a so-called "skeleton". It should be in the debian-doc mail
It more or less comes down to the following: Each section of a
document contains such a skeleton (using appropriate SGML entities)
outlining all the important information including figures, examples,
tables, etc. The author of a partiular (part of a) document for a
particular language uses the skeleton for writing the actual text in
that language. This means we only have to maintain these skeletons in
a central place, and let the (team of) language author(s) worry about
the exact wording.
Adam Di Carlo <email@example.com> writes:
> In article <[🔎] 19981108182946.E1407@debian.org>, "James A. Treacy" <firstname.lastname@example.org> writes:
> > Is there any mechanism in place for handling translations of Debian
> > documentation? I believe all the documentation is in CVS which is a
> > good start. We need to also set up CVS for any group that wishes to
> > translate documentation.
> The Debiandoc Project is ahead of the curve on that count, since we
> already manage all documentation that we can in CVS (on
> > Additionally, when there are multiple translations on a web site it
> > is much easier if the files are served using content
> > negotiation. This means that html files must have names in the
> > following format: <file>.<lang>.html Links from the main page could
> > explicitly point to pages in that language, but again, it is better
> > if links simply state <file> as this allows for partial translations
> > (if a file is not available in the preferred language, then the
> > english doc is served).
> > Can our current SGML system support something like this? If not,
> > how hard would it be to improve it?
> To be honest, I'm not completely clear on how we could extend our SGML
> system to accomodate multi-linguistic documentation and document
> Ideally we should separate the Language Independant version of a
> document from the Lanugage Specific elements. Based on an initial
> assumption that all documentation under the purview of the DDP is
> Debiandoc-SGML, this is going to require us to pretty deeply carve up
> the Debiandoc DTD, I fear.
> An example of a full system to manage a document, focusing on
> "synopticism", i.e., keeping multi-linguistic documents up to date at
> all time, can be found in the article, "The Addition of a Multilingual
> Component to an Existing Document Processing System",
> > Currently there is a random set of translations of Debian
> > documentation on the web page. As they don't follow any guidelines,
> > it is difficult to mix them in with the english versions. Simply
> > renaming files is not the solution as this will break all the
> > links. Clearly we need a better solution.
> Yes, I think we need a system which is fully integrated with our SGML
> processing and version control system. Even if it means we have a bit
> of up-front work ahead of us.
> At the simplest, we could use SGML conditionals, in conjunction with
> some sugar in debiandoc2*...
> > The Debian web pages themselves are a different story. Every
> > language that so desires can have their own source directory in
> > which they can translate pages. Now that an annoying bug in apache
> > has been found, it works quite well.
> The problem with that scheme, for me, is that there is no "intra-page"
> sharing of information. I.e., if I have a chart of Debian archive
> directory structure, this has to be "cut-n-pasted" between language
Ardo van Rangelrooij
home email: email@example.com, firstname.lastname@example.org
home page: http://www.tip.nl/users/ardo.van.rangelrooij
PGP fp: 3B 1F 21 72 00 5C 3A 73 7F 72 DF D9 90 78 47 F9