[SIP-devel] XML help files

[Ricardo F. <rf...@if...>]

Hi, Vitor and other SIP developers,

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.

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.

- The LINK command should be used, not ALINK. ALINK does not work.
- 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.

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

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


Best regards,
Ricardo.

--
  Ricardo Fabbri, Cybernetic Vision Research Group, USP, Brazil.
  WEB: cyvision.if.sc.usp.br/~rfabbri   ICQ: 208974212

  "With pain and suddeness is how Real Offsprings are born. But they
  must result from intense pleasure and a long period of development."