[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Common Lisp Emulation vs Common Lisp Extensions
From: |
Jean-Christophe Helary |
Subject: |
Re: Common Lisp Emulation vs Common Lisp Extensions |
Date: |
Mon, 30 May 2016 14:33:47 +0900 |
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