[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Fix the choked unreality in page Parser State in syntax.texi.
From: |
Alan Mackenzie |
Subject: |
Fix the choked unreality in page Parser State in syntax.texi. |
Date: |
Wed, 18 Dec 2019 19:54:23 +0000 |
User-agent: |
Mutt/1.10.1 (2018-07-13) |
Hello, Emacs.
The page Parser State in the Elisp manual gives a choked, vague,
inadequate impression. The cause is clear - A parser state is exactly
the return value of parse-partial-sexp, yet that function is not
mentioned once in the page.
In fact, the page looks censored to avoid mentioning parse-partial-sexp.
This is ridiculous and harmful.
I therefore propose installing the following documentation patch for
Emacs 27. It also tidies up one or two untidinesses:
diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi
index 63d534dd13..d494d6fc5e 100644
--- a/doc/lispref/syntax.texi
+++ b/doc/lispref/syntax.texi
@@ -797,12 +797,13 @@ Parser State
A @dfn{parser state} is a list of (currently) eleven elements
describing the state of the syntactic parser, after it parses the text
between a specified starting point and a specified end point in the
-buffer. Parsing functions such as @code{syntax-ppss}
+buffer using @code{parse-partial-sexp} (@pxref{Low-Level Parsing}).
+Parsing functions such as @code{syntax-ppss}
@ifnottex
(@pxref{Position Parse})
@end ifnottex
-return a parser state as the value. Some parsing functions accept a
-parser state as an argument, for resuming parsing.
+also return a parser state as the value. @code{parse-partial-sexp}
+can accept a parser state as an argument, for resuming parsing.
Here are the meanings of the elements of the parser state:
@@ -866,11 +867,11 @@ Parser State
@end enumerate
Elements 1, 2, and 6 are ignored in a state which you pass as an
-argument to continue parsing. Elements 9 and 10 are mainly used
-internally by the parser code.
+argument to @code{parse-partial-sexp} to continue parsing. Elements 9
+and 10 are mainly used internally by the parser code.
- One additional piece of useful information is available from a
-parser state using this function:
+ Two additional pieces of useful information are available from a
+parser state using these functions:
@defun syntax-ppss-toplevel-pos state
This function extracts, from parser state @var{state}, the last
@@ -883,8 +884,8 @@ Parser State
@end defun
@defun syntax-ppss-context state
-Return @code{string} if @var{state} is a string and @code{comment} if
-it's a comment.
+Return @code{string} if the end position of a scan returning
+@var{state} is in a string, and @code{comment} if it's in a comment.
@end defun
@node Low-Level Parsing
--
Alan Mackenzie (Nuremberg, Germany).
- Fix the choked unreality in page Parser State in syntax.texi.,
Alan Mackenzie <=