Re: [SIP-devel] XML help files

[Vitor V. A. S. <vi...@cn...>]

> Hi, Vitor and other SIP developers,

	Hello people,

> I'm finished with an initial build and installation framework for the
> new XML help files.  A development version with XML help files will be
> announced just right after this email. It would be good if somebody
> could test this version on a unix box.

	Ok.

> I didn't have an easy time with XML help, because there are many
> details that Scilab is still not getting right. Some remarks about this:
> 
> - The main error is that some tags are ignored by xmltohtml, or,
> worst, aren't even available in the Scilab help DTD.. I'm now trying to
> solve this, please send me any suggestions.  The ignored tags are
>         REMARKS (present in DTD but ignored by xmltohtml)
>         BUGS AND SHORTCOMINGS
>         AVAILABILITY
>         KNOWN PROBLEMS
>         FILE FORMATS
>         ARGV FILES
>         IMAGE SEGMENTATION
> Without these tags we can't even switch to XML definitely, so this is
> a relatively serious problem.

	Yes, I think it's a seriously problem. My first ideia when I faced this
problem was modify the man pages to "acommodate" the missing
instructions under the functional tags. An example is the mogrify
function, probabily one of the most powerfull and very dependent of tags
with problem.
	To answer your question, I really don't see another solution.

> - The LINK command should be used, not ALINK. ALINK does not work.

	Thank you. I didn't checked it correctly.

> - Vitor, did you check out the Scilab "formatman" command? It
> translates old .man help pages into xml, just as your script does,
> but I don't know if it works. Anyway, this is not of much use now,
> since you already translated them.

	I only took I look, but I thank that would be easist to work to put the
xml tags and not the .man format. The lack of information to generate
the .man tags is even worst to generate xml tags.

> - In the EXAMPLE section, we don't need to escape invalid characters,
> I guess. CDATA is not parsed by XML.

	I'm not sure about that. The only problem I had was with the ">" and
"<" caracters, but concerning to the perl script.

> - In SEE_ALSO, comments to links are ignored. For instance:
> 
> <SEE_ALSO_ITEM> <LINK>mogrify</LINK>(-segment option) </SEE_ALSO_ITEM>
> 
> The "(-segment option)" string is plainly ignored by xmltohtml, even
> though the DTD file allows #PCDATA to be part of SEE_ALSO_ITEM.
> 
> Scilab's TCL/TK browser also has some limitations:
>    - contents page has undesirable blank lines, because the browser
>    is not displaying <dd> tags nicely
>    - there are some strange vertical bars around examples

	Yes, I've noted this bars and really don't know waht they're doing there.

> Anybody is welcome to comment and help us on those issues,
> specially those with XML/DTD knowledge.
> 
> 
> Best regards,
> Ricardo.

	Ricardo, I'm available. What do you think about "change" the files the
not behave properly with the crazy dtd? Would be nice hear the SCILAB
developers opinion.
	Wish to help you in any decicision.
	Best regards and keep in touch,

	Vitor Vasconcelos
	M.Sc Student COPPE/UFRJ
	Computer Graphics and Image Processing Group
	www.lcg.ufrj.br