From: Jean-Christophe Helary <jean.christophe.helary@gmail.com>
To: emacs-devel <emacs-devel@gnu.org>
Subject: Re: Common Lisp Emulation vs Common Lisp Extensions
Date: Mon, 30 May 2016 14:33:47 +0900 [thread overview]
Message-ID: <6DF2DAEE-D008-41CA-AD9B-4CDD275B2F3C@gmail.com> (raw)
In-Reply-To: <8360twyjvn.fsf@gnu.org>
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
prev parent reply other threads:[~2016-05-30 5:33 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
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 [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=6DF2DAEE-D008-41CA-AD9B-4CDD275B2F3C@gmail.com \
--to=jean.christophe.helary@gmail.com \
--cc=emacs-devel@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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.