Help with :help !

classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

Help with :help !

Benji Fisher
     You can help!

     This request is aimed at anyone on this list who has received
valuable advice and wants to repay the vim community.  That includes
lurkers!

     Vim 7.0 has now started beta testing.  One thing that
non-developers, even newbies, can help with before the final release is
improving the documentation.

:help design-documented

There are many new features, and sometimes during development the docs
and the code are not kept in sync.  Sometimes a new feature makes old
docs obsolete.  (Search for "there is no way to ...")

     I would love it if a bunch of users each adopted one section of the
docs.  Maybe a whole file, like doc/pattern.txt .  Maybe just part of
such a file, like the section corresponding to

1. Search commands |search-commands|

Test the examples, look for mistakes.  Suggest better wording if things
are unclear, and correct typos.  Suggest new help tags so that others
can find what they need.  Learn more about how vim works, so that you
become a vim guru!

     If something is unclear, and you are not sure how to correct it,
ask for help.

     If you plan to adopt one section of the docs, please mention it on
this thread so that others will focus on different parts of the docs.

     Do not neglect the users' manual:

:help toc

                                        --Benji Fisher

P.S.  Another way to repay the vim community is to post a vim tip when
someone on the list solves a problem for you.  It is OK (IMHO) if you
post something that is not your idea, as long as you give credit.

http://www.vim.org/tips/index.php
Reply | Threaded
Open this post in threaded view
|

Re: Help with :help !

William Pursell
Benji Fisher wrote:

>      You can help!
>
>      This request is aimed at anyone on this list who has received
> valuable advice and wants to repay the vim community.  That includes
> lurkers!
>
>      Vim 7.0 has now started beta testing.  One thing that
> non-developers, even newbies, can help with before the final release is
> improving the documentation.
>
<snip>

After a total of 30 minutes playing with vim7, I decided to read through
the documentation on tabpage.  2 things I noticed:

1)  The introduction begins with: "A tab page holds one or more
windows."  At this point, it is not entirely clear what these words
mean.  It might be nice to have a link from here (possibly on the words
"tab page" and the word "window") to something like the definitions of
the words "screen", "shell", and "window" that appear in the
documentation for design-decisions.  This is perhaps not that
significant, but I think there is potential confusion.

2) he: tabdo  Tabdo is listed in the documentation as not taking a !
argument, while windo does.   I presume windo! {cmd}  will process cmd
on all windows, regardless of any errors, but that's not stated in the
text.  I notice that tabdo! is indeed not legal, and I'm curious to know
why.  It would be handy if you could continue to process other tabs when
an error occurs.  (Is that what the '!' on windo does?)

Also, I'm not sure if this is a result of an improper install (I
downloaded from the cvs, used 'vim -c make' to build, set VIMRUNTIME to
the resultant runtime dir, and executed via "vim -u NONE"), but I no
longer have any history in command mode, and I can't use <CTRL>f to
enter the command window.
Reply | Threaded
Open this post in threaded view
|

Re: Help with :help !

Eric Arnold


--- Bill Pursell <[hidden email]> wrote:

> Benji Fisher wrote:
> >      You can help!
> >
> >      This request is aimed at anyone on this list who has received
> > valuable advice and wants to repay the vim community.  That includes
> > lurkers!
> >
> >      Vim 7.0 has now started beta testing.  One thing that
> > non-developers, even newbies, can help with before the final release is
> > improving the documentation.
> >
> <snip>
>
> After a total of 30 minutes playing with vim7, I decided to read through
> the documentation on tabpage.  2 things I noticed:
>
> 1)  The introduction begins with: "A tab page holds one or more
> windows."  At this point, it is not entirely clear what these words
> mean.  It might be nice to have a link from here (possibly on the words
> "tab page" and the word "window") to something like the definitions of
> the words "screen", "shell", and "window" that appear in the
> documentation for design-decisions.  This is perhaps not that
> significant, but I think there is potential confusion.

:help windows

1. Introduction *windows-intro*

A window is a viewport onto a buffer.  You can use multiple windows on one
buffer, or several windows on different buffers.

A buffer is a file loaded into memory for editing.  The original file remains
unchanged until you write the buffer to the file.



If you haven't figured out   :help window^D   to expand all possible
completions, then you need to staple it into your bag of tricks.  It's on the
first   :help    page, but until you use it some, it's [huge] value isn't
obvious.

