Subdirectories for help files

[Marco]

Hi,

I have plenty of help files in my .vim/doc directory. I'd like to
structure it a little more. Apparently simply placing the files in
subdirectories is not sufficient. The help tags can not be found. Is
there a way to either

∙ add the paths of the subdirectories to the help tags or
∙ create one tag file per directory and tell vim to find those tag
files as well?

I don't know what's the better approach. The :helptags help is very
scarce about this topic.


Marco

[Chris Lott]

On Tue, Nov 13, 2012 at 12:22 PM, Marco <net...@lavabit.com> wrote:
> Hi,
>
> I have plenty of help files in my .vim/doc directory. I'd like to
> structure it a little more. Apparently simply placing the files in
> subdirectories is not sufficient. The help tags can not be found. Is
> there a way to either

Not sure if it's an option, but using a plugin manager like
[Pathogen](https://github.com/tpope/vim-pathogen) or
[Vundle](https://github.com/gmarik/vundle) allows you to keep the help
files in place in that plugin's folder (along with everything else).
Much cleaner, more portable

Just a thought.

c
--
Chris Lott <ch...@chrislott.org>

[Marco]

2012-11-13 Chris Lott:

> Not sure if it's an option, but using a plugin manager like
> [Pathogen](https://github.com/tpope/vim-pathogen) or
> [Vundle](https://github.com/gmarik/vundle) allows you to keep the help
> files in place in that plugin's folder (along with everything else).

I already use Vundle, but I don't see a difference if I create the
help and corresponding tag files in ~/.vim/doc or in the bundle
directory. Files located in subdirectories are not found using
Vundle, either.

~/.vim/bundle/whatever/doc/foo # found
~/.vim/bundle/whatever/doc/tags
~/.vim/bundle/whatever/doc/subir/bar # not found
~/.vim/bundle/whatever/doc/subir/tags

> Much cleaner, more portable

If it only would work. Since the tag files in

~/.vim/bundle/whatever/doc

are being found, it means there is apparently a way to locate tag
file outside of ~/.vim/doc. I need to apply the same logic as
Vundle, just with a different path.


Marco

[Ben Fritz]

On Wednesday, November 14, 2012 3:46:48 AM UTC-6, Marco wrote:
>
> I already use Vundle, but I don't see a difference if I create the
>
> help and corresponding tag files in ~/.vim/doc or in the bundle
>
> directory. Files located in subdirectories are not found using
>
> Vundle, either.
>
>
>
> ~/.vim/bundle/whatever/doc/foo # found
>
> ~/.vim/bundle/whatever/doc/tags
>
> ~/.vim/bundle/whatever/doc/subir/bar # not found
>
> ~/.vim/bundle/whatever/doc/subir/tags
>
>
>
> > Much cleaner, more portable
>
>
>
> If it only would work. Since the tag files in
>
>
>
> ~/.vim/bundle/whatever/doc
>
>
>
> are being found, it means there is apparently a way to locate tag
>
> file outside of ~/.vim/doc. I need to apply the same logic as
>
> Vundle, just with a different path.
>

I'm pretty sure the idea of a bundle directory like ~/.vim/bundle/whatever is that "whatever" is a self-contained, small, single plugin. There should be no reason to have subdirectories inside whatever. The subdirectories are the children of bundle. What am I missing here about your desired outcome?

[Chris Lott]

On Wed, Nov 14, 2012 at 12:46 AM, Marco <net...@lavabit.com> wrote:
> 2012-11-13 Chris Lott:
>
>> Not sure if it's an option, but using a plugin manager like
>> [Pathogen](https://github.com/tpope/vim-pathogen) or
>> [Vundle](https://github.com/gmarik/vundle) allows you to keep the help
>> files in place in that plugin's folder (along with everything else).
>
> I already use Vundle, but I don't see a difference if I create the
> help and corresponding tag files in ~/.vim/doc or in the bundle
> directory. Files located in subdirectories are not found using
> Vundle, either.
>
> ~/.vim/bundle/whatever/doc/foo # found
> ~/.vim/bundle/whatever/doc/tags
> ~/.vim/bundle/whatever/doc/subir/bar # not found
> ~/.vim/bundle/whatever/doc/subir/tags

My point is that, with the plugins each in their own directory, there
is no need to use subdirs for the docs. That makes sense when trying
to keep a single, central doc directory clean, but I don't understand
what you are trying to achieve here.

> are being found, it means there is apparently a way to locate tag
> file outside of ~/.vim/doc. I need to apply the same logic as
> Vundle, just with a different path.

Your original question didn't really make this clear...it sounded like
you wanted subdirs for your collection of doc files. You could look
inside the Vundle plugin and see what its equivalent of :Helptags (I
use Pathogen) does or create a pseudo-plugin in the bundle directory
for each of your tag files.

[Marco]

2012-11-14 Ben Fritz:

> I'm pretty sure the idea of a bundle directory like
> ~/.vim/bundle/whatever is that "whatever" is a self-contained,
> small, single plugin. There should be no reason to have
> subdirectories inside whatever.

I will describe my use case. I have several custom help files in
~/vim/doc, which contain code snippets. I don't want the text to be
cluttered with code snippets, so I move them to individual files.
That means a help file comprises the main help file and the
snippets.

doc/foo.txt
doc/foo-snip-a.txt
doc/foo-snip-b.txt
doc/foo-snip-c.txt

doc/bar.txt
doc/bar-snip-a.txt
doc/bar-snip-b.txt
doc/bar-snip-c.txt

This clutters my doc directory with all the snippets, so I thought I
could place them into subdirectories as follows.

doc/foo.txt
doc/foo/snip-a.txt
doc/foo/snip-b.txt
doc/foo/snip-c.txt

doc/bar.txt
doc/bar/snip-a.txt
doc/bar/snip-b.txt
doc/bar/snip-c.txt

The files are not under version control and they aren't plugins. I
hope my intentions are more clear now.


Marco

[Ben Fritz]

So just pretend they are plugins and put them in their own bundle/whatever/doc directory.

[Charles Campbell]

Marco wrote:
> Hi,
>
> I have plenty of help files in my .vim/doc directory. I'd like to
> structure it a little more. Apparently simply placing the files in
> subdirectories is not sufficient. The help tags can not be found. Is
> there a way to either
>

> * add the paths of the subdirectories to the help tags or
> * create one tag file per directory and tell vim to find those tag

> files as well?
>
> I don't know what's the better approach. The :helptags help is very
> scarce about this topic.
>

There's a new patch out that allows subdirectories in help. Actually,
its not a limitation of the help or tags, but rather of the :helptags
command.
Admittedly experimental. Probably won't work with vms (although I don't
think it'll do anything adverse with vms).

The patch is at http://www.drchip.org/astronaut/vim/index.html#HELPTAGS .

Regards,
C Campbell

[Charles Campbell]

Bram has accepted my patch into vim (7.3.734). So, enjoy!

Regards,
Chip Campbell

[Marco]

2012-11-19 Charles Campbell:

Hi Charles

> There's a new patch out that allows subdirectories in help. Actually,
> its not a limitation of the help or tags, but rather of the :helptags
> command.

I'm sorry to get back so late on this. I just compiled my new vim
and it seems to work fine.

> Admittedly experimental.

I did a few tests and it seems to work.

> The patch is at http://www.drchip.org/astronaut/vim/index.html#HELPTAGS .

Thanks a lot for looking into this and taking the time to write a
patch that solves my issue.


Marco