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

David Bateman David.Bateman at motorola.com
Wed May 28 10:48:26 CEST 2003


Daprès John W. Eaton <jwe at bevo.che.wisc.edu> (le 27/05/2003):
> On 27-May-2003, David Bateman <David.Bateman at motorola.com> wrote:
> 
> For error, warning, and other messages, I think we could use something
> like gettext.  The messages in the sources would remain in English and
> there would be files with translations for other languages.

For the error/warning messages this would be fine, but

> For doc strings, we could do something similar.

doesn't gettext translate word by word... Thus for the error/warning messages
we can tune the messages (as they are short) so that reasonable translations
are possible. But the help messages are long, can include embedded equations,
etc and so will be difficult to get good automatic translations. So I don't
think I'd trust gettext for this part of the task...

I think the preferred solution would be to translate the help messages by
hand as well. The question then becomes where to store these translations
and how to access them at runtime.

> I think it would better to translate the .txi files separately from
> the doc strings, and have them merged together to create a complete
> translation, same as is currently done for the English version.  Then
> with a little bit of support in the Octave sources, you could get
> translated doc strings from the help command as well as a translated
> manual.

I too think it would be better. But the original author stated clearly 
that he didn't have the skills for this task. So in the absence of 
someone wanting to do it the "right way", his only choice is to translate
the manual wholesale....

> I would want the English help text to remain in the source files.
> Translations would go in separate files.

Why make a special cae for English? Special cases, only make the job
harder. I feel that all languages should be treated in the same way 
just for this reason.

For the oct-file and inbuilt functions, its not clear to me whether
the help should be in the source or separately. At runtime, should it
be built as a data block as currently or stored seperately?  If its
stored seperately how do we handle user oct-files? At this moment 
the simplest would be to include all translates in the oct-files
something like

DEFUN_DLD (foo, args, nargout,
  "-* language = en -*-\n\
-* texinfo -*-\n\
@deftypefn {Loadable Function} ... \n\
@end deftypefn\n\
-* language = pl -*-\n\
-* texinfo -*-\n\
@deftypefn {Loadable Function} ... \n\
@end deftypefn\n")

and stored as a data-block as currently. This will increase the memory
use of each loadable function as more translations are included, which
will eventually be a problem if there are many different translations.
But it eases the issue of user included oct-files. Eventually, the
help messages should be stored seperately at run-time for oct-files to
alleviate this issue, while keeping the option of having them as a
data block so that the user included oct-files don't pose a problem.
The easiest way to do this, would be to have a special directive in the
source of the oct-file, something like

DEFUN_DLD (foo, args, nargout, "-*- ignore -*-");

and then go looking for the help in the .m file. As the oct-file takes
precedence over the .m file for excution this .m file could be stored
in the same directory as the oct-file at run time. The help for the
octave (and octave-forge) functions could then be treated as for script
files below.

As for the script files, the help system already skips the Copyright 
block and takes the second comment block, so I see no reason not to
include something like 

## -*- language = en -*-
## -*- texinfo -*-
## @deftypefn ...
##
## @end deftypefn

## -*- language = pl -*-
## -*- texinfo -*-
## @deftypefn ...
##
## @end deftypefn

as well for the translations. This easily addresses the issue of user
included script files as well. As the compiled versions of the script
files cut out the help block, the issue of memory use doesn't arise 
for .m files.

The language to use could then be controlled by a variable
OCTAVE_LANG. If a desired language doesn't have a translation for a
particular function, then the default is to display the first help
message regardless of what language it is in. This allows for
non-english speaking users to have non-english help messages only.

In the absence of the "-*- language = ?? -*-" directive, it will be
assumed that there is only a single help block and it will be displayed
without looking any further...

The last issue is the manual.. Basically this should be handled by 
making a version of DOCSTRINGS for each language, with english linked
in as the default for missing help message translations. That is gendoc
would create separate files for each language like

DOCSTRINGS-en
DOCSTRINGS-pl
ln -s DOCSTRINGS-en DOCSTRINGS

Then there would be seperate versions of the .txi files for each language.
With a seperate build of the documentation for each language...

Thinking about this, I don't think this would be that difficult to
implement, although it is a big task. The help system is then a
seperate problem to the error/warning system. The down-side of the
above suggestion is that it doesn't take into account unicode and so
will be limited to certain languages only...

> | > (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.
> | 
> | DOCSTRINGS files are derived from the source code. So any new functions
> | added, will mean you'll need to update this file as well.
> 
> I see this as the main problem with any effort to translate the manual
> or doc strings.  It will probably require significant effort to keep
> up to date.

Yeah, this is why translating the .texi is an ugly solution. But the only
one available to the original author.. If he goes this route, he'll end
up with a manual that is tied to a particular version of octave and no
online help in Polish at all....

Cheers
David

-- 
David Bateman                                David.Bateman at motorola.com
Motorola CRM                                 +33 1 69 35 25 00 (Ph)
Espace Technologique, Commune de St Aubin    +33 1 69 35 25 01 (Fax)
91193 Gif-Sur-Yvette FRANCE

The information contained in this communication has been classified as: 

[x] General Business Information 
[ ] Motorola Internal Use Only 
[ ] Motorola Confidential Proprietary



More information about the Mma mailing list