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

Some documentation bugs and wishes

Expand Messages
  • Stefan Parviainen
    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
    Message 1 of 6 , Jan 2, 2011
    • 0 Attachment
      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?
      - Old notation for some key codes is still used
      - e.g. in index.txt "<ESC>" is used instead of "<Esc>" in one place
      - It should be easy to grep through the documentation and replace
      old usage with new one
      - gQ is not mentioned at all in index.txt
      - 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.
      - 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.


      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.
      - 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.
      - 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)

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