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

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

[Van L]

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

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

[Eli Zaretskii]

> From: Van L <van@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.

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

[Van L]

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

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

[Eli Zaretskii]

On May 24, 2018 5:47:10 AM GMT+03:00, Van L <van@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.

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

[Van L]

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

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

[Eli Zaretskii]

> From: Van L <van@scratch.space>
> Date: Thu, 24 May 2018 21:51:59 +1000
> Cc: 31576@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.

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

[Van L]

> 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

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

[Van L]

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

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

[Eli Zaretskii]

On May 24, 2018 6:33:34 AM GMT+03:00, Van L <van@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.

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

[Stefan Kangas]

tags 31576 + wontfix
close 31576
quit

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Van L <van@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