bug#21501: new Emacs functions for capitalizing text intelligently

[Eli Zaretskii <eliz@gnu.org>]

> From: Zachary Kanfer <zkanfer@gmail.com>
> Date: Sun, 20 Sep 2015 02:13:39 -0400
> Cc: 21501@debbugs.gnu.org
> 
> Here's a changed patch.

Thanks.  Allow me a couple of minor comments.

> I'm in favor of changing M-u, M-l, and M-c to the new commands; I think it's
> much improved behavior. The only time a user would have to do more work to
> perform a capitalization action is if they've selected a region, but want to
> act only on the next word. I would bet that's rare, and even so, the user only
> has to press C-g before the capitalization. So if we're ok changing default
> commands, I think changing M-u, M-l, and M-c is a win.

For us to be able to bind M-u etc. to these new commands, they need to
support the prefix argument to upcase-word etc.  The way you wrote
these new commands, that feature will be lost.

> +;;; Functions relating to capitalization that Do What I Mean
> +(defun upcase-dwim ()
> +  "Call the upcase command you want (Do What I Mean).
> +If the region is active, call `upcase-region'.  Otherwise call
> +`upcase-word'."

Every doc string should state the effect of the function/variable in
its first line, because some Help commands (like 'apropos') show only
the first line.  The above doc string (and the others in your patch)
don't do that; the effect is only clear if one reads the rest of the
doc string.

I suggest to change the doc strings like this:

  Upcase words in the region, if active; otherwise upcase word at point.
If the region is active, this function calls `upcase-region'.
Otherwise it calls `upcase-word'.