[SIP-devel] SIP help files for Scilab 5

[<ric...@us...>]

Hi, all,

I got a system to build help files for Scilab 5.1 going, it should work in the
CVS version. Having a friendly fork of SIP around that already does this (SIVP)
definitely helped a lot, but we still need volunteers to translate remaining
help files to the new format. That's all that remains for us to have a
completely working
SIP for Scilab 5.1.

We have 65 help files in SIP! I already translated all the docs of functions
that have some overlap with SIVP (10 files), as well as other important ones
from SIP, such as mogrify. It was an interesting idea to do it by hand, since it
taught me the differences between the two toolboxes and got me started in
merging the two.

I tried to translate the remaining help files using an automated tool provided
by the Scilab team - the xmltodocbook toolbox:

http://www.scilab.org/contrib/index_contrib.php?page=displayContribution&fileID=1163

but it didn't work on my computer - Java crashes (gentoo Linux with
sun-jdk-1.6). We had a custom DTD for the 4.x help pages
which might complicate the use of such an automated tool, so I think doing it by
hand is the most likely solution. We can take the opportunity to fix any typos
and learn the new help style. Last time we moved from the old Scilab 2.x to 4.x
help styles, Vitor admirably did most of the work.

Here are my guidelines for doing this. The new help files are in the help/en_US
directory (as opposed to 'man'), and you can start from a copy of the existing
ones to use as a template. My only requirement is that you try to keep the XML
tags in the file well-indented as much as you can, but we should not enforce a
strict style. It is up to you, just keep it fairly clean.

Once you translated a new help file, say man/bwdist.xml to
help/en_US/bwdist.xml, then add the file to the list in help/Makefile.am,
and type "make" inside the help directory. That should rebuild the help files.

Instead of opening scilab all over again to check if the help file formatting
looks good, you can just point your browser to
help/en_US/scilab_en_US_help/index.html and navigate to your function.

Keeping the browser open, all you have to do is refresh it after you make a
change to your xml file and type "make" inside the help folder.

Once all the files are done, I will immediately make a new SIP release, with
plenty of thank you notes to the volunteer(s). So your help would be appreciated
since a new release of SIP is more than needed!

Thanks!
Ricardo