bug#30393: 24.4; cperl-mode: indentation failure - Documentation enhancements

[Eli Zaretskii]

> Date: Mon, 16 Apr 2018 19:21:37 +0000
> Cc: monnier@IRO.UMontreal.CA, 30393@debbugs.gnu.org, dgutov@yandex.ru,
>   npostavs@users.sourceforge.net
> From: Alan Mackenzie <acm@muc.de>
> 
> However, I propose the following documentation changes to go with my
> patch to the code, these changes clarifying some of the limitations
> inherent to syntax-ppss, and indicating how my enhancements will work.

OK.  I have a minor stylistic comment about the documentation changes:

> +As an alternative to setting @code{syntax-table} text properties
> +directly, you can use @code{syntax-propertize-function} (see below).
> +Most major modes supplied with Emacs which use these text properties
> +use this method for applying them.  We strongly recommended you to use
> +just one of these methods in any Emacs Lisp program, and not to mix
> +them in the same buffer.@footnote{@code{syntax-propertize-function}
> +can operate at unpredictable times, and may erase explicitly applied
> +@code{syntax-table} properties.}

@footnote should begin before the period that ends a sentence to which
the footnote applies.  I believe the usual typographic convention is
to show footnotes as this:

   bla bla bla¹.

rather than as this:

   yak yak yak.¹

If you agree, this should be fixed in more than one place in your
patch.

Another minor comment is to please consider whether the description
you add warrant some new index entries, so that it would be easier to
find this stuff when one is specifically looking for it.  I tend to
think at least some index entries would be useful.

Thanks.