[Mma] Re: documentation: are the .txi files the ones to edit?

Boud Roukema boud at astro.uni.torun.pl
Tue May 27 16:53:22 CEST 2003


hi again,

On Tue, 27 May 2003, David Bateman wrote:

> Dapr?s boud <boud at astro.uni.torun.pl> (le 27/05/2003):
> > hi help-octave,
> >   Are the *.txi files in the octave distribution, e.g.
> >
> > octave-2.1.48/doc/interpreter/*.txi
> >
> > the correct files to edit in order to work on Polish translations
> > of the main octave documentation:
> > http://www.octave.org/doc/octave_toc.html   ?
>
>
> Humm, yes and no.... "Yes" if you translate the .txi files they will
> appear in the documentation built with texinfo, etc. "No" in that the
> .txi files include the inbuilt help from the function definitions (see
> the file DOCSTRINGS and the @DOCSTRING directive in the .txi files) to
> build the .texi files. So if you do translate you get the text you
> changed translated, but also get all of the inlined help from the
> functions in English. As well you won't get translated versions of the
> function help (eg "help sin").

To start off with, I think having a mix of some bits in Polish and
some bits in English will already be a great help to Polish users,
and encourage them to do the translations of the untranslated bits
if they want to contribute.

If i understand things correctly,

src/DOCSTRINGS

is an extract of documentation with keywords like DEFUN_DLD inside
the source files like

src/DLD-FUNCTIONS/sqrtm.cc

and i guess  scripts/DOCSTRINGS    is a script for doing the extraction.

Is this right?

> If you really want Polish translations, the best place to start would
> be to propose a replacement for the octave on-line help system that
> includes i8n features.... Perhaps also i8n for the error/warning
> messages too... This is a big task.

The people likely to be interested in the short term mostly do not
have much programming experience, but as more people understand the
usefulness of GPL scientific packages, maybe there will be sufficient
interest.

> The only other alternative you
> have is to take the .texi (not the .txi files) files can translate
> a document that you maintainer seperately from octave.

So you mean ignore the comments:

@c DO NOT EDIT!  Generated automatically by munge-texi.

in these files?

> Note that matlab doesn't have internationalization either.... That this
> isn't really a reason for octave not to...

No need for free programming to be constrained by the limitations of
closed programming ;)

> Also this is not the first time this topic has come up. You should see
> the thread
>
> http://www.octave.org/octave-lists/archive/octave-maintainers.2003/msg00122.html

i had a look and am convinced that documentation is a complex issue.
But i have to learn sooner or later...

So regarding what's possible on a small scale, with moderate
maintainability requirements, it seems to me the obvious options are:

(1) modify the .texi files and make them and the output files
generated with texinfo available locally, but without any formal
integration into octave.

or
(2) modify the .txi files, put them into another directory,
and either
(2a) accept that a lot of English will remain in the final output
files from the @DOCSTRING directive, i.e. do nothing to change the
DEFUN directives in the program source files
or
(2b) do some general programming work on the whole structure of
documentation extraction, preferably in an i18n context allowing for
unicode, and then add translated (unicoded) documentation either inside of
the program/function source files with the DEFUN directive, or as
external files
or
(2c) translate src/DOCSTRINGS to, e.g.,  src/DOCSTRINGS-pl and
accept that this is only a hacked solution requiring an extra script
in order that it can be updated with English updates to at least
remain up-to-date in at least one language.

where
(1) implies local maintenance (or lack thereof),
(2-2a) allows integration into octave-forge, but is clearly incomplete
(2-2b) requires a lot more work than is likely on a short time scale
(2-2c) is a hack and would be frowned upon

So it seems that the suggestion is (1) is probably
most practical, and (2-2a) is possible but unsatisfying both to
Polish users and to general octave maintenance.

Is this correct?

boud



More information about the Mma mailing list