Documenting filetype plugins

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

Documenting filetype plugins

David Fishburn

I currently maintain the ftplugin\sql.vim for the Vim distribution.

It is under going some large changes for Vim7 (which also work with Vim6).

I am trying to figure out where I should document the features it provides.

For example:
1.  Specifies a number of maps to assist with the navigation of SQL files.
- These are all modeled after :help motion.txt, *object-select*
*text-objects*

But some do not map directly, but semantically they are the same.  This is
worth explaining.

2.  matchit.vim support.
- But is also provides a mechanism to extend the existing support via your
vimrc.

3.  set define support.

4.  An the new major change, the ability to change SQL dialects between
Oracle, Sybase, Informix, MySQL, Postgress, ...


Should I create a new docs\sql.txt, or should I extend an existing section
in the docs.  If I am going to write it, I want people to be able to find it
and use it.

Any suggestions from the people that actually read the documentation?

TIA,
Dave

Reply | Threaded
Open this post in threaded view
|

Re: Documenting filetype plugins

Mikołaj Machowski
Dnia czwartek, 15 wrze?nia 2005 17:02, David Fishburn napisa?:

> Should I create a new docs\sql.txt, or should I extend an existing
> section in the docs.  If I am going to write it, I want people to be
> able to find it and use it.
>
> Any suggestions from the people that actually read the documentation?

I think plugin docs should be in one file. The only exception
is splitting between users manual and reference (as in Vim docs).
Of course this is my personal opinion. That also depends on size of
docs.

m.

Reply | Threaded
Open this post in threaded view
|

Re: Documenting filetype plugins

A.J.Mechelynck
In reply to this post by David Fishburn
----- Original Message -----
From: "David Fishburn" <[hidden email]>
To: <[hidden email]>
Sent: Thursday, September 15, 2005 5:02 PM
Subject: Documenting filetype plugins


>
> I currently maintain the ftplugin\sql.vim for the Vim distribution.
>
> It is under going some large changes for Vim7 (which also work with Vim6).
>
> I am trying to figure out where I should document the features it
> provides.
>
> For example:
> 1.  Specifies a number of maps to assist with the navigation of SQL files.
> - These are all modeled after :help motion.txt, *object-select*
> *text-objects*
>
> But some do not map directly, but semantically they are the same.  This is
> worth explaining.
>
> 2.  matchit.vim support.
> - But is also provides a mechanism to extend the existing support via your
> vimrc.
>
> 3.  set define support.
>
> 4.  An the new major change, the ability to change SQL dialects between
> Oracle, Sybase, Informix, MySQL, Postgress, ...
>
>
> Should I create a new docs\sql.txt, or should I extend an existing section
> in the docs.  If I am going to write it, I want people to be able to find
> it
> and use it.
>
> Any suggestions from the people that actually read the documentation?
>
> TIA,
> Dave

If there is enough "specific" documentation to make it worth while, I guess
doc/sql.txt would be OK. (IMO: 10 lines -> add a ? in existing helpfile; 100
lines: make a new one). It may also depend on how your plugin is distributed
(if included in "official" distribution, the help goes under $VIMRUNTIME/doc
[doc, not docs]. If via vim-online scripts section, probably under
$VIM/vimfiles/doc and thus shouldn't be merged with any "official"
helpfile).

You might want to ask Bram's opinion about this.


Best regards,
Tony.


Reply | Threaded
Open this post in threaded view
|

Re: Documenting filetype plugins

Robert Schols
In reply to this post by David Fishburn
David Fishburn wrote:
> Should I create a new docs\sql.txt, or should I extend an existing section
> in the docs.  If I am going to write it, I want people to be able to find it
> and use it.
>
> Any suggestions from the people that actually read the documentation?

The obvious place seems to be under :help ftplugin-docs. There are
already a few there. Add a heading called "sql-plugin".

":help sql" will then find it since there is no other direct match for
it yet (no syntax and indent plugin documentation).
It would be great if you made further help tags with "sybase", "oracle"
etc. in them.

If it's way too long or involved, you could make it a seperate page and
both link it at "ftplugin-docs" and put it under the "Standard plugins"
heading in the help index.
Actually this method would 100% guarantee I know it's there.

Make sure to mention :help sql-plugin in your source! I often look for
instructions at the beginning of a source file.

HTH, Robert
Reply | Threaded
Open this post in threaded view
|

RE: Documenting filetype plugins

David Fishburn
In reply to this post by Mikołaj Machowski
 

> -----Original Message-----
> From: Mikolaj Machowski [mailto:[hidden email]]
> Sent: Thursday, September 15, 2005 2:52 PM
> To: [hidden email]
> Subject: Re: Documenting filetype plugins
>
> Dnia czwartek, 15 września 2005 17:02, David Fishburn napisał:
>
> > Should I create a new docs\sql.txt, or should I extend an existing
> > section in the docs.  If I am going to write it, I want
> people to be
> > able to find it and use it.
> >
> > Any suggestions from the people that actually read the
> documentation?
>
> I think plugin docs should be in one file. The only exception
> is splitting between users manual and reference (as in Vim docs).
> Of course this is my personal opinion. That also depends on
> size of docs.

I just wanted to confirm, I am not talking about plugins (.vim/plugin) here,
I am talking about filetype plugins (.vim/ftplugin).

Does the fact that this ftplugin is included as part of the "official" Vim
runtimes files change where it should be documented?

Dave