bug#23016: 25.1; First proof reading of emacs/abbrevs.texi and lispref/abbrevs.texi

bug#23016: 25.1; First proof reading of emacs/abbrevs.texi and lispref/abbrevs.texi

[Steve Byrne]

[-- Attachment #1: Type: text/plain, Size: 6230 bytes --]


My first cut at proofing.  I hope it will be ok that I hand-crafted this email message; M-x report-emacs-bug wanted to use a mail program that isn't present on OS X ;)

$ git diff -p sbb-initial sbb-first-changes
diff --git a/admin/release-process b/admin/release-process
index f378662..72129bf 100644
--- a/admin/release-process
+++ b/admin/release-process
@@ -238,7 +238,7 @@ TUTORIAL.zh

 ** Check the manual.

-abbrevs.texi
+abbrevs.texi 		Steve Byrne
 ack.texi
 anti.texi
 arevert-xtra.texi
@@ -293,7 +293,7 @@ xresources.texi

 ** Check the Lisp manual.

-abbrevs.texi
+abbrevs.texi		Steve Byrne
 anti.texi
 back.texi
 backups.texi
diff --git a/doc/emacs/abbrevs.texi b/doc/emacs/abbrevs.texi
index e0441a1..7fba728 100644
--- a/doc/emacs/abbrevs.texi
+++ b/doc/emacs/abbrevs.texi
@@ -414,7 +414,6 @@ case while searching for expansions (@pxref{Lax Search}).
 @emph{of the dynamic abbrev you are expanding}, by converting the
 expansion to that case pattern.

-@vindex dabbrev-case-fold-search
   The variable @code{dabbrev-case-replace} controls whether to
 preserve the case pattern of the dynamic abbrev.  If it is @code{t},
 the dynamic abbrev's case pattern is preserved in most cases; if it is
@@ -432,12 +431,13 @@ copies the expansion verbatim including its case pattern.

 @vindex dabbrev-abbrev-char-regexp
   The variable @code{dabbrev-abbrev-char-regexp}, if non-@code{nil},
-controls which characters are considered part of a word, for dynamic expansion
-purposes.  The regular expression must match just one character, never
-two or more.  The same regular expression also determines which
-characters are part of an expansion.  The value @code{nil} has a special
-meaning: dynamic abbrevs are made of word characters, but expansions are
-made of word and symbol characters.
+controls which characters are considered part of a word, for dynamic
+expansion purposes.  The regular expression must match just one
+character, never two or more.  The same regular expression also
+determines which characters are part of an expansion.  The value
+@code{nil} (the default value) has a special meaning: dynamic abbrevs
+are made of word characters, but expansions are made of word and
+symbol characters.

 @vindex dabbrev-abbrev-skip-leading-regexp
   In shell scripts and makefiles, a variable name is sometimes prefixed
@@ -445,4 +445,4 @@ with @samp{$} and sometimes not.  Major modes for this kind of text can
 customize dynamic abbrev expansion to handle optional prefixes by setting
 the variable @code{dabbrev-abbrev-skip-leading-regexp}.  Its value
 should be a regular expression that matches the optional prefix that
-dynamic abbrev expression should ignore.
+dynamic abbrev expression should ignore.  Its default value is @code{nil}.
diff --git a/doc/lispref/abbrevs.texi b/doc/lispref/abbrevs.texi
index 5f5a395..769ff03 100644
--- a/doc/lispref/abbrevs.texi
+++ b/doc/lispref/abbrevs.texi
@@ -198,7 +198,8 @@ abbrevs in a file automatically, under the control of variables
 described here.

 @defopt abbrev-file-name
-This is the default file name for reading and saving abbrevs.
+This is the default file name for reading and saving abbrevs.  Its default
+value is @file{~/.emacs.d/abbrev_defs}.
 @end defopt

 @defun quietly-read-abbrev-file &optional filename
@@ -216,7 +217,7 @@ A non-@code{nil} value for @code{save-abbrevs} means that Emacs should
 offer to save abbrevs (if any have changed) when files are saved.  If
 the value is @code{silently}, Emacs saves the abbrevs without asking
 the user.  @code{abbrev-file-name} specifies the file to save the
-abbrevs in.
+abbrevs in.  Its default value is @code{t}.
 @end defopt

 @defvar abbrevs-changed
@@ -283,6 +284,8 @@ be the name by which this abbrev was found (a string); it is used to
 figure out whether to adjust the capitalization of the expansion.  The
 function returns @code{abbrev} if the abbrev was successfully
 inserted.
+@c [sbb] what does it retrurn if name is not found?  nil?
+@c [sbb] what happens if start is defined but ent is not?  (Text should say)
 @end defun

 @deffn Command abbrev-prefix-mark &optional arg
@@ -298,7 +301,7 @@ next abbrev to be expanded.  The actual expansion removes the hyphen.
 @end deffn

 @defopt abbrev-all-caps
-When this is set non-@code{nil}, an abbrev entered entirely in upper
+When this is set to non-@code{nil}, an abbrev entered entirely in upper
 case is expanded using all upper case.  Otherwise, an abbrev entered
 entirely in upper case is expanded by capitalizing each word of the
 expansion.
@@ -331,6 +334,8 @@ Abbrevs, emacs, The GNU Emacs Manual}).
 This is the location of the most recent abbrev expanded.  This contains
 information left by @code{expand-abbrev} for the sake of the
 @code{unexpand-abbrev} command.
