Lowercase "arg" in doc strings.

Lowercase "arg" in doc strings.

[Reiner Steib]

Hi,

`checkdoc-defun' complains that "Argument `arg' should appear (as ARG)
in the doc string" for some functions.  I'll install the patch below,
unless somebody objects.

Bye, Reiner.

Index: comint.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/comint.el,v
retrieving revision 1.344
diff -u -r1.344 comint.el
--- comint.el	10 May 2006 21:31:09 -0000	1.344
+++ comint.el	22 May 2006 13:26:35 -0000
@@ -2359,11 +2359,11 @@
 
 (defun comint-kill-whole-line (&optional arg)
   "Kill current line, ignoring read-only and field properties.
-With prefix arg, kill that many lines starting from the current line.
-If arg is negative, kill backward.  Also kill the preceding newline,
+With prefix ARG, kill that many lines starting from the current line.
+If ARG is negative, kill backward.  Also kill the preceding newline,
 instead of the trailing one.  \(This is meant to make \\[repeat] work well
 with negative arguments.)
-If arg is zero, kill current line but exclude the trailing newline.
+If ARG is zero, kill current line but exclude the trailing newline.
 The read-only status of newlines is updated with `comint-update-fence',
 if necessary."
   (interactive "p")
Index: disp-table.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/disp-table.el,v
retrieving revision 1.61
diff -u -r1.61 disp-table.el
--- disp-table.el	6 Feb 2006 14:33:32 -0000	1.61
+++ disp-table.el	22 May 2006 13:26:35 -0000
@@ -196,7 +196,7 @@
 variable, or else customize `enable-multibyte-characters'.
 
 With prefix argument, this command enables European character display
-if arg is positive, disables it otherwise.  Otherwise, it toggles
+if ARG is positive, disables it otherwise.  Otherwise, it toggles
 European character display.
 
 When this mode is enabled, characters in the range of 160 to 255
Index: files.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/files.el,v
retrieving revision 1.837
diff -u -r1.837 files.el
--- files.el	17 May 2006 22:54:35 -0000	1.837
+++ files.el	22 May 2006 13:26:35 -0000
@@ -3778,7 +3778,7 @@
 
 (defun toggle-read-only (&optional arg)
   "Change whether this buffer is visiting its file read-only.
-With arg, set read-only iff arg is positive.
+With ARG, set read-only iff ARG is positive.
 If visiting file read-only and `view-read-only' is non-nil, enter view mode."
   (interactive "P")
   (if (and arg
Index: flow-ctrl.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/flow-ctrl.el,v
retrieving revision 1.31
diff -u -r1.31 flow-ctrl.el
--- flow-ctrl.el	6 Feb 2006 14:33:33 -0000	1.31
+++ flow-ctrl.el	22 May 2006 13:26:35 -0000
@@ -56,7 +56,7 @@
 (defun enable-flow-control (&optional argument)
   "Toggle flow control handling.
 When handling is enabled, user can type C-s as C-\\, and C-q as C-^.
-With arg, enable flow control mode if arg is positive, otherwise disable."
+With ARG, enable flow control mode if ARG is positive, otherwise disable."
   (interactive "P")
   (if (if argument
 	  ;; Argument means enable if arg is positive.
Index: simple.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/simple.el,v
retrieving revision 1.804
diff -u -r1.804 simple.el
--- simple.el	21 May 2006 22:56:27 -0000	1.804
+++ simple.el	22 May 2006 13:26:36 -0000
@@ -4245,7 +4245,7 @@
 
 (defun toggle-truncate-lines (arg)
   "Toggle whether to fold or truncate long lines on the screen.
-With arg, truncate long lines iff arg is positive.
+With ARG, truncate long lines iff ARG is positive.
 Note that in side-by-side windows, truncation is always enabled."
   (interactive "P")
   (setq truncate-lines

-- 
       ,,,
      (o o)
---ooO-(_)-Ooo---  |  PGP key available  |  http://rsteib.home.pages.de/

Re: Lowercase "arg" in doc strings.

[Andreas Schwab]

Reiner Steib <reinersteib+gmane@imap.cc> writes:

>  (defun comint-kill-whole-line (&optional arg)
>    "Kill current line, ignoring read-only and field properties.
> -With prefix arg, kill that many lines starting from the current line.
> -If arg is negative, kill backward.  Also kill the preceding newline,
> +With prefix ARG, kill that many lines starting from the current line.
> +If ARG is negative, kill backward.  Also kill the preceding newline,

I don't think this is correct.  `Prefix arg' is a technical term that only
coincidentally matches the name of the parameter.

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany
PGP key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Lowercase "arg" in doc strings.

[Richard Stallman]

    -With prefix arg, kill that many lines starting from the current line.
    -If arg is negative, kill backward.  Also kill the preceding newline,
    +With prefix ARG, kill that many lines starting from the current line.

Using ARG in upper case in this doc string is a good change, but it's
not correct to say "prefix ARG", because that implies ARG is a prefix.
It isn't a prefix, it is a prefix argument (often abbreviated "prefix
arg").

If you change that to "With prefix arg ARG", then it would be correct.
However, it might be clearer overall if you replace ARG with COUNT or N.

    -With arg, set read-only iff arg is positive.
    +With ARG, set read-only iff ARG is positive.

The current text makes sense; it is a terse way of saying "with a
prefix argument".  The proposed changed text does not make sense.  You
need to do this some other way.

In general, "arg" is an English noun, an abbreviation of "argument".
"ARG" is a proper name, the name of one particular argument.  They do
not have the same meaning, and they cannot be used in the same
contexts, so you cannot just replace one with the other.  To make the
text use ARG, you need to rewrite it so that it makes sense and still
says the other things it needs to say.