ido.el doc fixes

ido.el doc fixes

[Christoph]

Here is a small patch for review fixing some doc strings in ido.el. "ido 
speed-ups" seemed confusing in the context of these functions and I was 
looking for a ido-speed-ups function before I realized that it meant 
really "ido-mode".

Note: If this is accepted, I will try to commit it myself. I have just 
set up a branch for my commits.

Thanks,
Christoph


=== modified file 'lisp/ChangeLog'
--- lisp/ChangeLog	2011-02-28 17:42:03 +0000
+++ lisp/ChangeLog	2011-02-28 18:49:43 +0000
@@ -1,3 +1,8 @@
+2011-02-28  Christoph Scholtes  <cschol2112@googlemail.com>
+
+	* ido.el (ido-everywhere): Doc fix
+	(ido-mode): Doc fix
+
  2011-02-28  Glenn Morris  <rgm@gnu.org>

  	* dired-x.el (dired-guess-shell-alist-default): Use \\', not $.

=== modified file 'lisp/ido.el'
--- lisp/ido.el	2011-01-25 04:08:28 +0000
+++ lisp/ido.el	2011-02-28 18:36:40 +0000
@@ -1472,8 +1472,8 @@
    (add-hook 'choose-completion-string-functions 
'ido-choose-completion-string))

  (define-minor-mode ido-everywhere
-  "Toggle using ido speed-ups everywhere file and directory names are read.
-With ARG, turn ido speed-up on if arg is positive, off otherwise."
+  "Toggle using ido-mode everywhere file and directory names are read.
+With ARG, turn ido-mode on if arg is positive, off otherwise."
    :global t
    :group 'ido
    (when (get 'ido-everywhere 'file)
@@ -1494,8 +1494,8 @@

  ;;;###autoload
  (defun ido-mode (&optional arg)
-  "Toggle ido speed-ups on or off.
-With ARG, turn ido speed-up on if arg is positive, off otherwise.
+  "Toggle ido mode on or off.
+With ARG, turn ido-mode on if arg is positive, off otherwise.
  Turning on ido-mode will remap (via a minor-mode keymap) the default
  keybindings for the `find-file' and `switch-to-buffer' families of
  commands to the ido versions of these functions.

Re: ido.el doc fixes

[Eli Zaretskii]

> Date: Mon, 28 Feb 2011 12:06:53 -0700
> From: Christoph <cschol2112@googlemail.com>
> 
> Here is a small patch for review fixing some doc strings in ido.el. "ido 
> speed-ups" seemed confusing in the context of these functions and I was 
> looking for a ido-speed-ups function before I realized that it meant 
> really "ido-mode".

Thanks.

> +2011-02-28  Christoph Scholtes  <cschol2112@googlemail.com>
> +
> +	* ido.el (ido-everywhere): Doc fix
> +	(ido-mode): Doc fix

You want a period at the end of each sentence here.

Okay with that change.

Re: ido.el doc fixes

[Glenn Morris]

Eli Zaretskii wrote:

>> +2011-02-28  Christoph Scholtes  <cschol2112@googlemail.com>
>> +
>> +	* ido.el (ido-everywhere): Doc fix
>> +	(ido-mode): Doc fix
>
> You want a period at the end of each sentence here.

And might as well condense it to:

   * ido.el (ido-everywhere, ido-mode): Doc fix.

Re: ido.el doc fixes

[Christoph Scholtes]

Glenn Morris <rgm@gnu.org> writes:

> And might as well condense it to:
>
>    * ido.el (ido-everywhere, ido-mode): Doc fix.

I was using `C-x 4 a', but I'll remember that for next time.

Christoph

Re: ido.el doc fixes

[Eli Zaretskii]

> From: Christoph Scholtes <cschol2112@googlemail.com>
> Date: Mon, 28 Feb 2011 13:44:10 -0700
> Cc: emacs-devel@gnu.org
> 
> Glenn Morris <rgm@gnu.org> writes:
> 
> > And might as well condense it to:
> >
> >    * ido.el (ido-everywhere, ido-mode): Doc fix.
> 
> I was using `C-x 4 a', but I'll remember that for next time.

"C-x 4 a" knows how to concatenate several symbols.  You just need to
leave point after the closing parenthesis.  Like so: first C-x 4 a
inserts this:

	* ido.el (ido-everywhere): 
                                   ^
leaving point where I indicated.  Then the next C-x 4 a adds another
symbol:

	* ido.el (ido-everywhere, ido-mode): 
                                             ^
Now you are ready to type "Doc fixes.".

Re: ido.el doc fixes

[Christoph]

On 2/28/2011 2:03 PM, Eli Zaretskii wrote:

> "C-x 4 a" knows how to concatenate several symbols.  You just need to
> leave point after the closing parenthesis.  Like so: first C-x 4 a
> inserts this:
>
> 	* ido.el (ido-everywhere):
>                                     ^
> leaving point where I indicated.  Then the next C-x 4 a adds another
> symbol:
>
> 	* ido.el (ido-everywhere, ido-mode):
>                                               ^
> Now you are ready to type "Doc fixes.".

Nice. Thanks Eli. The manual didn't mention this specific behavior, so I 
added a little section. See patch below.

I also added a reference to `add-log-full-name' in the changelog format 
section. `add-log-mailing-address' was already referenced, but I was 
trying to figure out how Change Log mode knows my name. This information 
was missing.

I don't know what the etiquette is for adding examples like the 
Changelog entry below. The example is made up (copied and modified from 
another example in the format section).

Christoph

=== modified file 'doc/emacs/ChangeLog'
--- doc/emacs/ChangeLog	2011-02-28 01:07:29 +0000
+++ doc/emacs/ChangeLog	2011-02-28 23:17:26 +0000
@@ -1,3 +1,10 @@
+2011-02-28  Christoph Scholtes  <cschol2112@googlemail.com>
+
+	* maintaining.texi (Format of ChangeLog): Add reference to
+	add-log-full-name.
+	(Change Log Commands): Add documentation and example for combining
+	multiple symbols in one change.
+
  2011-02-28  Eli Zaretskii  <eliz@gnu.org>

  	* search.texi (Regexp Search): Move index entries about regexps to the

=== modified file 'doc/emacs/maintaining.texi'
--- doc/emacs/maintaining.texi	2011-02-05 22:30:14 +0000
+++ doc/emacs/maintaining.texi	2011-02-28 23:21:39 +0000
@@ -1486,6 +1486,21 @@
  non-@code{nil}, @kbd{C-x 4 a} adds to any existing item for the file
  rather than starting a new item.

+Multiple changes of the same nature can be combined. First, leave the
+point after the closing parenthesis after the inital @kbd{C-x 4
+a}. Then, any subsequent @kbd{C-x 4 a} adds another symbol to the
+change.
+
+For example:
+@iftex
+@medbreak
+@end iftex
+@smallexample
+1993-05-25  Richard Stallman  <rms@@gnu.org>
+
+        * man.el (man, man-follow): Doc fix.
+@end smallexample
+
  @vindex add-log-always-start-new-record
    If @code{add-log-always-start-new-record} is non-@code{nil},
  @kbd{C-x 4 a} always makes a new entry, even if the last entry
@@ -1535,13 +1550,14 @@
  @node Format of ChangeLog
  @subsection Format of ChangeLog

-  A change log entry starts with a header line that contains the current
-date, your name, and your email address (taken from the variable
-@code{add-log-mailing-address}).  Aside from these header lines, every
-line in the change log starts with a space or a tab.  The bulk of the
-entry consists of @dfn{items}, each of which starts with a line starting
-with whitespace and a star.  Here are two entries, both dated in May
-1993, with two items and one item respectively.
+  A change log entry starts with a header line that contains the
+current date, your name (taken from the variable
+@code{add-log-full-name}), and your email address (taken from the
+variable @code{add-log-mailing-address}).  Aside from these header
+lines, every line in the change log starts with a space or a tab.  The
+bulk of the entry consists of @dfn{items}, each of which starts with a
+line starting with whitespace and a star.  Here are two entries, both
+dated in May 1993, with two items and one item respectively.

  @iftex
  @medbreak

Re: ido.el doc fixes

[Glenn Morris]

Christoph wrote:

> On 2/28/2011 2:03 PM, Eli Zaretskii wrote:
>
>> "C-x 4 a" knows how to concatenate several symbols.  You just need to
>> leave point after the closing parenthesis.

I don't think that is correct. You can move point wherever you like. So
long as you have not entered any text for an entry, the next entry from
the same file will merge with it. (If add-log-always-start-new-record is
nil.)

> I don't know what the etiquette is for adding examples like the
> Changelog entry below.

I don't think an example ChangeLog entry is needed for this behaviour.
It's good to try to keep the manual from expanding too much.

> +Multiple changes of the same nature can be combined.

It's better to use the active voice (see tips.texi). Eg "You can combine
multiple changes of the same nature".

Re: ido.el doc fixes

[Christoph Scholtes]

Glenn Morris <rgm@gnu.org> writes:

> I don't think that is correct. You can move point wherever you like. So
> long as you have not entered any text for an entry, the next entry from
> the same file will merge with it. (If add-log-always-start-new-record is
> nil.)

That looks correct. I modified the patch as below.

> I don't think an example ChangeLog entry is needed for this behaviour.
> It's good to try to keep the manual from expanding too much.

OK. I think with the above corrections it might be clear enough without
example.

> It's better to use the active voice (see tips.texi). Eg "You can combine
> multiple changes of the same nature".

Thanks.

Christoph


=== modified file 'doc/emacs/ChangeLog'
--- doc/emacs/ChangeLog	2011-02-28 01:07:29 +0000
+++ doc/emacs/ChangeLog	2011-02-28 23:17:26 +0000
@@ -1,3 +1,10 @@
+2011-02-28  Christoph Scholtes  <cschol2112@googlemail.com>
+
+	* maintaining.texi (Format of ChangeLog): Add reference to
+	add-log-full-name.
+	(Change Log Commands): Add documentation and example for combining
+	multiple symbols in one change.
+
 2011-02-28  Eli Zaretskii  <eliz@gnu.org>
 
 	* search.texi (Regexp Search): Move index entries about regexps to the

=== modified file 'doc/emacs/maintaining.texi'
--- doc/emacs/maintaining.texi	2011-02-05 22:30:14 +0000
+++ doc/emacs/maintaining.texi	2011-03-01 02:28:44 +0000
@@ -1486,6 +1486,10 @@
 non-@code{nil}, @kbd{C-x 4 a} adds to any existing item for the file
 rather than starting a new item.
 
+You can combine multiple changes of the same nature. If you don't
+enter any text after the initial @kbd{C-x 4 a}, any subsequent
+@kbd{C-x 4 a} adds another symbol to the change.
+
 @vindex add-log-always-start-new-record
   If @code{add-log-always-start-new-record} is non-@code{nil},
 @kbd{C-x 4 a} always makes a new entry, even if the last entry
@@ -1535,13 +1539,14 @@
 @node Format of ChangeLog
 @subsection Format of ChangeLog
 
-  A change log entry starts with a header line that contains the current
-date, your name, and your email address (taken from the variable
-@code{add-log-mailing-address}).  Aside from these header lines, every
-line in the change log starts with a space or a tab.  The bulk of the
-entry consists of @dfn{items}, each of which starts with a line starting
-with whitespace and a star.  Here are two entries, both dated in May
-1993, with two items and one item respectively.
+  A change log entry starts with a header line that contains the
+current date, your name (taken from the variable
+@code{add-log-full-name}), and your email address (taken from the
+variable @code{add-log-mailing-address}).  Aside from these header
+lines, every line in the change log starts with a space or a tab.  The
+bulk of the entry consists of @dfn{items}, each of which starts with a
+line starting with whitespace and a star.  Here are two entries, both
+dated in May 1993, with two items and one item respectively.
 
 @iftex
 @medbreak

Re: ido.el doc fixes

[Eli Zaretskii]

> From: Christoph Scholtes <cschol2112@googlemail.com>
> Cc: Eli Zaretskii <eliz@gnu.org>,  emacs-devel@gnu.org
> Date: Mon, 28 Feb 2011 19:36:17 -0700
> 
> +You can combine multiple changes of the same nature. If you don't
                                                      ^^
Two spaces between sentences, please.

Okay with that change.

Thanks.

Re: ido.el doc fixes

[Christoph Scholtes]

Eli Zaretskii <eliz@gnu.org> writes:

> Two spaces between sentences, please.

Oops...sorry. I am still not used to that.

> Okay with that change.

Thank you. Committed.

Christoph

Re: ido.el doc fixes

[Christoph Scholtes]

Eli Zaretskii <eliz@gnu.org> writes:

> You want a period at the end of each sentence here.

Fixed.

> Okay with that change.

Thanks.

Looks like my first commit was successful. :)

Christoph