Re: Common Lisp Emulation vs Common Lisp Extensions

[Jean-Christophe Helary <jean.christophe.helary@gmail.com>]

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