Re: [Vim-latex-devel] Re: Whats the best way to write vim documentation?

[Srinath A. <sr...@fa...>]

On Sat, 18 Jan 2003, Luc Hermitte wrote:

> xml is not complicated at all.  There exists several interresting
> tools that manipulate xml files under windows platform.  For instance,
> XT can parse a xml data file and apply an xslt file on it to convert
> the data into any desired format: xsl:fo (used to produced pdf), html,
> latex, text, etc ; or even vim help file.  It you are interrested, I
> can search through my bookmarks the links I got.
>

I am very interested... I didn't know much about xslt for instance. I
was searching around on google today for xml and all I managed to get so
far is a very very good introduction and no solid examples...

I did in fact search for xslt too and came across this:

http://www.w3.org/TR/xslt

but I was just overwhelmed by the documentation... The problem I am
facing is that I am completeley totally new to this, so I don't even
know whats a good place to spend time at. For instance, should I spend
time learning the xml.minidom package of python and write a custom
xml->vimhelp converter (I don't have time for this right now...), or
should I learn xslt and write a xslt stylesheet (am I using the right
terminology?)

Also I would like to know for instance how much time I would have to
spend writing a style sheet for xml-vimhelp. If it is a big enough
project, it might be a good idea to float a project for it. I know quite
a few people would benefit from such a tool...

Another question is how powerful something like xt is. Will it be able
to generate vim help files which look somewhat like the present
latex-suite.txt? Generating a vim help file is going to be tougher than
generating an html file because in html we do not bother with paragraph
width, indented paragraphs etc.

As a concrete example, will something like:

-----------------------------%<-----------------------------
<option>
<name>IMAP_PlaceHolderStart</name>
<name>IMAP_PlaceHolderEnd</name>
<desc>
These settings affect the display of the starting and ending
placeholder characters
</desc>
</option>
-----------------------------%<-----------------------------

get converted into

--------------------------------%<--------------------------------
                                           *IMAP_PlaceHolderStart*
                                             *IMAP_PlaceHolderEnd*
IMAP_PlaceHolderStart
IMAP_PlaceHolderEnd       These settings affect the display of the
                          starting and ending placeholder settings
--------------------------------%<--------------------------------

Note how the actual text is left indented with leading spaces...
What about generating a table of contentes automatically?

> I use another way to produce html help file from vim help file. It is
> based on awk scripts shipped with vim. It is not so bad.
>
That sounds interesting too... Does that manage hyperlinking and color?
Another problem with the automated vim-html tools I've found so far is
the indiscriminate cross-linking they do. For example, they link the has
in a sentence "This package has the following features" to the
has() function...

Thanks,

Srinath