[PATCH] Moving Comments node from objects.texi to intro.texi

[PATCH] Moving Comments node from objects.texi to intro.texi

[Joshua Varner]

[-- Attachment #1: Type: text/plain, Size: 1904 bytes --]

When going through objects.texi the oddest part I found,
was the section on comments. To me comments have nothing
to do with objects, and while tangentially related to read syntax
they are not part of any particular object's read syntax.

Since I've only gone through the two files so far, I can only
suggest moving it into intro.texi. This would keep it close to
the beginning of the reference. Below is the old menu from
objects.texi and the menu for where I propose to move the
node in intro.texi. Patch attached, with Changelog entry.

Old placement:

@menu
* Printed Representation::      How Lisp objects are represented as text.
* Comments::                    Comments and their formatting conventions.
* Programming Types::           Types found in all Lisp systems.
* Editing Types::               Types specific to Emacs.
* Circular Objects::            Read syntax for circular structure.
* Type Predicates::             Tests related to types.
* Equality Predicates::         Tests of equality between any two objects.
@end menu

New placement

@menu
* Some Terms::               Explanation of terms we use in this manual.
* nil and t::                How the symbols @code{nil} and @code{t} are used.
* Comments::                    Comments and their formatting conventions.
* Evaluation Notation::      The format we use for examples of evaluation.
* Printing Notation::        The format we use when examples print text.
* Error Messages::           The format we use for examples of errors.
* Buffer Text Notation::     The format we use for buffer contents in examples.
* Format of Descriptions::   Notation for describing functions, variables, etc.
@end menu

To me the node on comments fits more naturally with the
other notation related nodes.

Josh

P.S. I tried to fix the text duplication in the e-mail, hopefully it's
back to normal.

[-- Attachment #2: comments-move.patch --]
[-- Type: application/octet-stream, Size: 2749 bytes --]

Index: ChangeLog
===================================================================
RCS file: /cvsroot/emacs/emacs/lispref/ChangeLog,v
retrieving revision 1.488
diff -r1.488 ChangeLog
0a1,5
> 2005-09-07 Joshua Varner  <jlvarner@gmail.com>
> 
> 	* objects.texi (Comments): Remove node.
> 	* intro.texi (Comments): Add node.
> 	
Index: intro.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/lispref/intro.texi,v
retrieving revision 1.31
diff -r1.31 intro.texi
147a148
> * Comments::                    Comments and their formatting conventions.
213a215,234
> 
> @node Comments
> @section Comments
> @cindex comments
> @cindex @samp{;} in comment
> 
>   A @dfn{comment} is text that is written in a program only for the sake
> of humans that read the program, and that has no effect on the meaning
> of the program.  In Lisp, a semicolon (@samp{;}) starts a comment if it
> is not within a string or character constant.  The comment continues to
> the end of line.  The Lisp reader discards comments; they do not become
> part of the Lisp objects which represent the program within the Lisp
> system.
> 
>   The @samp{#@@@var{count}} construct, which skips the next @var{count}
> characters, is useful for program-generated comments containing binary
> data.  The Emacs Lisp byte compiler uses this in its output files
> (@pxref{Byte Compilation}).  It isn't meant for source files, however.
> 
>   @xref{Comment Tips}, for conventions for formatting comments.
Index: objects.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/lispref/objects.texi,v
retrieving revision 1.48
diff -r1.48 objects.texi
55d54
< * Comments::                    Comments and their formatting conventions.
109,129d107
< 
< @node Comments
< @comment  node-name,  next,  previous,  up
< @section Comments
< @cindex comments
< @cindex @samp{;} in comment
< 
<   A @dfn{comment} is text that is written in a program only for the sake
< of humans that read the program, and that has no effect on the meaning
< of the program.  In Lisp, a semicolon (@samp{;}) starts a comment if it
< is not within a string or character constant.  The comment continues to
< the end of line.  The Lisp reader discards comments; they do not become
< part of the Lisp objects which represent the program within the Lisp
< system.
< 
<   The @samp{#@@@var{count}} construct, which skips the next @var{count}
< characters, is useful for program-generated comments containing binary
< data.  The Emacs Lisp byte compiler uses this in its output files
< (@pxref{Byte Compilation}).  It isn't meant for source files, however.
< 
<   @xref{Comment Tips}, for conventions for formatting comments.

[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel

Re: [PATCH] Moving Comments node from objects.texi to intro.texi

[Thien-Thi Nguyen]

Joshua Varner <jlvarner@gmail.com> writes:

> When going through objects.texi the oddest part I found,
> was the section on comments. To me comments have nothing
> to do with objects, and while tangentially related to read
> syntax they are not part of any particular object's read syntax.

i tend to think that comments belong with objects in the same
way a picture contains both background and foreground.  another
metaphor that comes to mind is that comments is the nil to the
rest of the objects' non-nil; the truth of a piece of code is
not completely describable subtracting one or the other.

thi

Re: [PATCH] Moving Comments node from objects.texi to intro.texi

[Richard M. Stallman]

    When going through objects.texi the oddest part I found,
    was the section on comments. To me comments have nothing
    to do with objects, and while tangentially related to read syntax
    they are not part of any particular object's read syntax.

Comments are part of read syntax, which is why they belong in
objects.texi.  intro.texi describes the conventions of the Emacs Lisp
Manual, not read syntax at all.