Fix the choked unreality in page Parser State in syntax.texi.

Fix the choked unreality in page Parser State in syntax.texi.

[Alan Mackenzie]

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).

Re: Fix the choked unreality in page Parser State in syntax.texi.

[Eli Zaretskii]

> Date: Wed, 18 Dec 2019 19:54:23 +0000
> From: Alan Mackenzie <acm@muc.de>
> 
> 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:

Thanks, this is fine with me, but please wait for someone who knows
syntax-ppss better than I do to agree with the changes.

Re: Fix the choked unreality in page Parser State in syntax.texi.

[Stefan Monnier]

> I therefore propose installing the following documentation patch for
> Emacs 27.  It also tidies up one or two untidinesses:

LGTM, thanks (rather than replacing "one" with "two", I'd rephrase so
that it doesn't mention how many there are to avoid such
inconsistencies in the future ;-)


        Stefan

>
>
> 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

Re: Fix the choked unreality in page Parser State in syntax.texi.

[Alan Mackenzie]

Hello, Stefan and Eli.

On Fri, Dec 20, 2019 at 11:45:15 -0500, Stefan Monnier wrote:
> > I therefore propose installing the following documentation patch for
> > Emacs 27.  It also tidies up one or two untidinesses:

> LGTM, thanks (rather than replacing "one" with "two", I'd rephrase so
> that it doesn't mention how many there are to avoid such
> inconsistencies in the future ;-)

Yes, that would be a lot better.  I've changed the patch for that, and
committed it to the master branch.

>         Stefan

-- 
Alan Mackenzie (Nuremberg, Germany).