+@c when is it cleared?  Should we state that?  Presumably its initial value is
+@c nil, should that be stated as well?
 @end defvar

 @defvar last-abbrev-text
@@ -389,6 +394,8 @@ global table.
 The value of this buffer-local variable is the (mode-specific)
 abbreviation table of the current buffer.  It can also be a list of
 such tables.
+@c [sbb] Should we explain in a little more detail this list of abbrev tables
+@c [sbb] idea?  Such as precedence among the tables for identical abbrevs?
 @end defvar

 @defvar abbrev-minor-mode-table-alist
@@ -397,6 +404,8 @@ The value of this variable is a list of elements of the form
 of a variable: if the variable is bound to a non-@code{nil} value,
 then the @var{abbrev-table} is active, otherwise it is ignored.
 @var{abbrev-table} can also be a list of abbrev tables.
+@c [sbb] Should we explain in a little more detail this list of abbrev tables
+@c [sbb] idea?  Such as precedence among the tables for identical abbrevs?
 @end defvar

 @defvar fundamental-mode-abbrev-table
@@ -498,6 +507,7 @@ non-word syntax.
 @item :parents
 This property holds a list of tables from which to inherit
 other abbrevs.
+@c [sbb] Should talk about precedence among the tables here.

 @item :abbrev-table-modiff
 This property holds a counter incremented each time a new abbrev is


[-- Attachment #2: Message signed with OpenPGP using GPGMail --]
[-- Type: application/pgp-signature, Size: 203 bytes --]

bug#23016: 25.1; First proof reading of emacs/abbrevs.texi and lispref/abbrevs.texi

[Eli Zaretskii]

> From: Steve Byrne <sbb@penguinis.org>
> Date: Mon, 14 Mar 2016 19:37:53 -0700
> 
> My first cut at proofing.  I hope it will be ok that I hand-crafted this email message; M-x report-emacs-bug wanted to use a mail program that isn't present on OS X ;)

Thanks, I will deal with this in a couple of days.

For the future, I think it would be best if you reported the problems
and their suggested solutions in plain English, not as patches, since
you don't have copyright assignment on file for Emacs, so we are
limited in how many of your patches we will be able to apply.

bug#23016: 25.1; First proof reading of emacs/abbrevs.texi and lispref/abbrevs.texi

[Eli Zaretskii]

> Date: Wed, 16 Mar 2016 19:17:52 +0200
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: 23016@debbugs.gnu.org
> 
> > From: Steve Byrne <sbb@penguinis.org>
> > Date: Mon, 14 Mar 2016 19:37:53 -0700
> > 
> > My first cut at proofing.  I hope it will be ok that I hand-crafted this email message; M-x report-emacs-bug wanted to use a mail program that isn't present on OS X ;)
> 
> Thanks, I will deal with this in a couple of days.

Done, thanks.

I decided not to expand the documentation of the variables that are
not user options, but don't let this discourage you from raising
similar issues in the future, as the decisions there might well be
different.