* Common Lisp Emulation vs Common Lisp Extensions @ 2016-05-28 13:39 Jean-Christophe Helary 2016-05-28 15:59 ` Eli Zaretskii 0 siblings, 1 reply; 6+ messages in thread From: Jean-Christophe Helary @ 2016-05-28 13:39 UTC (permalink / raw) To: emacs-devel The Elisp Reference points at a "Common Lisp Extensions" document or chapter without specifying where to find that document. Cf. p2 of the PDF (Lisp History) and 6 other references in the manual. It looks like the correct reference is: "GNU Emacs Common Lisp Emulation" according to: http://www.gnu.org/software/emacs/manual/html_mono/cl.html The Emacs Manual uses the same reference (p. 526 of the PDF) It would be good to fix the two manuals to properly reference the document. Also, the web page for the GNU Emacs Manual Online uses "GNU Emacs Common Lisp support." to describe the package and the page that is linked to from there is "CL manual". It seems to me that the first item should be "GNU Emacs Common Lisp *Emulation*" and not "support" and the second should be "GNU Emacs Common Lisp Emulation Manual", or something like that. If the above assumptions are correct, is there a person in particular to address them too, or is there a way to provide a fix myself ? Jean-Christophe Helary ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Common Lisp Emulation vs Common Lisp Extensions 2016-05-28 13:39 Common Lisp Emulation vs Common Lisp Extensions Jean-Christophe Helary @ 2016-05-28 15:59 ` Eli Zaretskii 2016-05-28 23:47 ` Jean-Christophe Helary 0 siblings, 1 reply; 6+ messages in thread From: Eli Zaretskii @ 2016-05-28 15:59 UTC (permalink / raw) To: Jean-Christophe Helary; +Cc: emacs-devel > From: Jean-Christophe Helary <jean.christophe.helary@gmail.com> > Date: Sat, 28 May 2016 22:39:46 +0900 > > The Elisp Reference points at a "Common Lisp Extensions" document or chapter without specifying where to find that document. > > Cf. p2 of the PDF (Lisp History) and 6 other references in the manual. > > It looks like the correct reference is: "GNU Emacs Common Lisp Emulation" according to: > http://www.gnu.org/software/emacs/manual/html_mono/cl.html > > The Emacs Manual uses the same reference (p. 526 of the PDF) > > It would be good to fix the two manuals to properly reference the document. Are you looking at the PDF versions of the manuals, or at HTML versions? Each one has a different title name. The PDF (and the printed version) uses "Common Lisp Extensions", which is what appears on the title page of the printed CL library manual. The HTML version uses the name of the top node, which is "GNU Emacs Common Lisp Emulation". Does this information help to understand the confusion? > Also, the web page for the GNU Emacs Manual Online uses "GNU Emacs Common Lisp support." to describe the package and the page that is linked to from there is "CL manual". I see nothing wrong in the reference, it could be a Texinfo problem in how it processes cross-references for HTML versions. I also don't see "GNU Emacs Common Lisp support.", can you point to it more specifically with a complete URL? In general, for all of the problems you mention, it is better to provide more specific references, like the context or the name of the node/chapter where the reference lives. Otherwise, it is very hard to look for these instances. Thanks. ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Common Lisp Emulation vs Common Lisp Extensions 2016-05-28 15:59 ` Eli Zaretskii @ 2016-05-28 23:47 ` Jean-Christophe Helary 2016-05-29 15:16 ` Eli Zaretskii 0 siblings, 1 reply; 6+ messages in thread From: Jean-Christophe Helary @ 2016-05-28 23:47 UTC (permalink / raw) To: emacs-devel Thank you Eli for the reply. > 2016/05/29 0:59、Eli Zaretskii <eliz@gnu.org> のメール: > >> From: Jean-Christophe Helary <jean.christophe.helary@gmail.com> >> Date: Sat, 28 May 2016 22:39:46 +0900 >> >> The Elisp Reference points at a "Common Lisp Extensions" document or chapter without specifying where to find that document. >> >> Cf. p2 of the PDF (Lisp History) and 6 other references in the manual. >> >> It looks like the correct reference is: "GNU Emacs Common Lisp Emulation" according to: >> http://www.gnu.org/software/emacs/manual/html_mono/cl.html >> >> The Emacs Manual uses the same reference (p. 526 of the PDF) >> >> It would be good to fix the two manuals to properly reference the document. > > Are you looking at the PDF versions of the manuals, As I wrote, I am using the PDF version of the Elisp Reference and of the Emacs Manual. > or at HTML > versions? There is no PDF version for the CL, so I gave the URL. > Each one has a different title name. The PDF (and the > printed version) uses "Common Lisp Extensions", which is what appears > on the title page of the printed CL library manual. When I check here: http://www.gnu.org/software/emacs/manual/cl.html I don't find anything but an HTML version for the CL library. Where did you get your printed version ? > The HTML version > uses the name of the top node, which is "GNU Emacs Common Lisp > Emulation". Indeed, and the table of contents for info gives me "Partial Common Lisp support for Emacs Lisp." In the Elisp nodes I get "See Lists as Sets(cl)" when in the PDF it is "See Section “Lists as Sets” in Common Lisp Extensions." > Does this information help to understand the confusion? Definitely. It is a serious mess :) > >> Also, the web page for the GNU Emacs Manual Online uses "GNU Emacs Common Lisp support." to describe the package and the page that is linked to from there is "CL manual". > > I see nothing wrong in the reference, it could be a Texinfo problem in > how it processes cross-references for HTML versions. I also don't see > "GNU Emacs Common Lisp support.", can you point to it more > specifically with a complete URL? http://www.gnu.org/software/emacs/manual/ Check the description for "CL". > In general, for all of the problems you mention, it is better to > provide more specific references, like the context or the name of the > node/chapter where the reference lives. Otherwise, it is very hard to > look for these instances. I understand. Sorry for the confusion. In the end, it still seems to me that we should have a better reference system and that the media (PDF/info/HTML/print) should not modify the way the reference looks, only the way it is accessed (links for info/html/pdf eventually, formal reference for pdf/print). On a separate note, now that I am checking the info system, I see that the info root menu is not very helpful either. For exemple, instead of having: Emacs * Org Mode Outline-based notes management and organizer * Emacs The extensible self-documenting text editor. etc. Wouldn't it be better to have the actual name of the nodes instead of an abridged name ? When I open "Org Mode", I get: (org)Top Org Mode Manual *************** and below that: * Menu: * Introduction Getting started * Document structure A tree works like your brain Where "Introduction", "Document structure" etc are all the names of their respective nodes. If we applied that to the info root menu we'd have: Emacs * Org Mode Manual Outline-based notes management and organizer * The Emacs Editor The extensible self-documenting text editor. * The GNU Emacs FAQ Frequently Asked Questions about Emacs. and eventually: * GNU Emacs Common Lisp Emulation instead of "CL". Of course that uses a lot more space than the current state of affairs, but that could suggest manual writers to adopt a standard when they name their manuals. Jean-Christophe ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Common Lisp Emulation vs Common Lisp Extensions 2016-05-28 23:47 ` Jean-Christophe Helary @ 2016-05-29 15:16 ` Eli Zaretskii 2016-05-29 20:20 ` Marcin Borkowski 2016-05-30 5:33 ` Jean-Christophe Helary 0 siblings, 2 replies; 6+ messages in thread From: Eli Zaretskii @ 2016-05-29 15:16 UTC (permalink / raw) To: Jean-Christophe Helary; +Cc: emacs-devel > From: Jean-Christophe Helary <jean.christophe.helary@gmail.com> > Date: Sun, 29 May 2016 08:47:07 +0900 > > > Are you looking at the PDF versions of the manuals, > > As I wrote, I am using the PDF version of the Elisp Reference and of the Emacs Manual. > > > or at HTML > > versions? > > There is no PDF version for the CL, so I gave the URL. But the consistency is only kept in across manuals in the same format. So if you look for consistency between a PDF version of one manual and an HTML version of another, you won't find it. > When I check here: > http://www.gnu.org/software/emacs/manual/cl.html > > I don't find anything but an HTML version for the CL library. Where did you get your printed version ? I didn't (although one can generate it from the sources, of course). I just looked at the Texinfo sources and saw this: @titlepage @sp 6 @center @titlefont{Common Lisp Extensions} @sp 4 @center For GNU Emacs Lisp @sp 1 @center as distributed with Emacs @value{EMACSVER} @sp 5 @center Dave Gillespie @center daveg@@synaptics.com @page @vskip 0pt plus 1filll @insertcopying @end titlepage This describes the title page of the printed manual for CL, and it says that the title is "Common Lisp Extensions". > > The HTML version > > uses the name of the top node, which is "GNU Emacs Common Lisp > > Emulation". > > Indeed, and the table of contents for info gives me "Partial Common Lisp support for Emacs Lisp." > > In the Elisp nodes I get "See Lists as Sets(cl)" when in the PDF it is "See Section “Lists as Sets” in Common Lisp Extensions." That's expected, see the Texinfo manual. The way cross-references are formatted for on-line and printed versions is different. > > Does this information help to understand the confusion? > > Definitely. It is a serious mess :) I don't think I see the mess. You are looking for identical text where there shouldn't be one. The assumption is that the reader uses the same format consistently for all the manuals. This assumption is at the basis of the Texinfo documentation system, and has nothing to do with Emacs the project. We just use Texinfo, that's all. > >> Also, the web page for the GNU Emacs Manual Online uses "GNU Emacs Common Lisp support." to describe the package and the page that is linked to from there is "CL manual". > > > > I see nothing wrong in the reference, it could be a Texinfo problem in > > how it processes cross-references for HTML versions. I also don't see > > "GNU Emacs Common Lisp support.", can you point to it more > > specifically with a complete URL? > > http://www.gnu.org/software/emacs/manual/ > > Check the description for "CL". That comes from the top-level menu of the Texinfo system, and is taken from this line of cl.texi, the Texinfo source of the CL manual: @dircategory Emacs lisp libraries @direntry * CL: (cl). Partial Common Lisp support for Emacs Lisp. @end direntry > In the end, it still seems to me that we should have a better reference system and that the media (PDF/info/HTML/print) should not modify the way the reference looks, only the way it is accessed (links for info/html/pdf eventually, formal reference for pdf/print). Each format serves its own purpose, so they don't necessarily have to say the same. > On a separate note, now that I am checking the info system, I see that the info root menu is not very helpful either. > > For exemple, instead of having: > > Emacs > * Org Mode Outline-based notes management and organizer > * Emacs The extensible self-documenting text editor. > > etc. > > Wouldn't it be better to have the actual name of the nodes instead of an abridged name ? > > When I open "Org Mode", I get: > > (org)Top > > Org Mode Manual > *************** > > and below that: > > * Menu: > > * Introduction Getting started > * Document structure A tree works like your brain > > Where "Introduction", "Document structure" etc are all the names of their respective nodes. > > If we applied that to the info root menu we'd have: > > Emacs > * Org Mode Manual Outline-based notes management and organizer > * The Emacs Editor The extensible self-documenting text editor. > * The GNU Emacs FAQ Frequently Asked Questions about Emacs. > > and eventually: > > * GNU Emacs Common Lisp Emulation > > instead of "CL". > > Of course that uses a lot more space than the current state of affairs, but that could suggest manual writers to adopt a standard when they name their manuals. This top-level menu serves a slightly different purpose: it strives to provide a short description of each topic so that the reader could make up her mind whether this item is what she is looking for. Blindly repeating the respective text from the corresponding manual won't necessarily achieve that goal. ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Common Lisp Emulation vs Common Lisp Extensions 2016-05-29 15:16 ` Eli Zaretskii @ 2016-05-29 20:20 ` Marcin Borkowski 2016-05-30 5:33 ` Jean-Christophe Helary 1 sibling, 0 replies; 6+ messages in thread From: Marcin Borkowski @ 2016-05-29 20:20 UTC (permalink / raw) To: Eli Zaretskii; +Cc: Jean-Christophe Helary, emacs-devel On 2016-05-29, at 17:16, Eli Zaretskii <eliz@gnu.org> wrote: > I don't think I see the mess. You are looking for identical text > where there shouldn't be one. The assumption is that the reader uses > the same format consistently for all the manuals. This assumption is > at the basis of the Texinfo documentation system, and has nothing to > do with Emacs the project. We just use Texinfo, that's all. FWIW, I am a counterexample proving that that assumption is false. I might read the Emacs Lisp Intro on my ebook reader (using a version converted from HTML), then consult the Emacs Lisp Reference in an Info buffer, and print out parts of the Emacs Manual from a pdf. Not that I did it all in this way, but it _might_ be that way (and indeed I used all three of those formats - Info, pdf and HTML - at some point in time). Best, -- Marcin Borkowski http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski Faculty of Mathematics and Computer Science Adam Mickiewicz University ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Common Lisp Emulation vs Common Lisp Extensions 2016-05-29 15:16 ` Eli Zaretskii 2016-05-29 20:20 ` Marcin Borkowski @ 2016-05-30 5:33 ` Jean-Christophe Helary 1 sibling, 0 replies; 6+ messages in thread From: Jean-Christophe Helary @ 2016-05-30 5:33 UTC (permalink / raw) To: emacs-devel Maybe my first mail was confusing so let me restart the discussion from scratch. I've checked the texi sources for the CL manual, the Emacs manual and the Elisp reference and the main discrepancy I find is the following (which explains the issue I had finding the CL references): 1) CL manual The info source is: @settitle Common Lisp Extensions and @ifnottex @node Top @top GNU Emacs Common Lisp Emulation 2) Emacs manual The info source is: @settitle GNU Emacs Manual and @ifnottex @node Top @top The Emacs Editor 3) Elisp reference The info source is: @settitle GNU Emacs Lisp Reference Manual and @ifnottex @node Top @top Emacs Lisp If we consider that the Emacs manual and the Elisp reference set a practice standard, the CL manual should use the following source: @settitle GNU Emacs Common Lisp Emulation and @ifnottex @node Top @top Common Lisp Extensions Also, (after checking the manual) since *extensions* to the Common Lisp standard are only a small part of the CL manual contents, "Common Lisp Extensions" should be reworded as "Common Lisp Emulation", and that would increase the consistency in the whole documentation. So, let's suppose the CL manual follows that suggestion: @settitle GNU Emacs Common Lisp Emulation and @ifnottex @node Top @top Common Lisp Emulation The only pointer to the CL manual in the Emacs manual could be written as: @xref{Top,,Overview,cl,GNU Emacs Common Lisp Emulation} and be rendered in info as: See Overview(cl) and in PDF as: See Section Overview in GNU Emacs Common Lisp Emulation and the 6 Elisp Reference pointers to the CL manual could similarly be rewritten as: @xref{Section Name,,,cl,GNU Emacs Common Lisp Emulation} for a PDF rendering of: See Section “Section Name” in GNU Emacs Common Lisp Emulation and in info: See Section Name(cl) "Common Lisp Emulation" would be used as the main title in the HTML (as <h1>), and as the info top page title. Last but not least, the info manual top node displays: * CL Partial Common Lisp support for Emacs Lisp. which comes from: @direntry * CL: (cl). Partial Common Lisp support for Emacs Lisp. @end direntry Could be changed to "Partial Common Lisp emulation for Emacs Lisp" to increase consistency. On a side note regarding that info manual top node, the entries are really not consistent. * Org Mode Outline-based notes management and organizer → does not end with a period * Emacs The extensible self-documenting text editor. → we know what Emacs is, is the document the manual or not ? * Emacs FAQ Frequently Asked Questions about Emacs. → good enough * Elisp The Emacs Lisp Reference Manual. → good enough * Emacs Lisp Intro A simple introduction to Emacs Lisp programming. → good enough * Ada mode Emacs mode for editing and compiling Ada code. → we know it is a mode and that it is for Emacs, also the mode does not "compile" since it requires an external compiler * CC Mode Emacs mode for editing C, C++, Objective-C, Java, Pike, AWK, and CORBA IDL code. → we know it is an Emacs mode etc. It would be good to have general rules for Emacs related documentation to add consistency to the set. Jean-Christophe ^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2016-05-30 5:33 UTC | newest] Thread overview: 6+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2016-05-28 13:39 Common Lisp Emulation vs Common Lisp Extensions Jean-Christophe Helary 2016-05-28 15:59 ` Eli Zaretskii 2016-05-28 23:47 ` Jean-Christophe Helary 2016-05-29 15:16 ` Eli Zaretskii 2016-05-29 20:20 ` Marcin Borkowski 2016-05-30 5:33 ` Jean-Christophe Helary
Code repositories for project(s) associated with this external index https://git.savannah.gnu.org/cgit/emacs.git https://git.savannah.gnu.org/cgit/emacs/org-mode.git This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.