Re: improvement in functions.texi

Re: improvement in functions.texi

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

I propose this improvement in functions.texi.  The biggest change
is moving the description of define-inline into the node Inline Functions
where it semantically fits better.  But this also adds a cross
reference in Defining Functions to information about undefining.

diff -u /home/rms/emacs-git/build-oct-2/doc/lispref/functions.texi.\~2\~ /home/rms/emacs-git/build-oct-2/doc/lispref/functions.texi
--- /home/rms/emacs-git/build-oct-2/doc/lispref/functions.texi.~2~	2019-10-26 08:57:05.985082189 -0400
+++ /home/rms/emacs-git/build-oct-2/doc/lispref/functions.texi	2020-01-05 16:12:09.453450858 -0500
@@ -575,8 +575,9 @@
 @cindex defining a function
 
   We usually give a name to a function when it is first created.  This
-is called @dfn{defining a function}, and it is done with the
-@code{defun} macro.
+is called @dfn{defining a function}, and we usually do it with the
+@code{defun} macro.  This section also describes other ways to define
+a function.
 
 @defmac defun name args [doc] [declare] [interactive] body@dots{}
 @code{defun} is the usual way to define new Lisp functions.  It
@@ -681,95 +682,8 @@
 and tells the Lisp compiler to perform inline expansion on it.
 @xref{Inline Functions}.
 
-  Alternatively, you can define a function by providing the code which
-will inline it as a compiler macro.  The following macros make this
-possible.
-
-@c FIXME: Can define-inline use the interactive spec?
-@defmac define-inline name args [doc] [declare] body@dots{}
-Define a function @var{name} by providing code that does its inlining,
-as a compiler macro.  The function will accept the argument list
-@var{args} and will have the specified @var{body}.
-
-If present, @var{doc} should be the function's documentation string
-(@pxref{Function Documentation}); @var{declare}, if present, should be
-a @code{declare} form (@pxref{Declare Form}) specifying the function's
-metadata.
-@end defmac
-
-Functions defined via @code{define-inline} have several advantages
-with respect to macros defined by @code{defsubst} or @code{defmacro}:
-
-@itemize @minus
-@item
-They can be passed to @code{mapcar} (@pxref{Mapping Functions}).
-
-@item
-They are more efficient.
-
-@item
-They can be used as @dfn{place forms} to store values
-(@pxref{Generalized Variables}).
-
-@item
-They behave in a more predictable way than @code{cl-defsubst}
-(@pxref{Argument Lists,,, cl, Common Lisp Extensions for GNU Emacs
-Lisp}).
-@end itemize
-
-Like @code{defmacro}, a function inlined with @code{define-inline}
-inherits the scoping rules, either dynamic or lexical, from the call
-site.  @xref{Variable Scoping}.
-
-The following macros should be used in the body of a function defined
-by @code{define-inline}.
-
-@defmac inline-quote expression
-Quote @var{expression} for @code{define-inline}.  This is similar to
-the backquote (@pxref{Backquote}), but quotes code and accepts only
-@code{,}, not @code{,@@}.
-@end defmac
-
-@defmac inline-letevals (bindings@dots{}) body@dots{}
-This is similar to @code{let} (@pxref{Local Variables}): it sets up
-local variables as specified by @var{bindings}, and then evaluates
-@var{body} with those bindings in effect.  Each element of
-@var{bindings} should be either a symbol or a list of the form
-@w{@code{(@var{var} @var{expr})}}; the result is to evaluate
-@var{expr} and bind @var{var} to the result.  The tail of
-@var{bindings} can be either @code{nil} or a symbol which should hold
-a list of arguments, in which case each argument is evaluated, and the
-symbol is bound to the resulting list.
-@end defmac
-
-@defmac inline-const-p expression
-Return non-@code{nil} if the value of @var{expression} is already
-known.
-@end defmac
-
-@defmac inline-const-val expression
-Return the value of @var{expression}.
-@end defmac
-
-@defmac inline-error format &rest args
-Signal an error, formatting @var{args} according to @var{format}.
-@end defmac
-
-Here's an example of using @code{define-inline}:
-
-@lisp
-(define-inline myaccessor (obj)
-  (inline-letevals (obj)
-    (inline-quote (if (foo-p ,obj) (aref (cdr ,obj) 3) (aref ,obj 2)))))
-@end lisp
-
-@noindent
-This is equivalent to
-
-@lisp
-(defsubst myaccessor (obj)
-  (if (foo-p obj) (aref (cdr obj) 3) (aref obj 2)))
-@end lisp
+  To undefine a function name, use @code{fmakunbound}.
+@xref{Function Cells}.
 
 @node Calling Functions
 @section Calling Functions
