Thread: [Vim-latex-devel] Whats the best way to write vim documentation?
Brought to you by:
srinathava,
tmaas
Menu
▾
▴
vim-latex-devel
|
From: Srinath A. <sr...@fa...> - 2003-01-18 05:11:00
|
Hello,
I have recently decided to revamp the documentation of latex-suite to
make it more comprehensive and easily navigable. I would ideally like to
do the following:
1. Maintain documentation in a single format. This could be one of
vim-help, html, latex, xml or whatever. I have actually never done
xml before, but have heard lots about it... I don't know if there are
any nice xml tools for windows platforms...
2. From this one file, I would like to create the vim-help file and the
html documentation for the web-page.
The only way I know of to maintain a single source of documentation is:
Always edit the vim help file. Use the 2html.vim script to convert to
html and use that in the web-page. I don't like this approach because
the html page generated by this method..., well.. quite frankly sucks.
It is also a hassle to maintain pages which look like:
|ls_1| Basic editing
|ls_1_1| Environments
|ls_1_1| Fonts
|ls_2| Compiling from vim
.
.
.
I would prefer to maintain something like:
\section{Basic Editing}
\label{sec:basicediting}
\subsection{Environments}
.
.
.
I really like the html generated by latex2html but unfortunately I do
not know of anything like latex2vim. Infact that would be ideal...
Ofcourse even if I do get a latex2vim I wouldn't know how to make it
generate links in the html file...
Is there any other better way?
Basically, I am asking the exact same thing Peter Karp asks in this
post:
http://groups.google.com/groups?q=latex+%2Bto+vim+help&hl=en&lr=&ie=UTF-8&selm=79jkluc1tacttnf4lm2osr28fedqvt5o4b%404ax.com&rnum=1
Unfortunately I am working on too many things right now to be also
working on a latex2vim or similar scipt...
Srinath
|
|
From: Luc H. <her...@fr...> - 2003-01-18 23:27:36
|
hello, * On Fri, Jan 17, 2003 at 09:10:56PM -0800, Srinath Avadhanula <sr...@fa...> wrote: > 1. Maintain documentation in a single format. This could be one of > vim-help, html, latex, xml or whatever. I have actually never done > xml before, but have heard lots about it... I don't know if there > are any nice xml tools for windows platforms... 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. > 2. From this one file, I would like to create the vim-help file and the > html documentation for the web-page. > The only way I know of to maintain a single source of documentation is: > > Always edit the vim help file. Use the 2html.vim script to convert to > html and use that in the web-page. 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. > Unfortunately I am working on too many things right now to be also > working on a latex2vim or similar scipt... -- Luc Hermitte http://hermitte.free.fr/vim/ |
|
From: Srinath A. <sr...@fa...> - 2003-01-18 23:50:27
|
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 |
|
From: Benji F. <be...@me...> - 2003-01-19 20:29:24
|
Srinath Avadhanula wrote: > 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: I am willing to look into this. It may take me a couple of weeks before I can get anywhere, though. You may have noticed that I posted to the vim-dev list, in order to get a wider range of experience. So far, the answers are not so encouraging as I had hoped. We can get vim2html and latex2html, but so far there seems to be no mechanism to generate both latex and vim from the same sources. From what I have "heard," it seems that xml/xslt/DocBook is the way to go. I think the xml2vim piece is the only one that needs to be made, and it will help us, the latex documentation project, and others. So I volunteer to do it, with my usual caveat: unless someone else beats me to it. In the mean time, I suggest writing documentation in whatever format seems easiest. If you structure things as consistently as possible, it should not be hard (using the best text editor in the world) to convert to xml. --Benji |
|
From: Srinath A. <sr...@fa...> - 2003-01-19 20:44:49
|
Hey Benji, Thanks for taking this up... On Sun, 19 Jan 2003, Benji Fisher wrote: > I am willing to look into this. It may take me a couple of weeks > before I can get anywhere, though. You may have noticed that I posted > to the vim-dev list, in order to get a wider range of experience. So > far, the answers are not so encouraging as I had hoped. > You might also want to take a look at this: http://www.python.org/doc/current/lib/dom-example.html All the answers which people seem to be giving you on vim-dev seem to have the flavor of using some xslt kind of approach. That will require you to learn yet another thing. From what I can see in the minidom example, if you take a python programming approach (and I know you use and like python), at least for our xml2vim thing, you might end up getting something faster. Just a suggestion... Ofcourse I have about 2 hours of knowledge about xml so far, so maybe (most probably) there is something easier... What about asking this on an xml newsgroup/mailing list? > In the mean time, I suggest writing documentation in whatever > format seems easiest. If you structure things as consistently as > possible, it should not be hard (using the best text editor in the > world) to convert to xml. Okay... I'll write the documentation for now in vim-help format itself and set myself a couple of rigid rules... Hopefully that will make conversion easy... Srinath |
|
From: Luc H. <her...@fr...> - 2003-01-20 06:24:37
|
Hello, * On Sat, Jan 18, 2003 at 03:50:12PM -0800, Srinath Avadhanula <sr...@fa...> wrote: > > 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... The tool XT is available on: http://www.blnz.com/xt For other tools, check the FAQ::Where To Start::Implementations. I like the FAQ available on: http://www.dpawson.co.uk/ It is about XSLT and XSL:fo. It helped me a lot with typical xslt constructs. There is a reference documentation and some nice trivial examples (kind of tutorial) on: http://www.zvon.org/ (and many, many other things) > 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. Hum. That is a very good question. I don't know. I'm also quite a newbye in XML and XSLT. Checking on the FAQ ... yes! It is possible. The solution seems quite complex, but it is possible (cf. FAQ::Plain Text Outputs). Personnally, I don't found XSLT as powerful as TeX is. There are several things it can't do easilly or can't do at all -- that's were the FAQ is interresting. BTW, there is an XML processor programmed in TeX by David Carlisle -- I haven't tested it, but I think it worths mentionning it on this ML. > What about generating a table of contentes automatically? That is possible. Cf the FAQ again, and even the tutorials let us imagine how to do it. ____ > > 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? Hyperlinking yes, but colors no. You should found the result of this convertion somewhere in my web site. Probably on: http://hermitte.free.fr/vim/ressources/ VS_help.html If not in vim/ressources/, it could be into vim/, or vim/ressources/vimfiles/doc/. > 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... It also has this kind of problems. So, I avoid to use too generic tags whenever I can. -- Luc Hermitte http://hermitte.free.fr/vim/ |
|
From: Srinath A. <sr...@fa...> - 2003-01-22 02:34:09
Attachments:
option.py
|
Hey Luc, On Mon, 20 Jan 2003, Luc Hermitte wrote: > The tool XT is available on: http://www.blnz.com/xt > For other tools, check the FAQ::Where To Start::Implementations. > > I like the FAQ available on: http://www.dpawson.co.uk/ > It is about XSLT and XSL:fo. It helped me a lot with typical xslt > constructs. > > There is a reference documentation and some nice trivial examples (kind > of tutorial) on: http://www.zvon.org/ > (and many, many other things) > Thanks for the valuable links... I have been going through them in my spare time... Unfortunately, I am beginning to think that its quite non-trivial to do something like this what we want in xslt... Maybe after more reading, that will change... I am beginning to get more and more inclinded to go the python path and write our own little xml2vim converter... What do you think? This weekend, I was looking at the xml.dom.minidom documentation in python and the helpful example there. I could modify it without too much effort and came up with the attached .py file... Run it as $ python options.py Note that althout it has 113 lines, the code which I actually wrote was about 17 lines. The rest I got from a google search for "paragraph indentation python". Obviously, this was just done on a whim. Do you think this is a good way to proceed? Or should I (or Benji) be better off learning xslt? Thanks, Srinath PS: It converts -----------------------------------%<----------------------------------- <option> <name>Tex_Leader</name> <desc> The mappings in latex-suite are by default prefixed with the back-tick character. For example, `/ inserts \frac{<++>}{<++>}<++> etc. You can change the prefix with the following setting. ',', '/', '`' are preferred values. '' or '\' will lead to a _lot_ of trouble. g:Tex_Leader is also used for visual mode mappings for fonts. </desc> </option> -----------------------------------%<----------------------------------- to ----------------------------------%<---------------------------------- *Tex_Leader* Tex_Leader The mappings in latex-suite are by default prefixed with the back-tick character. For example, `/ inserts \frac{<++>}{<++>}<++> etc. You can change the prefix with the following setting. ',', '/', '`' are preferred values. '' or '\' will lead to a _lot_ of trouble. g:Tex_Leader is also used for visual mode mappings for fonts. ----------------------------------%<---------------------------------- |
|
From: Mikolaj M. <mi...@wp...> - 2003-01-19 23:21:16
|
On Sun, Jan 19, 2003 at 12:44:46PM -0800, Srinath Avadhanula wrote: > Okay... I'll write the documentation for now in vim-help format itself > and set myself a couple of rigid rules... Hopefully that will make > conversion easy... I think it is easier to write some macros in vim/perl/python translating vim-help format into xml/whatever than to translate it from xml and get instantly nice formatting which is very important to readability of vim-help files. Mikolaj |
|
From: Srinath A. <sr...@fa...> - 2003-01-20 04:43:32
|
On Sun, 19 Jan 2003, Mikolaj Machowski wrote: > I think it is easier to write some macros in vim/perl/python translating > vim-help format into xml/whatever than to translate it from xml and get > instantly nice formatting which is very important to readability of > vim-help files. > Actually, I think converting xml to vim help format will be much easier than the other way around... because the syntax of xml is so rigid and there are xml parsers available in python/perl etc. I looked at the xml.dom.minidom module of python briefly and I beleive that a converter shouldn't be too hard to do... But ofcourse, there might be even easier methods... Besides, xml is so much easier to write because it is freeform. I do not have to bother with paragraph indentation etc... Srinath |
|
From: Benji F. <be...@me...> - 2003-01-22 13:43:47
|
Srinath Avadhanula wrote:
>
> PS: It converts
>
> -----------------------------------%<-----------------------------------
> <option>
> <name>Tex_Leader</name>
> <desc>
> The mappings in latex-suite are by default prefixed with the back-tick
> character. For example, `/ inserts \frac{<++>}{<++>}<++> etc.
> You can change the
> prefix with the following setting.
> ',', '/', '`' are preferred values. '' or '\' will lead to a _lot_ of
> trouble.
>
> g:Tex_Leader is also used for visual mode mappings for fonts.
> </desc>
> </option>
> -----------------------------------%<-----------------------------------
>
> to
>
> ----------------------------------%<----------------------------------
> *Tex_Leader*
>
> Tex_Leader
>
> The mappings in latex-suite are by default
> prefixed with the back-tick character. For
> example, `/ inserts \frac{<++>}{<++>}<++> etc. You
> can change the prefix with the following setting.
> ',', '/', '`' are preferred values. '' or '\' will
> lead to a _lot_ of trouble.
>
> g:Tex_Leader is also used for visual mode mappings
> for fonts.
> ----------------------------------%<----------------------------------
That looks pretty good for a first attempt. How about latex and
html output? Unless we want to write custom converters for those, too,
we should figure out what kind of xml tags are already being used, and
work with those. Have you looked at the latex documentation project lately?
I am afraid I cannot help much right now. Remember, the time
frame I gave when I offered to look into this was "a few weeks."
--Benji
|
|
From: Srinath A. <sr...@fa...> - 2003-01-22 17:22:56
|
On Wed, 22 Jan 2003, Benji Fisher wrote: > That looks pretty good for a first attempt. How about latex and > html output? Unless we want to write custom converters for those, too, > we should figure out what kind of xml tags are already being used, and > work with those. Yes... We should definitely use tags which are standard (maybe find out what the tex refs project uses)... Also, as I said, this was just a quick hack around the xml.dom.minidom example. I really didn't spend time learning the right tools and such. On further reading, xslt seems a bit more tractable than before, but unfortunately, I couldn't get the xt tools which Luc recommended to work on my box. (Thats mostly a problem with my java newbie status). As far as converting to html goes, I think we might be able to find xml2html converters on the web... I would think they are pretty ubiquitous. I could find a few with a google search... I dont know about xml2latex... > > Have you looked at the latex documentation project lately? > No. Another thing which should be done. Maybe we should contact Peter Karp... > I am afraid I cannot help much right now. Remember, the time > frame I gave when I offered to look into this was "a few weeks." > Sorry. I didn't mean to hurry you :) Please take your time... But I just wanted to get an opinion of whether this approach is worth pursuing for the long run? Srinath |
×
Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.
Thanks for helping keep SourceForge clean.
X