Common Lisp Emulation vs Common Lisp Extensions

Common Lisp Emulation vs Common Lisp Extensions

[Jean-Christophe Helary]

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 

Re: Common Lisp Emulation vs Common Lisp Extensions

[Eli Zaretskii]

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

Re: Common Lisp Emulation vs Common Lisp Extensions

[Jean-Christophe Helary]

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

Re: Common Lisp Emulation vs Common Lisp Extensions

[Eli Zaretskii]

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

Re: Common Lisp Emulation vs Common Lisp Extensions

[Marcin Borkowski]

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

Re: Common Lisp Emulation vs Common Lisp Extensions

[Jean-Christophe Helary]

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