From: Alan Mackenzie <acm@muc.de>
Date: Fri, 20 Dec 2019 19:55:29 +0000 (+0000)
Subject: Elisp manual: mention parse-partial-sexp as the source of a parser state, etc
X-Git-Tag: emacs-27.0.90~328
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=52178a312d34512f7db53ae34ea7f815b5a13323;p=emacs.git

Elisp manual: mention parse-partial-sexp as the source of a parser state, etc

* doc/lispref/syntax.texi (Parser State): mention parse-partial-sexp as a
function returning a parser state, and the function to which one supplies a
parser state as an argument for continued parsing.
Refine the documentation of syntax-ppss-context, and correct the text
introducing it and another function.
---

diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi
index 63d534dd134..364180b9920 100644
--- a/doc/lispref/syntax.texi
+++ b/doc/lispref/syntax.texi
@@ -797,12 +797,13 @@ Hooks}).
   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 @@ escaped/char-quoted character pair), the @var{syntax-code}
 @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:
+  Some additional useful information is 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 @@ arrived at a top level position.
 @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 the scan returning
+@var{state} is in a string, and @code{comment} if it's in a comment.
 @end defun
 
 @node Low-Level Parsing