Re: Some native compiler related renaming

["Basil L. Contovounesios" <contovob@tcd.ie>]

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

Eli Zaretskii <eliz@gnu.org> writes:

> I have now written some documentation of this new feature in the ELisp
> manual.

Thanks!

> Suggestions for improvements are welcome.  Bonus points for submitting
> patches that improve this documentation.

No bonus points for me please, only some nits.  How's this:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Minor-fixes-to-native-compilation-Texinfo.patch --]
[-- Type: text/x-diff, Size: 8283 bytes --]

From e799a7248b40139af63859bac6da68551ae53ce3 Mon Sep 17 00:00:00 2001
From: "Basil L. Contovounesios" <contovob@tcd.ie>
Date: Sat, 8 May 2021 15:45:47 +0100
Subject: [PATCH] Minor fixes to native compilation Texinfo

For discussion, see the following thread:
https://lists.gnu.org/r/emacs-devel/2021-05/msg00347.html

* doc/lispref/compile.texi (Native Compilation): Fix grammar in @ref
online label.
(Native-Compilation Functions): Consistently mark LIMPLE as an
@acronym and unhyphenate 'sub-process'.  Fix grammar.
(Native-Compilation Variables): Fix @cindex entry.
* doc/lispref/loading.texi (Library Search): Prefer @file over @samp
to refer to particular types of files (as opposed to particular
affixes when constructing file names).  Follow i.e. with US-style
comma.
---
 doc/lispref/compile.texi | 50 ++++++++++++++++++++--------------------
 doc/lispref/loading.texi | 12 +++++-----
 2 files changed, 31 insertions(+), 31 deletions(-)

diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi
index f0787795ca..09a3973d64 100644
--- a/doc/lispref/compile.texi
+++ b/doc/lispref/compile.texi
@@ -801,13 +801,13 @@ Native Compilation
 
 @cindex native code
   In addition to the byte-compilation, described in @ref{Byte
-Compilation, previous chapter}, Emacs can also optionally compile Lisp
-function definitions into a true compiled code, known as @dfn{native
-code}.  This feature uses the @file{libgccjit} library, which is part
-of the GCC distribution, and requires that Emacs be built with support
-for using that library.  It also requires to have GCC and Binutils
-(the assembler and linker) available on your system for you to be able
-to native-compile Lisp code.
+Compilation, the previous chapter}, Emacs can also optionally compile
+Lisp function definitions into a true compiled code, known as
+@dfn{native code}.  This feature uses the @file{libgccjit} library,
+which is part of the GCC distribution, and requires that Emacs be
+built with support for using that library.  It also requires to have
+GCC and Binutils (the assembler and linker) available on your system
+for you to be able to native-compile Lisp code.
 
 @vindex native-compile@r{, a Lisp feature}
   To determine whether the current Emacs process can produce and load
@@ -857,7 +857,7 @@ Native-Compilation Functions
 @section Native-Compilation Functions
 @cindex native-compilation functions
 
-   Native-Compilation is implemented as side effect of
+   Native-Compilation is implemented as a side effect of
 byte-compilation (@pxref{Byte Compilation}).  Thus, compiling Lisp
 code natively always produces its byte code as well, and therefore all
 the rules and caveats of preparing Lisp code for byte compilation
@@ -875,9 +875,9 @@ Native-Compilation Functions
   Native compilation might produce warning or error messages; these
 are normally recorded in the buffer called
 @file{*Native-compile-Log*}.  In interactive sessions, it uses the
-special LIMPLE mode (@code{native-comp-limple-mode}), which sets up
-@code{font-lock} as appropriate for this log, and is otherwise the
-same as Fundamental mode.  Logging of messages resulting from
+special @acronym{LIMPLE} mode (@code{native-comp-limple-mode}), which
+sets up @code{font-lock} as appropriate for this log, and is otherwise
+the same as Fundamental mode.  Logging of messages resulting from
 native-compilation can be controlled by the @code{native-comp-verbose}
 variable (@pxref{Native-Compilation Variables}).
 
@@ -892,14 +892,14 @@ Native-Compilation Functions
 or a name (a string) of the file which contains the Emacs Lisp source
 code to compile.  If the optional argument @var{output} is provided,
 it must be a string specifying the name of the file to write the
