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

[David Bateman]

Daprès Boud Roukema <boud at astro.uni.torun.pl> (le 27/05/2003):
> hi again,
> 
> 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.


The point is to translate those untranslated bits means you need to
edit the octave source code to convert the help into Polish... Somehow
I thing this will be a difficult patch to get into the CVS :-)

> 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

Yes...

> 
> and i guess  scripts/DOCSTRINGS    is a script for doing the extraction.
> 
> Is this right?

No. scripts/DOCSTRINGS are the help from the script files in scripts/.
The programs to extract the help info are scripts/mkdoc and src/gendoc

> > 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?

Sort of... The fact is that teh .txi is an internal octave format. The real
texinfo files are the .texi files built by munging the .txi and the help
messages together. So what I suggested is that you take a COPY of the .texi
files from a particular release, that will include all of the help message
and translate these, as you say ignoring the "DO NOT EDIT" message. These
Polish files would then have a life of their own independent from the octave
help files. So it would be upto you to keep it upto date with changes in
octave.

> 
> > 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.

This is probably what you should do from the information you've
given

> 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

Ugly... Especially if you aim is to increase the accesibility of octave..

> 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

Also ugly, as the help message is currently sorted as data block of the
function. So multiple translations of help message will blow out the size
of this data block.

Better to rewrite the help system so that the help is sort else where. This
might mean that it is still in the source code, but only seperated at compile
time though.

> 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.

DOCSTRINGS files are derived from the source code. So any new functions
added, will mean you'll need to update this file as well.

> 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?

Yup, that pretty much how I see it too...

D.
-- 
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