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

[Benji F. <be...@me...>]

      I have a few questions today.

1. I have been thinking about how to translate DocBook tags into *tags* 
(hyperlinks) for vim help files.  Let's look at an example:

===from tex-refs.xml===
	  <section id="bslash-addtocounter">
	    <title id="bslash-addtocounter-title">\addtocounter</title>
	    <indexterm><primary>\addtocounter</primary></indexterm>

	    <para><literal>\addtocounter{counter}{value}</literal>
	    </para>
	    <para>The <literal>\addtocounter</literal> command increments
	      the <literal>counter</literal> by the
	      amount specified by the <literal>value</literal> argument.
	      The <literal>value</literal> argument can be negative.
	    </para>

	  </section>
========================

===from tex-refs.html===
<div class="section" lang="en">
<div class="titlepage">
<div>
<div>
<h6 class="title"><a name="bslash-addtocounter"></a>1.3.2.1.1
\addtocounter</h6></div></div></div>
<a class="indexterm" name="d0e264"></a>
<p><tt class="literal">\addtocounter{counter}{value}</tt></p>
<p>The <tt class="literal">\addtocounter</tt> command increments
the <tt class="literal">counter</tt> by the amount specified by the
<tt class="literal">value</tt> argument. The <tt class=
"literal">value</tt> argument can be negative.</p></div>
=========================

===from latexhelp.txt===
\addtocounter{counter}{value}			*\addtocounter*
		Increments the {counter} by the amount specified by the
		{value} argument. The {value} argument can be negative.

========================

      It looks to me as if the HTML <a name="bslash-addtocounter"></a> 
is generated from the XML <section id="bslash-addtocounter">.  Is this 
right?  If so, I think we should plan to generate the *\addtocounter* 
from the same element.

2. I think the main reason to prefer Python over XSL is that we need 
plain text with the correct indentation and line breaks.  Am I missing 
something?  Perhaps it would be easier to use a two-step process: 
first, an XSL style sheet that does most of the processing, prducing 
something like this:

===from latexhelp.xml===
\addtocounter{counter}{value}			*\addtocounter*
<block indent=2 tw=80>
Increments the {counter} by the amount specified by the {value} 
argument. The {value} argument can be negative.
</block>

========================

Then a simple Python or vim script could do the rest of the work.  Does 
this sound feasible?

3. If we want a customized format for vim documentation, we could make 
up our own simple DTD and then use XSL to convert this to DocBook.  Is 
this as easy as I make it sound?  Or would it be simpler to use 
attributes in standard DocBook tags?  Srinath proposed

===from options.xml===
<option>
     <optionName>statusline</optionName>
     <optionNameAlias>stl</optionNameAlias>
     <optionType>string</optionType>
     <optionDefault>empty</optionDefault>
     <optionScope>global</optionScope>
     <notInVi/>
     <notInVi>not available when compiled with the <tag>+statusline</tag>
         feature</notInVi>
     <optionDescription>
         When nonempty, this option determines the content of the status 
line.
         Also see <featureTag>status-line</featureTag>
     </optionDescription>
</option>
======================

A variant would be to use attributes:

===from options.xml===
<option name="statusline" alias="stl" type="string" default="empty" 
scope="global">
     <compatibility>not in vi
     </compatibility>
     <compatibility>not available when compiled without the
	<tag>+statusline</tag> feature
     </compatibility>
     <optionDescription>
         When nonempty, this option determines the content of the status
	line.  Also see <featureTag>status-line</featureTag>
     </optionDescription>
</option>
=======================

Is there enough flexibility in DocBook (with attributes and PI's) to so 
something equivalent, or does the custom format, converted to DocBook, 
sound like a good idea?

4. I spent some time trying to set up my system (Red Hat, not Debian) to 
handle the tex-refs conversions.  I adjusted the paths in Makefile.cfg 
and downloaded Saxon from sourceforge.  I think my problem is that I do 
not know what to do to install Saxon.  I copied saxon.jar to 
/usr/share/java but I get this error message:

[benji@localhost tex-refs-0.2.2]$ make tex-refs.html
java -classpath /usr/share/java/saxon.jar com.icl.saxon.StyleSheet 
tex-refs.xml
tex-refs.xsl > tex-refs-saxon.html
Exception in thread "main" java.lang.VerifyError: verification failed at 
PC 65 in com.icl.saxon.style.XSLTemplate:preprocess(()V): incompatible 
type on stack
    at 0x4028115f: java.lang.Throwable.Throwable(java.lang.String) 
(/usr/lib/libgcj.so.3)

Can someone tell me what else I should do?

					--Benji