[Vim-latex-devel] Re: tex-refs project and xml to vim-help conversion

[Peter K. <pma...@ka...>]

Hi Benji and Srinath,

I'll answer your two e-mails in one:

> I downloaded 0.2.1 of the tex-refs xml source. It looks like you are
> using the DocBook DTD.

Yes.

> But I am quite unclear about how exactly they process the xml source to
> generate the various formats. It looks like they would use the docbook
> xsl stylesheets available at
> 
> http://docbook.sourceforge.net/projects/xsl/

I'm not sure about that. Michael can answer that.

> Since vim-help is plain text, it will be in general hard to create
> stylesheets for it, because we will have to do all the rendering
> ourselves. 

I hope that it won't be that hard, because the stylesheet for the plain
ascii text output could be used as a starting point.

> Therefore, it is of importance to know how many elements of
> the docbook DTD definition the tex-refs project uses. Each new element
> used will be more work.

As far as I've understand the number of elements won't add too much work,
because many can be handled the same way to create a simple ascii output.

I'm more worried if it's hard to create a stylesheet which creates an
output as half as nice as the very good (in terms of ease of reading)
formatted Vim help files. :-)

> For a simple vim help file itself, we need not more than a couple of
> elements:
> 
> 1. table
> 2. option
> 3. tag
> 4. para
> 
> and maybe a few more.

I'm not sure which option and tag you refer to. You don't mean the help
tags which are generated, do you?

>       A while ago, you wrote to the vim-latex group, asking for a 
> volunteer to work on an XML-to-vim-help converter.

I've forwarded your e-mail to Michael (at the tex-refs mailing list). As
I've written he's pretty busy these days, but I hope he can find some time
to give us a few pointers.

If you don't mind it would be great to subscribe to the tex-refs mailing
list, so it's easier to reach everyone "at once". I personally had started
to improve upon the LaTeX reference which Mikolaij prepared to the Vim help
format. I myself have no XML experience. I've started to learn about
XML/XSL and so on, so that I can better contribute to the project.

Have you already taken a look into the readme files of the source file from
tex-refs? Some questions are answered there already. But I myself still
need to see/learn which tags are used in the XML source and to think about
how they should be translated into the Vim help format.

I guess Michael is right and it's easier to create an XSLT transformation
instead of writing a Vim macro (awk or whatever script) to do all the
formatting, but maybe I'm wrong -- especially considering that you both
have experience to write vim macros, but not with XSLT.

The next best bet would be to use the text output format and reformat that
to the Vim help format. That's not as nice as doing a direct translation,
but might be a much easier solution -- more a (I hope so) quick hack to
have the information at least inside vim so that the help tags file can be
generated.

What do you think about those two options? Which way do you think is the
best way to go? Are there others who are interested in an XML to Vim help
converter (besides tex-refs)? As XML is gaining more ground each day it
might be useful in the future for others too?

Thanks for your efforts to help us to get the tex-references accesible
direct inside Vim :-)

Regards
Peter