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

[Michael W. <mw...@mi...>]

* Peter Karp <pma...@ka...> [030131 14:34]:

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

We are using DocBook XML V4.2, currently the most actual version.

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

The HTML (chunked and non-chunked) transformation process uses the 
most actual version of the DocBook XSL Stylesheets (V1.60.1 at the
time of this writing), using Saxon as XSLT processor (I'd prefer to
use xsltproc from libxml2 because it would be much faster, but it
is still buggy).

For TXT output we use the HTML non-chunked output and use 'lynx -dump'
to create TXT output. Note: there are no XSL stylesheets to generate
directly TXT output!

RTF is generated using openjade and the DSSSL stylesheets (there are
no XSL stylesheets for RTF output available).

PDF is still experimental, the XSL-FO output is quite good, but the
backends to transform this into high quality PDF are not yet ready.
Currently there is some work undergoing in the ConTeXt community,
which might lead to good PDF in the near future.

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

See the note above: there are _no_ XSL stylesheets to genertate directly
TXT output.

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

IMHO it's _not_ a good idea to restrict the use to a subset of all available
DocBook tags! If a backend cannot handle specific tags it should simply 
copy the contents (all between start and end tag) of the unknown tags 
unchanged to the output file.

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

Maybe you should consider to split the source XML file into separate
files. It can be easier to handle only a part (e.g. Chapter 1, TeX) 
of the complete XML file at the beginning. I could provide a XSL
stylesheets which auomatically extracts a specific section of the
complete source file into a separate file.

Please let me know if you need any further information or help
(as Peter already mentioned I'm quite busy at the moment but will
do my best to assist you in your work).

Michael
-- 
mw...@mi...                              http://www.miwie.org
mw...@mi...