Re: Formatting help files

El 28 de mayo de 2010 19:03, Tony Mechelynck <antoine.mechelynck@gmail.com> escribió:

On 28/05/10 12:48, Pablo Giménez wrote:

Hi.
I have some help files along with my scripts and I wanto give them a
better formatting.
So far the text layout is not too  bad, but I am wondering is there is
anyway to make some letter to appear as bold or italic, like when you
write a wiki.
Is this possible with vim help files format????
thanks

--
Un saludo
Best Regards
Pablo Giménez

If these help files are to be used by other Vim users (e.g. because you distribute them with one or more Vim scripts), then you should stick to "standard" help formatting. In that case you cannot make sure that any particular text will be in any _particular_ color, boldness, etc., because any user may have a different "preferred colorscheme", and colorschemes are allowed to set any coloring scheme. But you can make some parts of the text appear in a different color than the rest to any user who has set ":syntax on", by following the same rules as in the help files distributed with Vim, as follows:

Thanks  Tony.
I am already following these rules to format my help files.
But txtfmt plugin is really useful to make a more professional look to it.
So probably I will add this pluging along side with my one, which basically a compilation of plugins and scripts to offer a better help.

* Always put a modeline at the bottom, as Bram does with Vim's helpfiles. Never set a global option in such a modeline, that can have consequences undesired by whoever reads that help.

* Where you define a help tag, put its *help-tag-name* between asterisks. Then after the user runs |:helptags| or |:UseVimball| he will be able to use ":help help-tag-name" to go to it. The name should be distinctive and different from all help tags already used by Vim; ideally it should begin with the name of your plugin.

* To hotlink to an 'option', just put its name between single quotes, Vim is clever enough to highlight that the right way.

* To hotlink to a |help-tag-name| for something other than an option, put it between |bars| (q.v.)

* The words "Note" and "TODO" automagically receive distinctive highlighting.

* See also (e.g. by looking at some of the Vim helpfiles after setting ":syntax off", or by viewing them in some dumb editor such as Notepad) how the Vim help uses some character at the start or end of some lines to produce distintive highlighting. For instance the following have a meaning (I'm not sure I found them all):

       - a special key name expressed either in <> notation as in <PageDown>, or as a Ctrl character as in CTRL-X
       - anything between {braces}, e.g. {lhs} and {rhs}
       - a greater-than sign at the end of the line (maning: here comes a block of ex-commands)
       - a less-than sign as the first nonblank on a line (meaning: the line above was the last one of a block of ex-commands)
       - a line starting in column 1 also implicitly stops any block of ex-commands before it.
       - a tilde at the end of a line (to give this line a different colour, usually for a column heading)


Best regards,
Tony.
--
ARTHUR:  Bloody peasant!
DENNIS:  Oh, what a give away.  Did you hear that, did you hear that, eh?
        That's what I'm on about -- did you see him repressing me, you saw it
        didn't you?
                                 The Quest for the Holy Grail (Monty Python)

--
Un saludo
Best Regards
Pablo Giménez

--
You received this message from the "vim_use" maillist.
Do not top-post! Type your reply below the text you are replying to.
For more information, visit http://www.vim.org/maillist.php