bug#67820: 29.1; Code example in "fwd-para while" has unmatched ending parentheses

[Xiyue Deng <manphiz@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 1652 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Xiyue Deng <manphiz@gmail.com>
>> Cc: 67820@debbugs.gnu.org
>> Date: Fri, 15 Dec 2023 14:08:51 -0800
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> >> From: Xiyue Deng <manphiz@gmail.com>
>> >> Date: Wed, 13 Dec 2023 21:55:55 -0800
>> >> 
>> >> 
>> >> The code example in section "fwd-para while" has unmatched ending
>> >> parentheses[1].  Admittedly this code snippet was copied literally from
>> >> the previous longer code sample where the 2 extra ending parentheses
>> >> were to match the `if' and `while', but it would make more sense to drop
>> >> them in this example.  Will add a patch next.
>> >
>> > I'm not sure it makes sense to make this expression stand-alone.  As
>> > you say, this snippet is copied verbatim from the full example at the
>> > beginning of the section.  So I think we should leave this alone.
>> >
>> > Thanks.
>> 
>> This essentially was due to the coding convention to put all ending
>> parentheses on the last line of the sexp, which most other programming
>> languages don't normally share.  But anyway.
>> 
>> Just want to say that a code snippet with unmatched ending parentheses
>> would confuse beginners a little.  However, if from a book writing point
>> of view that code snippets should be copied literally, it's probably
>> understandable (adding a small explanation for the extras would better
>> still, and I can update the patch accordingly.)
>> 
>> Wdyt?
>
> It's okay to add a note in parentheses that this snippet is from the
> above full code, and therefore is not standalone.

Sounds good.  Please see the updated patch attached.
-- 
Xiyue Deng


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-explanation-for-the-two-extra-ending-parentheses.patch --]
[-- Type: text/x-diff, Size: 1098 bytes --]

From 823abac0236aa07fee317bfa35f913d1f0be48d5 Mon Sep 17 00:00:00 2001
From: Xiyue Deng <manphiz@gmail.com>
Date: Wed, 13 Dec 2023 16:21:10 -0800
Subject: [PATCH] Add explanation for the two extra ending parentheses
 (bug#67820)

* doc/lispintro/emacs-lisp-intro.texi (fwd-para while): add notes to
explain the extra ending parentheses.
---
 doc/lispintro/emacs-lisp-intro.texi | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi
index eb8ff413b79..09ab97110ae 100644
--- a/doc/lispintro/emacs-lisp-intro.texi
+++ b/doc/lispintro/emacs-lisp-intro.texi
@@ -13250,6 +13250,10 @@ The last expression when there is no fill prefix is
 @end smallexample
 
 @noindent
+(Note that this code snippet is copied verbatim from the original code,
+so the two extra ending parentheses are matching the previous `if' and
+`while'.)
+
 This says that if there is no fill prefix and if we are not at the
 end, point should move to the beginning of whatever was found by the
 regular expression search for @code{sp-parstart}.
-- 
2.39.2