@@ -2154,8 +2068,12 @@
   An @dfn{inline function} is a function that works just like an
 ordinary function, except for one thing: when you byte-compile a call
 to the function (@pxref{Byte Compilation}), the function's definition
-is expanded into the caller.  To define an inline function, use
-@code{defsubst} instead of @code{defun}.
+is expanded into the caller.
+
+  The simple way to define an inline function, is to write
+@code{defsubst} instead of @code{defun}.  The rest of the definition
+looks just the same, but using @code{defsubst} says to make it inline
+for byte compilation.
 
 @defmac defsubst name args [doc] [declare] [interactive] body@dots{}
 This macro defines an inline function.  Its syntax is exactly the same
@@ -2193,9 +2111,95 @@
 worry about how many times the body uses the arguments, as you do for
 macros.
 
-  As an alternative to @code{defsubst}, you can use
-@code{define-inline} to define functions via their exhaustive compiler
-macro.  @xref{Defining Functions, define-inline}.
+  Alternatively, you can define a function by providing the code which
+will inline it as a compiler macro.  The following macros make this
+possible.
+
+@c FIXME: Can define-inline use the interactive spec?
+@defmac define-inline name args [doc] [declare] body@dots{}
+Define a function @var{name} by providing code that does its inlining,
+as a compiler macro.  The function will accept the argument list
+@var{args} and will have the specified @var{body}.
+
+If present, @var{doc} should be the function's documentation string
+(@pxref{Function Documentation}); @var{declare}, if present, should be
+a @code{declare} form (@pxref{Declare Form}) specifying the function's
+metadata.
+@end defmac
+
+Functions defined via @code{define-inline} have several advantages
+with respect to macros defined by @code{defsubst} or @code{defmacro}:
+
+@itemize @minus
+@item
+They can be passed to @code{mapcar} (@pxref{Mapping Functions}).
+
+@item
+They are more efficient.
+
+@item
+They can be used as @dfn{place forms} to store values
+(@pxref{Generalized Variables}).
+
+@item
+They behave in a more predictable way than @code{cl-defsubst}
+(@pxref{Argument Lists,,, cl, Common Lisp Extensions for GNU Emacs
+Lisp}).
+@end itemize
+
+Like @code{defmacro}, a function inlined with @code{define-inline}
+inherits the scoping rules, either dynamic or lexical, from the call
+site.  @xref{Variable Scoping}.
+
+The following macros should be used in the body of a function defined
+by @code{define-inline}.
+
+@defmac inline-quote expression
+Quote @var{expression} for @code{define-inline}.  This is similar to
+the backquote (@pxref{Backquote}), but quotes code and accepts only
+@code{,}, not @code{,@@}.
+@end defmac
+
+@defmac inline-letevals (bindings@dots{}) body@dots{}
+This is similar to @code{let} (@pxref{Local Variables}): it sets up
+local variables as specified by @var{bindings}, and then evaluates
+@var{body} with those bindings in effect.  Each element of
+@var{bindings} should be either a symbol or a list of the form
+@w{@code{(@var{var} @var{expr})}}; the result is to evaluate
+@var{expr} and bind @var{var} to the result.  The tail of
+@var{bindings} can be either @code{nil} or a symbol which should hold
+a list of arguments, in which case each argument is evaluated, and the
+symbol is bound to the resulting list.
+@end defmac
+
+@defmac inline-const-p expression
+Return non-@code{nil} if the value of @var{expression} is already
+known.
+@end defmac
+
+@defmac inline-const-val expression
+Return the value of @var{expression}.
+@end defmac
+
+@defmac inline-error format &rest args
+Signal an error, formatting @var{args} according to @var{format}.
+@end defmac
+
+Here's an example of using @code{define-inline}:
+
+@lisp
+(define-inline myaccessor (obj)
+  (inline-letevals (obj)
+    (inline-quote (if (foo-p ,obj) (aref (cdr ,obj) 3) (aref ,obj 2)))))
+@end lisp
+
+@noindent
+This is equivalent to
+
+@lisp
+(defsubst myaccessor (obj)
+  (if (foo-p obj) (aref (cdr obj) 3) (aref obj 2)))
+@end lisp
 
 @node Declare Form
 @section The @code{declare} Form

