From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: Common Lisp Emulation vs Common Lisp Extensions Date: Sun, 29 May 2016 18:16:44 +0300 Message-ID: <8360twyjvn.fsf@gnu.org> References: <1E868375-1773-40FB-95F5-2E141BA7CCCA@gmail.com> <83r3cmxjf3.fsf@gnu.org> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Trace: ger.gmane.org 1464535017 7539 80.91.229.3 (29 May 2016 15:16:57 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 29 May 2016 15:16:57 +0000 (UTC) Cc: emacs-devel@gnu.org To: Jean-Christophe Helary Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun May 29 17:16:49 2016 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1b72SO-00081H-ET for ged-emacs-devel@m.gmane.org; Sun, 29 May 2016 17:16:48 +0200 Original-Received: from localhost ([::1]:56200 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1b72SK-0004zK-DW for ged-emacs-devel@m.gmane.org; Sun, 29 May 2016 11:16:44 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:35111) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1b72SC-0004z2-VS for emacs-devel@gnu.org; Sun, 29 May 2016 11:16:38 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1b72S7-00073r-Vb for emacs-devel@gnu.org; Sun, 29 May 2016 11:16:35 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:55165) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1b72S7-00073h-SI; Sun, 29 May 2016 11:16:31 -0400 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:3163 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1b72S5-0002Un-N9; Sun, 29 May 2016 11:16:30 -0400 In-reply-to: (message from Jean-Christophe Helary on Sun, 29 May 2016 08:47:07 +0900) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:204129 Archived-At: > From: Jean-Christophe Helary > 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.