Re: [SIP-devel] XML help files

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

Hi,

still working on XML help, I've made some progress today, after
learning more about this technology.

First, I'll try to accommodate some inexistent manual sections under
DESCRIPTION_ITEM tags. Other sections will be treated like this:

- we'll use/distribute our own XSL and DTD to translate and define new
tags. I suggest generic SECTION and SUBSECTION tags, and the name of
the section as a sub-tag NAME of these.

- we propose these XSL and DTD to Scilab group, but we continue to
use/maintain our own versions of these. xmltohtml enables us to specify
our own XSL.


On Mon, 15 Mar 2004, Vitor Vasconcelos Araujo Silva wrote:

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

I'm just saying that we could have used formatman to translate our old
man to xml just like you did in PERL, but this doesn't matter anymore.


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

Now I'm sure. Here's an excerpt from http://www.w3schools.com/xml/xml_cdata.asp:
"Everything inside a CDATA section is ignored by the parser.
 If your text contains a lot of "<" or "&" characters - as program
 code often does - the XML element can be defined as a CDATA section."

 So invalid characters in code examples inside CDATA don't need to be escaped.

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

This will certainly be fixed by patching "xmltohtml.sci".

So most problems seems to be solved in theory now,
I'll be implementing the solution tomorrow.
Any comments are welcome.

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