GNU bug report logs - #31576
emacs-lisp-intro.texi - NAME, TITLE inconsistency among @node, @unnumberedsec

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 31576 in the body.
You can then email your comments to 31576 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Van L <van <at> scratch.space>
To: bug-gnu-emacs <at> gnu.org
Subject: emacs-lisp-intro.texi - NAME, TITLE inconsistency among @node,
 @unnumberedsec
Date: Thu, 24 May 2018 10:41:55 +1000

Hello.

IMO, having `@node NAME' consistent with `@unnumberedsec TITLE' is better in an intro.

  #+BEGIN_EXAMPLE

    8cda6f8f (Glenn Morris             2007-09-06  1057) @ifnottex
    d6adf7e7 (Glenn Morris             2012-05-28  1058) @node Numbers Lists
    8cda6f8f (Glenn Morris             2007-09-06  1059) @unnumberedsubsec Numbers, Lists inside of Lists
    8cda6f8f (Glenn Morris             2007-09-06  1060) @end ifnottex

    8cda6f8f (Glenn Morris             2007-09-06  6759) @ifnottex
    d6adf7e7 (Glenn Morris             2012-05-28  6760) @node Strange Names
    8cda6f8f (Glenn Morris             2007-09-06  6761) @unnumberedsec Strange Names
    8cda6f8f (Glenn Morris             2007-09-06  6762) @end ifnottex

  #+END_EXAMPLE

Message #8 received at 31576 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Van L <van <at> scratch.space>
Cc: 31576 <at> debbugs.gnu.org
Subject: Re: bug#31576: emacs-lisp-intro.texi - NAME,
 TITLE inconsistency among @node, @unnumberedsec
Date: Thu, 24 May 2018 05:38:08 +0300

> From: Van L <van <at> scratch.space>
> Date: Thu, 24 May 2018 10:41:55 +1000
> 
> Hello.
> 
> IMO, having `@node NAME' consistent with `@unnumberedsec TITLE' is better in an intro.

I'm not sure I understand why.  This is an introduction to Emacs Lisp,
not to Texinfo.  All our manuals use different names for nodes and for
corresponding chapters/sections, primarily because the node name is
just a label, and also because some characters should not appear ion a
node name.

I see no problem here.

Message #11 received at 31576 <at> debbugs.gnu.org (full text, mbox):

From: Van L <van <at> scratch.space>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 31576 <at> debbugs.gnu.org
Subject: Re: bug#31576: emacs-lisp-intro.texi - NAME,
 TITLE inconsistency among @node, @unnumberedsec
Date: Thu, 24 May 2018 12:47:10 +1000

> Eli Zaretskii writes:
> 
> I see no problem here.

I don’t want to nitpick, just registering what looks out of place with fresh eyes. I’m not looking at how the label fits the context, if either both adequately capture the context I see no problem either.

Message #14 received at 31576 <at> debbugs.gnu.org (full text, mbox):

From: Van L <van <at> scratch.space>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 31576 <at> debbugs.gnu.org
Subject: Re: bug#31576: emacs-lisp-intro.texi - NAME,
 TITLE inconsistency among @node, @unnumberedsec
Date: Thu, 24 May 2018 13:33:34 +1000

> Eli Zaretskii writes:
> 
> I'm not sure I understand why.  This is an introduction to Emacs Lisp,
> not to Texinfo.

To my understanding, the texi file is the source and the other files are facets in the presentation. A person may switch between reading the infopage and pdf. Jotting down on paper `numbers, lists in lists’ from reading the pdf then later on resuming on the infopage will look different as `numbers lists’.

Message #17 received at 31576 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Van L <van <at> scratch.space>
Cc: 31576 <at> debbugs.gnu.org
Subject: Re: bug#31576: emacs-lisp-intro.texi - NAME,
 TITLE inconsistency among @node, @unnumberedsec
Date: Thu, 24 May 2018 07:29:55 +0300

On May 24, 2018 6:33:34 AM GMT+03:00, Van L <van <at> scratch.space> wrote:
> 
> > Eli Zaretskii writes:
> > 
> > I'm not sure I understand why.  This is an introduction to Emacs
> Lisp,
> > not to Texinfo.
> 
> To my understanding, the texi file is the source and the other files
> are facets in the presentation. A person may switch between reading
> the infopage and pdf. Jotting down on paper `numbers, lists in lists’
> from reading the pdf then later on resuming on the infopage will look
> different as `numbers lists’.

The chapter and section names are shown in the Info format as well.

So I still don't think I see the problem.  Besides, renaming all the nodes
and sections is a huge job, and a waste if done unnesessarily.

Message #20 received at 31576 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Van L <van <at> scratch.space>
Cc: 31576 <at> debbugs.gnu.org
Subject: Re: bug#31576: emacs-lisp-intro.texi - NAME,
 TITLE inconsistency among @node, @unnumberedsec
Date: Thu, 24 May 2018 07:35:10 +0300

On May 24, 2018 5:47:10 AM GMT+03:00, Van L <van <at> scratch.space> wrote:
> 
> > Eli Zaretskii writes:
> > 
> > I see no problem here.
> 
> I don’t want to nitpick, just registering what looks out of place with
> fresh eyes. I’m not looking at how the label fits the context, if
> either both adequately capture the context I see no problem either.

