Loading ...
Sorry, an error occurred while loading the content.

Re: Some documentation bugs and wishes

Expand Messages
  • Stefan Parviainen
    ... 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.
    Message 1 of 6 , Jan 4, 2011
    • 0 Attachment
      On Tue, Jan 4, 2011 at 2:25 PM, Bram Moolenaar <Bram@...> 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
    • James Vega
      ... How many of those people actually use :visual? I wouldn t expect people to know it takes an argument since it s not a common command to use aside for
      Message 2 of 6 , Jan 4, 2011
      • 0 Attachment
        On Tue, Jan 04, 2011 at 03:04:40PM +0200, Stefan Parviainen wrote:
        > On Tue, Jan 4, 2011 at 2:25 PM, Bram Moolenaar <Bram@...> wrote:
        > > 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.

        How many of those people actually use :visual? I wouldn't expect people
        to know it takes an argument since it's not a common command to use
        aside for providing compatibility with vi (in which it didn't accept an
        argument).

        --
        James
        GPG Key: 1024D/61326D40 2003-09-02 James Vega <jamessan@...>
      Your message has been successfully submitted and would be delivered to recipients shortly.