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

Re: Some documentation bugs and wishes

Expand Messages
  • Ben Fritz
    ... to :visual (which I just learned also takes a file argument) Additionally, |Ex mode| should be |Ex-mode| to make it a valid link in :help :view ... This is
    Message 1 of 6 , Jan 3, 2011
      On Jan 2, 2:41 pm, Stefan Parviainen <pa...@...> wrote:
      > Hi,
      >
      > I've run into a few bugs in the Vim documentation, most in index.txt
      > because that is really the only place I've looked.
      >
      > - :view does not mention that it exits Ex mode in index.txt
      >   - This is mentioned in editing.txt but not in index.txt
      >   - Can someone explain why this is? Shouldn't it be like ":edit" but
      > read-only?

      :view should not be compared to :edit, it should be compared
      to :visual (which I just learned also takes a file argument)

      Additionally, |Ex mode| should be |Ex-mode| to make it a valid link
      in :help :view

      > - Ex commands do not indicate arguments
      >   - It would be nice to know which commands expect arguments
      > (e.g. :s, :edit) and which don't (e.g. :quit)
      > - Ex commands do not indicate if they support ranges
      >   - It would be nice to know which commands can take ranges (e.g. :s)
      > and which don't (e.g. :edit)
      >

      This is true in index.txt however the command name is a link to the
      main help topic for each command, which DOES indicate arguments, etc.
      I would rather have index.txt stay really short and simple, for use as
      an index, not as a command reference.

      --
      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
    • Stefan Parviainen
      ... Yes, this is true. However, it seems pretty handy to get an overview of all the commands in one place. As you yourself said, you had no idea that :visual
      Message 2 of 6 , Jan 3, 2011
        On Jan 3, 5:36 pm, Ben Fritz <fritzophre...@...> wrote:
        >> - Ex commands do not indicate arguments
        >> - It would be nice to know which commands expect arguments
        >> (e.g. :s, :edit) and which don't (e.g. :quit)
        >> - Ex commands do not indicate if they support ranges
        >> - It would be nice to know which commands can take ranges (e.g. :s)
        >> and which don't (e.g. :edit)
        > This is true in index.txt however the command name is a link to the
        > main help topic for each command, which DOES indicate arguments, etc.
        > I would rather have index.txt stay really short and simple, for use as
        > an index, not as a command reference.

        Yes, this is true. However, it seems pretty handy to get an overview
        of all the commands in one place. As you yourself said, you had no
        idea that :visual takes an argument, probably because you have never
        thought of looking at the main topic for that command (and why would
        you?). Indicating that it _does_ take an argument might lead you to
        check the main documentation. I think adding a "Notes" column with 1 =
        Takes arguments, 2 = supports range would make features much more
        discoverable without making index.txt more complex. As a bonus:
        >> The above changes would make it easier to parse the documentation
        >> automatically and check whether a given command is valid without
        >> having to actually enter it in Vim.

        --
        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
      • Bram Moolenaar
        ... Index.txt omits many details, that s intentional. :view is an old Vi command, it works like it works ni Vi. ... Fixed. ... It s easy to make a mistake
        Message 3 of 6 , Jan 4, 2011
          Stefan Parviainen wrote:

          > I've run into a few bugs in the Vim documentation, most in index.txt
          > because that is really the only place I've looked.
          >
          > - :view does not mention that it exits Ex mode in index.txt
          > - This is mentioned in editing.txt but not in index.txt
          > - Can someone explain why this is? Shouldn't it be like ":edit" but
          > read-only?

          Index.txt omits many details, that's intentional. :view is an old Vi
          command, it works like it works ni Vi.

          > - Old notation for some key codes is still used
          > - e.g. in index.txt "<ESC>" is used instead of "<Esc>" in one place

          Fixed.

          > - It should be easy to grep through the documentation and replace
          > old usage with new one

          It's easy to make a mistake that way. Grepping is OK, but replacement
          can only be done after verifying it's the right thing to do.

          > - gQ is not mentioned at all in index.txt

          I'll add it.

          > - In index.txt the command "@" says "@{a-z}" but plenty of other
          > register names are valid and the main documentation of this command in
          > repeat.txt says "@{0-9a-z".=*}" which seems more correct.

          index.txt omits many details.

          > - The columns in index.txt are not properly aligned. There are several
          > instances where one column contains data that is too long and it runs
          > into the next column. Making the columns wider would solve this issue.

          It has to stay under 80 columns. It's OK for normal reading.

          I do have a problem with the aligning now that we conceal the ||. Not
          easy to fix.

          > Some issues which are more wishes then bugs:
          > - Some columns in index.txt are separated by a single space. This
          > makes it difficult to parse the column data since it is hard to say
          > where one column ends and one begins.

          The text is not written to be parsed but to be read by a human.

          > - It seems to me that things enclosed in {} are often regular
          > expression character class-like, except with {} instead of [].
          > |quote| "{a-zA-Z0-9.%#:-"}
          > Changing {} to [] does result in a valid regular expression character
          > class in Vim's dialect, but it's not valid in some other
          > implementations since :-" is interpreted as a character range, which
          > is invalid. Moving the single dash which does not represent a range to
          > be the last character fixes the issue.

          These things are not regular expressions.

          > - Ex commands do not indicate arguments
          > - It would be nice to know which commands expect arguments
          > (e.g. :s, :edit) and which don't (e.g. :quit)

          Follow the tag. This short overview becomes less readable when adding
          the arguments.

          > - Ex commands do not indicate if they support ranges
          > - It would be nice to know which commands can take ranges (e.g. :s)
          > and which don't (e.g. :edit)

          Same answer.

          > The above changes would make it easier to parse the documentation
          > automatically and check whether a given command is valid without
          > having to actually enter it in Vim.

          This documentation was not intended to be parsed and going that way
          would make it less readable for humans.

          --
          If bankers can count, how come they have eight windows and
          only four tellers?

          /// Bram Moolenaar -- Bram@... -- http://www.Moolenaar.net \\\
          /// sponsor Vim, vote for features -- http://www.Vim.org/sponsor/ \\\
          \\\ an exciting new programming language -- http://www.Zimbu.org ///
          \\\ help me help AIDS victims -- http://ICCF-Holland.org ///

          --
          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
        • 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 4 of 6 , Jan 4, 2011
            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 5 of 6 , Jan 4, 2011
              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.