Diff finished.  Sun Jan  5 16:20:31 2020

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Bad RFC 2047 decoding in Rmail

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: michael_heerdegen@web.de, pieter-l@vanoostrum.org,
> 	jidanni@jidanni.org, 38818@debbugs.gnu.org
> Date: Mon, 06 Jan 2020 18:08:36 -0500
> 
> I debugged this some, and found that rfc2047-decode-encoded-words
> is decoding header fields such as =?iso-8859-1?Q?B=C3=A9raud?=
> incorrectly, using a peculiar choice of coding system, windows-1252.
> That seems to come from mm-charset-to-coding-system.
> 
> Does anyone see how that could happen?

It has to be something at least a bit specific to your environment or
customizations, because I use Rmail in the exact same way, and these
problems never happen to me, including when replying to jidanni.

Can you try this in "emacs -Q"?  It would help if you did that with
the email message where the problem happened, which is this:

  https://debbugs.gnu.org/cgi/bugreport.cgi?bug=38818#80

You can download that message in mbox format from this URL:

  https://debbugs.gnu.org/cgi/bugreport.cgi?msg=80;bug=38818;mbox=yes

If you respond to this message, and the problem happens in "emacs -Q"
as well, then please either step through rfc2047-decode-encoded-words
and tell where does it make the bad decoding decision, or tell me you
values of locale-coding-system and buffer-file-coding-system, and I
will try to reproduce on my system.

If the problem doesn't happen in "emacs -Q", then some of your
customizations directly or indirectly cause
rfc2047-decode-encoded-words to fail, and so please try to find out
which of the customizations do that.

Re: Bad RFC 2047 decoding in Rmail

[Stefan Monnier]

>> I debugged this some, and found that rfc2047-decode-encoded-words
>> is decoding header fields such as =?iso-8859-1?Q?B=C3=A9raud?=
>> incorrectly, using a peculiar choice of coding system, windows-1252.

`windows-1252` is a superset of `iso-8859-1` (it assigns chars to a few
more bytes which `iso-8859-1` leaves unused), so it can only generate
"incorrect" output if `iso-8859-1` would have generated incorrect output
as well.


        Stefan

Re: Bad RFC 2047 decoding in Rmail

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > `windows-1252` is a superset of `iso-8859-1` (it assigns chars to a few
  > more bytes which `iso-8859-1` leaves unused), so it can only generate
  > "incorrect" output if `iso-8859-1` would have generated incorrect output
  > as well.

I thought I partially understood the problem, but it seems I did not get
any real understanding.


-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: improvement in functions.texi

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Sun, 05 Jan 2020 17:21:41 -0500
> Cc: michael_heerdegen@web.de, pieter-l@vanoostrum.org, jidanni@jidanni.org
> 
> I propose this improvement in functions.texi.  The biggest change
> is moving the description of define-inline into the node Inline Functions
> where it semantically fits better.  But this also adds a cross
> reference in Defining Functions to information about undefining.

Thanks, installed.