I think the help doc.s lead you through the concepts pretty well.  If you don't
have the patience (i.e. me) to go through the doc.s as they are designed, then
it is up to you to handle the fragmented information stream into your brain.

There are also GUI windows, which refer to the whole running instance.  This
makes sense in the context of the X11 or MSwin envs.

A shell doesn't really belong in the same category as the others.  It refers to
the shell (i.e. sh/csh/etc) that Vim uses to start something outside itself.

>[...]
>
> Also, I'm not sure if this is a result of an improper install (I
> downloaded from the cvs, used 'vim -c make' to build, set VIMRUNTIME to
> the resultant runtime dir, and executed via "vim -u NONE"), but I no
> longer have any history in command mode, and I can't use <CTRL>f to
> enter the command window.
>

Umm, that's because you lost the "history" option by using -u NONE, among other
things.  Getting all those options set (probably for ^f also) is non-trivial,
that's why -u NONE is such a pain.




Reply | Threaded
Open this post in threaded view
|

Re: Help with :help !

Eric Arnold
In reply to this post by William Pursell

The Vim7 sections I have had trouble with so far are for the "tabline" and the
new List and Dictionary support.  The examples have errors in them, ranging
from missing "let" commands before setting variables, to more subtle stuff.

It would have been better for the example for a "tabline" function to be a
working template.  I have just written a more detailed script.  I wasn't able
to find a .vim file delivered with the runtime stuff that is responsible for
the default tabline behaviour.  Is it internal, or did I miss something?  It
would be nice to have the default accessible, and perhaps a few alternatives
(like colorschemes, etc.).

The explanations of how failures manifest in the world of lists and dicts
should be extended.  It's pretty easy (for me anyway) to get yourself into a
mess where you are frazzled trying to track down "type mismatch" errors (I
posted about this maddness earlier).  I can't say whether the lists and dicts
will mature, and be completely robust about handling foolish invocations, but a
trouble shooting section would be helpful in any case.



--- Bill Pursell <[hidden email]> wrote:

> Benji Fisher wrote:
> >      You can help!
> >
> >      This request is aimed at anyone on this list who has received
> > valuable advice and wants to repay the vim community.  That includes
> > lurkers!
> >
> >      Vim 7.0 has now started beta testing.  One thing that
> > non-developers, even newbies, can help with before the final release is
> > improving the documentation.
> >
> <snip>
Reply | Threaded
Open this post in threaded view
|

Re: Help with :help !

Bram Moolenaar
In reply to this post by William Pursell

Bill Pursell wrote:

> Benji Fisher wrote:
> >      You can help!
> >
> >      This request is aimed at anyone on this list who has received
> > valuable advice and wants to repay the vim community.  That includes
> > lurkers!
> >
> >      Vim 7.0 has now started beta testing.  One thing that
> > non-developers, even newbies, can help with before the final release is
> > improving the documentation.
> >
> <snip>
>
> After a total of 30 minutes playing with vim7, I decided to read through
> the documentation on tabpage.  2 things I noticed:
>
> 1)  The introduction begins with: "A tab page holds one or more
> windows."  At this point, it is not entirely clear what these words
> mean.  It might be nice to have a link from here (possibly on the words
> "tab page" and the word "window") to something like the definitions of
> the words "screen", "shell", and "window" that appear in the
> documentation for design-decisions.  This is perhaps not that
> significant, but I think there is potential confusion.

If you read the docs out-of-order you will miss some terms.  If you
don't know what a window is you really need to read part of the user
manual first.

> 2) he: tabdo  Tabdo is listed in the documentation as not taking a !
> argument, while windo does.   I presume windo! {cmd}  will process cmd
> on all windows, regardless of any errors, but that's not stated in the
> text.  I notice that tabdo! is indeed not legal, and I'm curious to know
> why.  It would be handy if you could continue to process other tabs when
> an error occurs.  (Is that what the '!' on windo does?)

Actually, :windo doesn't use the ! argument.  It's only for :bufdo,
which may need to close the current buffer, which fails if it was
modified.

There is no way for ":somedo" command to continue past an error, except
putting your commands in a try/catch block.

