bug#15429: 23.4; doc string of `syntax-ppss'

bug#15429: 23.4; doc string of `syntax-ppss'

[Drew Adams]

"... except that the 2nd and 6th values of the returned state cannot be
relied upon."

Be clearer.  Say exactly which values you mean - describe them.

This is all the more important because the doc for `parse-partial-sexp'
lists the values of the return state starting with 0, not 1.  So what is
the "second" value of the return state?

Is it the second item in the returned list, or is it value "2" according
to the `parse-partial-sexp' doc?  It turns out, according to (elisp)
`Position Parse', that it is the latter.

This is really sloppy.  Even the manual's description should avoid use
of "2nd value" and "6th value", even if it does provide the real info in
parens.  In English (and math), the second value of a list is the second
value.  It is not (nth 2...) - that's the third value.



In GNU Emacs 23.4.1 (i386-mingw-nt6.1.7601)
 of 2012-02-04 on MARVIN
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --with-gcc (4.4) --cflags
 -ID:/devel/emacs/libs/libXpm-3.5.8/include
 -ID:/devel/emacs/libs/libXpm-3.5.8/src
 -ID:/devel/emacs/libs/libpng-dev_1.4.3-1/include
 -ID:/devel/emacs/libs/zlib-dev_1.2.5-2/include
 -ID:/devel/emacs/libs/giflib-4.1.4-1/include
 -ID:/devel/emacs/libs/jpeg-6b-4/include
 -ID:/devel/emacs/libs/tiff-3.8.2-1/include'

bug#15429: 23.4; doc string of `syntax-ppss'

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

> "... except that the 2nd and 6th values of the returned state cannot be
> relied upon."
>
> Be clearer.  Say exactly which values you mean - describe them.
>
> This is all the more important because the doc for `parse-partial-sexp'
> lists the values of the return state starting with 0, not 1.  So what is
> the "second" value of the return state?

The doc (now) says:

The returned value is the same as that of `parse-partial-sexp'
run from `point-min' to POS except that values at positions 2 and 6
in the returned list (counting from 0) cannot be relied upon.

So I think that's OK now.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/