help.vim's syntax

[Mathieu Roux]

Hi everybody,

I have understood that for vim's help, the syntax file used is help.vim
(in the directory /usr/share/vim/vim80/syntax).

I can use it with:
:so help.vim
(if it is in the same directory of the file i open)

But i still don't understand why, when i open one file in
/usr/share/vim/vim80/doc
EVEN A NEW FILE
it automatically uses the syntax of help.vim, whereas i do nothing...
Maybe someone can explain me.

Best regards,
Mathieu Roux

[Gary Johnson]

This is explained in

:help syntax

In short, when you enable syntax highlighting by executing

:syntax enable

in your vimrc, you source $VIMRUNTIME/filetype.vim, which contains:

" Vim help file
au BufNewFile,BufRead $VIMRUNTIME/doc/*.txt setf help

Whenever you open a file matching that pattern, Vim sets the
'filetype' to "help" and (with the aid of a few other scripts)
sources $VIMRUNTIME/syntax/help.vim.


You wrote above that you opened a new file in
/usr/share/vim/vim80/doc. Do not create new syntax files in that
directory. Do not create new files or modify any files anywhere
under /usr/share/vim/vim80. Those directories are for files
included with the Vim package. Any files in those directories may
be overwritten by an update to the Vim package and will not be
accessed when you upgrade to a version later than 8.0.

Instead, put any files you create for you own use under ~/.vim or
any that you want to share with other users under
/usr/share/vim/vimfiles. Then they will be safe from any changes to
your distribution's Vim package and will continue to be used even if
you build Vim yourself.

Regards,
Gary

[Mathieu Roux]

> --

I think i don't understand...

In fact, i don't want to modify /usr/share/vim/vim80/. i just tried,
and i see that a new file automatically uses help.vim syntax.

In my ~/.vimrc, i don't see where i source filetype.vim. Should i have
a lign so filetype.vim?

/usr/share/vim/vim80/ has a subdirectory called syntax, but it contains
many .vim files with many syntaxes. I don't understand why file in doc
directory uses help.vim.


As for me, in my directory, say ~/mathieu, i want that every .txt file
that i create uses help.vim syntax.
I copied help.vim file in ~/mathieu and in ~/mathieu/syntax. I tried
:syntax on
But it does not work.

The only solution for me is to do :so help.vim
But when i close my .txt file and open it again, i have to do :so
help.vim again.

I am sorry, i am quite a beginner in vim, but i really don't understand
your explanation.

Best regards,
Mathieu

[Gary Johnson]

I inferred too much from your comment in your earlier post about
opening a new file in /usr/share/vim/vim80/doc. Newcomers to Vim
often do not understand the problems with modifying or adding files
under $VIMRUNTIME (in your case, /user/share/vim/vim80) and I wanted
to help you avoid those problems.

> In my ~/.vimrc, i don't see where i source filetype.vim. Should i have
> a lign so filetype.vim?

No, you don't need a line in your ~/.vimrc to source filetype.vim.
Vim automatically sources filetype.vim when it executes the ":syntax
on" or ":filetype on" commands. Those commands are usually in the
system vimrc provided by your Linux distribution's vim package.

> /usr/share/vim/vim80/ has a subdirectory called syntax, but it contains
> many .vim files with many syntaxes. I don't understand why file in doc
> directory uses help.vim.

The files in /usr/share/vim/vim80/doc use help.vim because of the
line I quoted earlier from $VIMRUNTIME/filetype.vim:

au BufNewFile,BufRead $VIMRUNTIME/doc/*.txt setf help

That is an autocommand that sets the 'filetype' to help for every
file opened whose path name matches the pattern

$VIMRUNTIME/doc/*.txt

Vim also uses modelines in help files to set the filetype to "help".
Look at the last line of any file in $VIMRUNTIME/doc. It will look
like this example from $VIMRUNTIME/doc/workshop.txt:

vim:tw=78:ts=8:noet:ft=help:norl:

If you put that line as the last line of your files, their filetype
will be set to "help" when they are opened.

> As for me, in my directory, say ~/mathieu, i want that every .txt file
> that i create uses help.vim syntax.

The easiest way to do that is to put that modeline at the bottom of
every .txt file in that directory. Another way to do that is to
create an autocommand to set the filetype to "help" for any file
whose path name matches the pattern

~/mathieu/*.txt

If you want to use that second method, read

:help new-filetype

I know that you're not adding a new filetype, you're adding a new
pattern to detect an existing filetype, but in this case, the
solution is the same.

> I copied help.vim file in ~/mathieu and in ~/mathieu/syntax. I tried
> :syntax on
> But it does not work.
>
> The only solution for me is to do :so help.vim
> But when i close my .txt file and open it again, i have to do :so
> help.vim again.
>
> I am sorry, i am quite a beginner in vim, but i really don't understand
> your explanation.

I hope the explanation above is better.

Regards,
Gary

[Mathieu Roux]

yes, it is, thanks for all!

in fact, i think the ligns

au BufNewFile,BufRead *.txt
\ if getline('$') !~ 'vim:.*ft=help'
\| setf text
\| endif

in filetype.vim are also important.


But the modeline
vim: tw=0;ft=help:
at the end of my txt file is not enough.

I had to modify my .vimrc too with:

au BufRead /home/m/*.txt setf help
au BufRead /home/m/*.txt set tw=0

and now everything is ok.

Best regards,
Mathieu Roux

[Gary Johnson]

You're welcome.

> in fact, i think the ligns
>
> au BufNewFile,BufRead *.txt
> \ if getline('$') !~ 'vim:.*ft=help'
> \| setf text
> \| endif
>
> in filetype.vim are also important.
>
>
> But the modeline
> vim: tw=0;ft=help:
> at the end of my txt file is not enough.

The separator between settings in that style of modeline is a colon
(':'), not a semicolon (';'). If you really did put a semicolon
between the '0' and the 'f', then that modeline failed because the
syntax was incorrect. If the modeline you actually used had a colon
at that point, i.e.,

vim: tw=0:ft=help:

then the modeline should have worked fine. You may need to check
that 'modeline' is set. That is,

:verbose set modeline?

should print

modeline

> I had to modify my .vimrc too with:
>
> au BufRead /home/m/*.txt setf help
> au BufRead /home/m/*.txt set tw=0
>
> and now everything is ok.

I'm glad to hear that.

Regards,
Gary

[Mathieu Roux]

> --


Even with a : instead of ; it fails.

When i do
set modeline?
i have nomodeline.
I can do
set modeline,
but after, when i start vi again, it is again nomodeline...

[Kennedy, Marcus A.]

Add in the "set modeline" in your .vimrc file.

Best of luck,
Andy

[Gary Johnson]

How and to what value modeline is set depends on a number of
factors, including those discussed in ":help 'modeline'" and whether
your Linux distribution has chosen to disable it in the system
vimrc.

I guess it doesn't really matter how, where or why nomodeline was
set; if you want modeline set, you'll have to set it in your vimrc.
Or, you can not worry about the modeline for your files and just set
the filetype and textwidth as you have.

Regards,
Gary