--
A disclaimer for the disclaimer:
"and before I get a huge amount of complaints , I have no control over the
disclaimer at the end of this mail :-)" (Timothy Aldrich)

 /// Bram Moolenaar -- [hidden email] -- http://www.Moolenaar.net   \\\
///        sponsor Vim, vote for features -- http://www.Vim.org/sponsor/ \\\
\\\        download, build and distribute -- http://www.A-A-P.org        ///
 \\\            help me help AIDS victims -- http://www.ICCF.nl         ///
Reply | Threaded
Open this post in threaded view
|

Re: Help with :help !

William Pursell
Bram Moolenaar wrote:

> Bill Pursell wrote:
>
>
>>Benji Fisher wrote:
>>
>>>     You can help!
>>>
>>>     This request is aimed at anyone on this list who has received
>>>valuable advice and wants to repay the vim community.  That includes
>>>lurkers!
>>>
>>>     Vim 7.0 has now started beta testing.  One thing that
>>>non-developers, even newbies, can help with before the final release is
>>>improving the documentation.
>>>
>>
>><snip>
>>
>>After a total of 30 minutes playing with vim7, I decided to read through
>>the documentation on tabpage.  2 things I noticed:
>>
>>1)  The introduction begins with: "A tab page holds one or more
>>windows."  At this point, it is not entirely clear what these words
>>mean.  It might be nice to have a link from here (possibly on the words
>>"tab page" and the word "window") to something like the definitions of
>>the words "screen", "shell", and "window" that appear in the
>>documentation for design-decisions.  This is perhaps not that
>>significant, but I think there is potential confusion.
>
>
> If you read the docs out-of-order you will miss some terms.  If you
> don't know what a window is you really need to read part of the user
> manual first.
>

I know what the terms mean.  I'm simply trying to point out that it may
be useful to have a back reference at that point of the documentation.

>>2) he: tabdo  Tabdo is listed in the documentation as not taking a !
>>argument, while windo does.   I presume windo! {cmd}  will process cmd
>>on all windows, regardless of any errors, but that's not stated in the
>>text.  I notice that tabdo! is indeed not legal, and I'm curious to know
>>why.  It would be handy if you could continue to process other tabs when
>>an error occurs.  (Is that what the '!' on windo does?)
>
>
> Actually, :windo doesn't use the ! argument.  It's only for :bufdo,
> which may need to close the current buffer, which fails if it was
> modified.

Then I would suggest that the documentation for windo not specify an
optional !.  Either that, or tabdo do should allow it (and ignore it)
the same way windo does.  The documentation and behavior should be
consistent.


Reply | Threaded
Open this post in threaded view
|

Re: Help with :help !

Gary Johnson
In reply to this post by Benji Fisher
On 2006-03-30, Benji Fisher <[hidden email]> wrote:

>      Do not neglect the users' manual:
>
> :help toc

One issue with the :help for Vim-7.0 is that that command doesn't
take you where it used to.  It now takes you to the Reference Manual
table of contents rather than the User Manual table of contents.  
This is going to confuse people who, out of habit, type ":help toc"
to get to the User Manual.  It's also going to confuse people who
have been told by more experienced users on the vim list and on
comp.editors to use ":help toc" to get to the User Manual and
probably have that command written on a crib sheet.  For those
reasons, I would suggest adding just "toc" to the tags for the User
Manual table of contents.

Further, there is an inconsistency between the tags used for the two
tables of contents.  Since ":help toc" takes you to "ref-toc", upon
realizing your mistake, you might think that ":help user-toc" or
":help usr-toc" would take you where you want to go.  Wrong.  The
tag for the User Manual table of contents is "usr_toc.txt" or
"user-manual".

This illustrates the difference between "readability" and
"searchability" or "learnabilty".  Any of those tags looks
reasonable when you at it.  However, seeing one does not give you
reliable cues for finding the others.

Solving that problem properly would require developing a style for
Vim tags that might include rules for constructing abbreviations and
when to  use them (e.g., "usr" vs. "user") and for combining words
with '-' vs. '_' vs. just running the words together.

I'm not sure how far we or Bram want to take that, but one editing
task ought to be checking for the more obvious inconsistencies such
as the toc tags.

Gary

--
Gary Johnson                 | Agilent Technologies
[hidden email]     | Wireless Division
                             | Spokane, Washington, USA