* bug#31576: emacs-lisp-intro.texi - NAME, TITLE inconsistency among @node, @unnumberedsec
@ 2018-05-24 0:41 Van L
2018-05-24 2:38 ` Eli Zaretskii
2019-10-06 4:33 ` Stefan Kangas
0 siblings, 2 replies; 10+ messages in thread
From: Van L @ 2018-05-24 0:41 UTC (permalink / raw)
To: 31576
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
^ permalink raw reply [flat|nested] 10+ messages in thread* bug#31576: emacs-lisp-intro.texi - NAME, TITLE inconsistency among @node, @unnumberedsec
2018-05-24 0:41 bug#31576: emacs-lisp-intro.texi - NAME, TITLE inconsistency among @node, @unnumberedsec Van L
@ 2018-05-24 2:38 ` Eli Zaretskii
2018-05-24 2:47 ` Van L
2018-05-24 3:33 ` Van L
2019-10-06 4:33 ` Stefan Kangas
1 sibling, 2 replies; 10+ messages in thread
From: Eli Zaretskii @ 2018-05-24 2:38 UTC (permalink / raw)
To: Van L; +Cc: 31576
> 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.
^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#31576: emacs-lisp-intro.texi - NAME, TITLE inconsistency among @node, @unnumberedsec
2018-05-24 2:38 ` Eli Zaretskii
@ 2018-05-24 2:47 ` Van L
2018-05-24 4:35 ` Eli Zaretskii
2018-05-24 3:33 ` Van L
1 sibling, 1 reply; 10+ messages in thread
From: Van L @ 2018-05-24 2:47 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 31576
> 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.
^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#31576: emacs-lisp-intro.texi - NAME, TITLE inconsistency among @node, @unnumberedsec
2018-05-24 2:47 ` Van L
@ 2018-05-24 4:35 ` Eli Zaretskii
2018-05-24 11:51 ` Van L
0 siblings, 1 reply; 10+ messages in thread
From: Eli Zaretskii @ 2018-05-24 4:35 UTC (permalink / raw)
To: Van L; +Cc: 31576
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.
^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#31576: emacs-lisp-intro.texi - NAME, TITLE inconsistency among @node, @unnumberedsec
2018-05-24 4:35 ` Eli Zaretskii
@ 2018-05-24 11:51 ` Van L
2018-05-24 15:33 ` Eli Zaretskii
0 siblings, 1 reply; 10+ messages in thread
From: Van L @ 2018-05-24 11:51 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 31576
> 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.
^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#31576: emacs-lisp-intro.texi - NAME, TITLE inconsistency among @node, @unnumberedsec
2018-05-24 11:51 ` Van L
@ 2018-05-24 15:33 ` Eli Zaretskii
2018-05-26 4:32 ` Van L
0 siblings, 1 reply; 10+ messages in thread
From: Eli Zaretskii @ 2018-05-24 15:33 UTC (permalink / raw)
To: Van L; +Cc: 31576
> 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.
^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#31576: emacs-lisp-intro.texi - NAME, TITLE inconsistency among @node, @unnumberedsec
2018-05-24 15:33 ` Eli Zaretskii
@ 2018-05-26 4:32 ` Van L
0 siblings, 0 replies; 10+ messages in thread
From: Van L @ 2018-05-26 4:32 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 31576
> 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
^ permalink raw reply related [flat|nested] 10+ messages in thread
* bug#31576: emacs-lisp-intro.texi - NAME, TITLE inconsistency among @node, @unnumberedsec
2018-05-24 2:38 ` Eli Zaretskii
2018-05-24 2:47 ` Van L
@ 2018-05-24 3:33 ` Van L
2018-05-24 4:29 ` Eli Zaretskii
1 sibling, 1 reply; 10+ messages in thread
From: Van L @ 2018-05-24 3:33 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 31576
> 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’.
^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#31576: emacs-lisp-intro.texi - NAME, TITLE inconsistency among @node, @unnumberedsec
2018-05-24 3:33 ` Van L
@ 2018-05-24 4:29 ` Eli Zaretskii
0 siblings, 0 replies; 10+ messages in thread
From: Eli Zaretskii @ 2018-05-24 4:29 UTC (permalink / raw)
To: Van L; +Cc: 31576
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.
^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#31576: emacs-lisp-intro.texi - NAME, TITLE inconsistency among @node, @unnumberedsec
2018-05-24 0:41 bug#31576: emacs-lisp-intro.texi - NAME, TITLE inconsistency among @node, @unnumberedsec Van L
2018-05-24 2:38 ` Eli Zaretskii
@ 2019-10-06 4:33 ` Stefan Kangas
1 sibling, 0 replies; 10+ messages in thread
From: Stefan Kangas @ 2019-10-06 4:33 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: Van L, 31576
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
^ permalink raw reply [flat|nested] 10+ messages in thread
end of thread, other threads:[~2019-10-06 4:33 UTC | newest]
Thread overview: 10+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2018-05-24 0:41 bug#31576: emacs-lisp-intro.texi - NAME, TITLE inconsistency among @node, @unnumberedsec Van L
2018-05-24 2:38 ` Eli Zaretskii
2018-05-24 2:47 ` Van L
2018-05-24 4:35 ` Eli Zaretskii
2018-05-24 11:51 ` Van L
2018-05-24 15:33 ` Eli Zaretskii
2018-05-26 4:32 ` Van L
2018-05-24 3:33 ` Van L
2018-05-24 4:29 ` Eli Zaretskii
2019-10-06 4:33 ` Stefan Kangas
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).