-compiled code.  Otherwise, if @var{function-or-file} is a function or
-a Lisp form, this function returns the compiled object, and if
-@var{function-or-file} is a file name, the function returns the full
-absolute name of the file it created for the compiled code.  The
+compiled code into.  Otherwise, if @var{function-or-file} is a
+function or a Lisp form, this function returns the compiled object,
+and if @var{function-or-file} is a file name, the function returns the
+full absolute name of the file it created for the compiled code.  The
 output file is by default given the @file{.eln} extension.
 
 This function runs the final phase of the native compilation, which
-invokes GCC via @file{libgccjit}, in a separate sub-process, which
+invokes GCC via @file{libgccjit}, in a separate subprocess, which
 invokes the same Emacs executable as the process that called this
 function.
 @end defun
@@ -913,12 +913,12 @@ Native-Compilation Functions
 non-zero status code.
 @end defun
 
-Native compilation can be run entirely asynchronously, in a
-sub-process of the main Emacs process.  This leaves the main Emacs
-process free to use while the compilation runs in the background.
-This is the method used by Emacs to natively-compile any Lisp file or
-byte-compiled Lisp file that is loaded into Emacs, when no
-natively-compiled file for it is available.
+Native compilation can be run entirely asynchronously, in a subprocess
+of the main Emacs process.  This leaves the main Emacs process free to
+use while the compilation runs in the background.  This is the method
+used by Emacs to natively-compile any Lisp file or byte-compiled Lisp
+file that is loaded into Emacs, when no natively-compiled file for it
+is available.
 
 @defun native-compile-async files &optional recursively load selector
 This function compiles the named @var{files} asynchronously.  The
@@ -944,12 +944,12 @@ Native-Compilation Functions
 
 On systems with multiple CPU execution units, when @var{files} names
 more than one file, this function will normally start several
-compilation sub-processes in parallel, under the control of
+compilation subprocesses in parallel, under the control of
 @code{native-comp-async-jobs-number} (@pxref{Native-Compilation
 Variables}).
 @end defun
 
-  The following function allows Lisp program to test whether
+  The following function allows Lisp programs to test whether
 native-compilation is available at runtime.
 
 @defun native-comp-available-p
@@ -962,7 +962,7 @@ Native-Compilation Functions
 
 @node Native-Compilation Variables
 @section Native-Compilation Variables
-@cindex native-compilation variable
+@cindex native-compilation variables
 
   This section documents the variables that control
 native-compilation.
diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
index 4d683da1ad..f1fed7a2da 100644
--- a/doc/lispref/loading.texi
+++ b/doc/lispref/loading.texi
@@ -438,21 +438,21 @@ Library Search
 @end deffn
 
   If Emacs was compiled with support for native compilation
-(@pxref{Native Compilation}), then when a @samp{.elc} byte-compiled
+(@pxref{Native Compilation}), then when a @file{.elc} byte-compiled
 file is found by searching @code{load-path}, Emacs will try to look
-for a corresponding @samp{.eln} file holding the corresponding
+for a corresponding @file{.eln} file holding the corresponding
 natively-compiled code.  The natively-compiled files are looked up in
 the directories listed by the @code{native-comp-eln-load-path}.
 
 @vindex comp-native-version-dir
 @defvar native-comp-eln-load-path
 This variable holds a list of directories where Emacs looks for
-natively-compiled @samp{.eln} files.  File names in the list that are
+natively-compiled @file{.eln} files.  File names in the list that are
 not absolute are interpreted as relative to @code{invocation-directory}
 (@pxref{System Environment}).  The last directory in the list is the
-system directory, i.e.@: the directory with @samp{.eln} files
-installed by the Emacs build and installation procedure.  In each of
-the directories in the list, Emacs looks for @samp{.eln} files in a
+system directory, i.e., the directory with @file{.eln} files installed
+by the Emacs build and installation procedure.  In each of the
+directories in the list, Emacs looks for @file{.eln} files in a
 subdirectory whose name is constructed from the Emacs version and an
 8-character hash that depends on the current native-compilation
 @acronym{ABI}; the name of this subdirectory is stored in the variable
-- 
2.30.2


[-- Attachment #3: Type: text/plain, Size: 11 bytes --]


-- 
Basil