You don't need to apologize for reporting something that looks
strange to you, but please also accept the responses, even if you
aren't entirely convinced.  There's a lot of history, conventions, and
other good reasons behind what we do, so not everything you find
surprising at first sight is nesessarily a real problem.

Thanks.

Message #23 received at 31576 <at> debbugs.gnu.org (full text, mbox):

From: Van L <van <at> scratch.space>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 31576 <at> debbugs.gnu.org
Subject: Re: bug#31576: emacs-lisp-intro.texi - NAME,
 TITLE inconsistency among @node, @unnumberedsec
Date: Thu, 24 May 2018 21:51:59 +1000

> Eli Zaretskii writes:
> 
> You don't need to apologize for reporting something that looks
> strange to you, but please also accept the responses, even if you
> aren't entirely convinced.  There's a lot of history

Thanks for your help. I agree with you.

Looking at

: d6adf7e7 (Glenn Morris             2012-05-28  1206) @node Typing Lists
: 8cda6f8f (Glenn Morris             2007-09-06  1207) @subsection GNU Emacs Helps You Type Lists

it makes sense why the node name is short, presentation-wise in the infopage. 

A comment saying this is justified at the first instance will help future readers in the texi file.

Message #26 received at 31576 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Van L <van <at> scratch.space>
Cc: 31576 <at> debbugs.gnu.org
Subject: Re: bug#31576: emacs-lisp-intro.texi - NAME,
 TITLE inconsistency among @node, @unnumberedsec
Date: Thu, 24 May 2018 18:33:01 +0300

> From: Van L <van <at> scratch.space>
> Date: Thu, 24 May 2018 21:51:59 +1000
> Cc: 31576 <at> debbugs.gnu.org
> 
> : d6adf7e7 (Glenn Morris             2012-05-28  1206) @node Typing Lists
> : 8cda6f8f (Glenn Morris             2007-09-06  1207) @subsection GNU Emacs Helps You Type Lists
> 
> it makes sense why the node name is short, presentation-wise in the infopage. 

Yes, that's one of the aspects of a good Texinfo usage.

> A comment saying this is justified at the first instance will help future readers in the texi file.

I don't think this manual is a place to document that.  How to choose
good node names is explained in the Texinfo manual, see the node "Node
Names" there.

This manual should (as any other manual, IMO) assume the typical
reader reads it either in Info/HTML, or in PDF, or as a book.  the
Texinfo source is not the medium whose appearance we should judge wrt
these aspects.

Message #29 received at 31576 <at> debbugs.gnu.org (full text, mbox):

From: Van L <van <at> scratch.space>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 31576 <at> debbugs.gnu.org
Subject: Re: bug#31576: emacs-lisp-intro.texi - NAME,
 TITLE inconsistency among @node, @unnumberedsec
Date: Sat, 26 May 2018 14:32:31 +1000

> Eli Zaretskii writes:
> 
>> it makes sense why the node name is short, presentation-wise in the infopage. 
> 
> Yes, that's one of the aspects of a good Texinfo usage.
> 
>> A comment saying this is justified at the first instance will help future readers in the texi file.
> 
> I don't think this manual is a place to document that.  How to choose
> good node names is explained in the Texinfo manual, see the node "Node
> Names" there.
> 

diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi
index b79432e..43a8e55 100644
--- a/doc/lispintro/emacs-lisp-intro.texi
+++ b/doc/lispintro/emacs-lisp-intro.texi
@@ -1054,6 +1054,13 @@ Lisp Lists
 * Typing Lists::                How GNU Emacs helps you type lists.
 @end menu
 
+@ignore
+The `node name' and `section title' vary. This is common.  The node
+name is shorter for presentation on Info page only. Further down are
+nodes for `typing lists' and `strange names' for comparison. How to
+choose good node names is explained in the Texinfo manual, see the
+node "Node Names" there.
+@end ignore
 @ifnottex
 @node Numbers Lists
 @unnumberedsubsec Numbers, Lists inside of Lists

Message #32 received at 31576 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Van L <van <at> scratch.space>, 31576 <at> debbugs.gnu.org
Subject: Re: bug#31576: emacs-lisp-intro.texi - NAME, TITLE inconsistency
 among @node, @unnumberedsec
Date: Sun, 6 Oct 2019 06:33:49 +0200

tags 31576 + wontfix
close 31576
quit

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Van L <van <at> scratch.space>
>> Date: Thu, 24 May 2018 10:41:55 +1000
>>
>> Hello.
>>
>> IMO, having `@node NAME' consistent with `@unnumberedsec TITLE' is better in an intro.
>
> I'm not sure I understand why.  This is an introduction to Emacs Lisp,
> not to Texinfo.  All our manuals use different names for nodes and for
> corresponding chapters/sections, primarily because the node name is
> just a label, and also because some characters should not appear ion a
> node name.
>
> I see no problem here.

Having read the discussion, and in the interest of not keeping bug
reports open that we will not want to work on, I'm closing this as
wontfix.

If anyone thinks that's the wrong thing to do, feel free reopen the bug report.

Best regards,
Stefan Kangas

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.