Re: Common Lisp Emulation vs Common Lisp Extensions

[Eli Zaretskii]

> From: Jean-Christophe Helary <address@hidden>
> 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.