On Tue, Jan 4, 2011 at 2:25 PM, Bram Moolenaar <[email protected]> wrote:
> index.txt omits many details.
IMHO it is strange that the same details are included in some
commands, but not in others. Either it should be included in all
commands or no commands. Anything else is confusing and misleading (at
least to me).
>> |quote| "{a-zA-Z0-9.%#:-"}
> These things are not regular expressions.
OK, fair enough. What, exactly, are they then? Is the syntax explained
somewhere?
> Follow the tag. This short overview becomes less readable when adding
> the arguments.
I've spoken to a few people (real life, IRC and even on this list) and
not a single one new that :visual takes an argument. It would help a
lot with discovery if there was at least a note about this. I'm not
suggesting adding detailed info about the argument, just a note that
tells the reader: "This command takes argument, check out the full
docs for details".
> This documentation was not intended to be parsed and going that way
> would make it less readable for humans.
I don't see how adding notes makes it any less readable. It seems to
work fine in sections 1 and 2.
I guess my main gripe is the inconsistency. Why are notes OK in the
explanations for section 1 and 2 but not later? Why Is the full range
of possible characters following a command mentioned in one place, but
not in another (and instead a misleading value is given). Why do most
commands mention that they exit a mode while some don't?
IMHO consistency is not important just for automatic parsing but also
for human readers. This is, of course, just my humble opinion, and I'm
sure others consider it less important.
--
Stefan Parviainen
--
You received this message from the "vim_dev" 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
