some emacs commands at end of file

some emacs commands at end of file

[Allan Adler]

In the C source code to a math package called GAP 3, there are some
emacs commands hidden in a comment at the end of the file, something
like this (I copied this by hand):

/***************************************************
*E  Emacs ................... local emacs variables
**
**  Local Variables:
**  mode: outline
**  outline-regexp: "*A\\|*F\\|*V\\|*T\\|*E"
**  fill-column: 73
**  fill-prefix: "**  "
**  eval: (local-set-key "\t" 'c-indent-command')
**  eval: (local-set-key ";" 'electric-c-semi)
**  eval: (local-set-key "{" 'electric-c-brace)
**  eval: (local-set-key "}" 'electric-c-brace)
**  eval: (hide-body)
**  End:
*/

Because of this stuff at the end of the file, if I run emacs and enter
the file, I get prompted with a y or n question that I don't understand.
If I instead type n to the prompt, I just get the file as it is.
If I type y, then all of the lines in the file that begin with *A,*F,*V,
*T or *E are displayed and none of the other lines. This is a display
that looks like just a few lines. If I go to the beginning of those few lines
and execute M-x set-mark and then go to the end and hit C-W to put them
in the yank buffer, and then go to an empty buffer and hit C-y, instead
of just those lines I get the full contents of the file. So this is all
about display, just smoke and mirrors, not the actual content of the file.

I've been trying to make some sense of these commands, since it seems to
be a very useful technique to be able to display just certain particularly
important lines. Here are some questions:
(1) What exactly is it that causes emacs to treat the material in the
    C comments as commands instead of as text?
(2) At what point does it start and at what point does it end?
(3) Why can't I find everything in the comments in the documentation for
    GNU emacs or in the documentation for GNU emacs lisp?

I have a theory about (3), even though I don't know enough to really have
a theory. My theory is that when it says

mode:  outline

it tells emacs to go into something called outline mode. Maybe an outline
is a selection of particular lines, such as I find displayed when I type
y in reply to the prompt. On the other hand, since it is a C file, maybe
the mode that handles C files has some smarts beyond the formatting of C
that makes it respond to some of these commands. For example, I couldn't
find c-indent-mode or electric-c-semi or electric-c-brace in any of the
documentation, so I'm guessing that maybe they are in the .el file that
tells emacs how to handle C files. Using grep, I found a file c-mode.elc
but no file c-mode.el. So, I guess I need to download c-mode.el for
emacs 20.7 from somewhere and try to read it.

Even if that theory is right, I'm not sure what the respective roles are
of outline mode and C mode in this. I noticed something about major and
minor modes in the elisp documentation but haven't made sense of it yet.
-- 
Ignorantly,
Allan Adler <ara@zurich.csail.mit.edu>
* Disclaimer: I am a guest and *not* a member of the MIT CSAIL. My actions and
* comments do not reflect in any way on MIT. Also, I am nowhere near Boston.

Re: some emacs commands at end of file

[Leo]

On 2007-01-21, Allan Adler said:

> In the C source code to a math package called GAP 3, there are some
> emacs commands hidden in a comment at the end of the file, something
> like this (I copied this by hand):
>
> /***************************************************
> *E  Emacs ................... local emacs variables
> **
> **  Local Variables:
> **  mode: outline
> **  outline-regexp: "*A\\|*F\\|*V\\|*T\\|*E"
> **  fill-column: 73
> **  fill-prefix: "**  "
> **  eval: (local-set-key "\t" 'c-indent-command')
> **  eval: (local-set-key ";" 'electric-c-semi)
> **  eval: (local-set-key "{" 'electric-c-brace)
> **  eval: (local-set-key "}" 'electric-c-brace)
> **  eval: (hide-body)
> **  End:
> */

Check this (info "(emacs)Locals")

-- 
Leo <sdl.web AT gmail.com>                         (GPG Key: 9283AA3F)

Re: some emacs commands at end of file

[Leo]

I mean

(info "(emacs)Specifying File Variables")

-- 
Leo <sdl.web AT gmail.com>                         (GPG Key: 9283AA3F)

Re: some emacs commands at end of file

[Allan Adler]

Leo <sdl.web@gmail.com> writes:

> I mean
> 
> (info "(emacs)Specifying File Variables")

On my system, emacs complains that it can't find it.
-- 
Ignorantly,
Allan Adler <ara@zurich.csail.mit.edu>
* Disclaimer: I am a guest and *not* a member of the MIT CSAIL. My actions and
* comments do not reflect in any way on MIT. Also, I am nowhere near Boston.

Re: some emacs commands at end of file

[Robert Thorpe]

Allan Adler wrote:
> Leo <sdl.web@gmail.com> writes:
>
> > I mean
> >
> > (info "(emacs)Specifying File Variables")
>
> On my system, emacs complains that it can't find it.

Then you are using Emacs 21. Type

(info "(emacs)File Variables")

This is a feature to enable some customization on a per-file basis, so
files that need slightly different treatment can have it.  It sounds as
though the file you have found has abused it to some extent though by
setting things up exactly as some particular person wants.

Re: some emacs commands at end of file

[Allan Adler]

"Robert Thorpe" <rthorpe@realworldtech.com> writes:

> Allan Adler wrote:
> > Leo <sdl.web@gmail.com> writes:
> > > I mean
> > > (info "(emacs)Specifying File Variables")
> > On my system, emacs complains that it can't find it.
> 
> Then you are using Emacs 21. Type
> 
> (info "(emacs)File Variables")

Actually, 20.7, but it works just fine. Thanks.

> This is a feature to enable some customization on a per-file basis, so
> files that need slightly different treatment can have it.  It sounds as
> though the file you have found has abused it to some extent though by
> setting things up exactly as some particular person wants.

It is in source code that is not normally read by anyone but the developers.
-- 
Ignorantly,
Allan Adler <ara@zurich.csail.mit.edu>
* Disclaimer: I am a guest and *not* a member of the MIT CSAIL. My actions and
* comments do not reflect in any way on MIT. Also, I am nowhere near Boston.

Re: some emacs commands at end of file

[Nikos Apostolakis]

Allan Adler <ara@nestle.csail.mit.edu> writes:

> I have a theory about (3), even though I don't know enough to really have
> a theory. My theory is that when it says
>
> mode:  outline
>
> it tells emacs to go into something called outline mode. Maybe an outline
> is a selection of particular lines, such as I find displayed when I type
> y in reply to the prompt.

Your theory is basically correct.  Besides Leo's suggestion you
might want to have a look at: 

,----[ C-h v outline-regexp RET ]
| outline-regexp is a variable defined in `outline.el'.
| Its value is "[*\f]+"
| 
| 
| This variable is safe as a file local variable if its value
| satisfies the predicate `string-or-null-p'.
| 
| Documentation:
| Regular expression to match the beginning of a heading.
| Any line whose beginning matches this regexp is considered to start a heading.
| Note that Outline mode only checks this regexp at the start of a line,
| so the regexp need not (and usually does not) start with `^'.
| The recommended way to set this is with a Local Variables: list
| in the file it applies to.  See also `outline-heading-end-regexp'.
| 
| You can customize this variable.
| 
| [back]
`----

And the info node for outline mode says:

,----[ (info "(emacs) Outline Mode") ]
| Outline mode is a major mode much like Text mode but intended for
| editing outlines.  It allows you to make parts of the text temporarily
| invisible so that you can see the outline structure.  Type `M-x
| outline-mode' to switch to Outline mode as the major mode of the current
| buffer.
| 
|    When Outline mode makes a line invisible, the line does not appear
| on the screen.  The screen appears exactly as if the invisible line
| were deleted, except that an ellipsis (three periods in a row) appears
| at the end of the previous visible line.  (Multiple consecutive
| invisible lines produce just one ellipsis.)
| 
|    Editing commands that operate on lines, such as `C-n' and `C-p',
| treat the text of the invisible line as part of the previous visible
| line.  Killing the ellipsis at the end of a visible line really kills
| all the following invisible lines.
| 
|    Outline minor mode provides the same commands as the major mode,
| Outline mode, but you can use it in conjunction with other major modes.
| Type `M-x outline-minor-mode' to enable the Outline minor mode in the
| current buffer.  You can also specify this in the text of a file, with
| a file local variable of the form `mode: outline-minor' (*note File
| Variables::).
`----

HTH,
Nikos

Re: some emacs commands at end of file

[Allan Adler]

Nikos Apostolakis <nikos.ap@gmail.com> writes:

> Allan Adler <ara@nestle.csail.mit.edu> writes:
> > I have a theory about (3), even though I don't know enough to really have
> > a theory. My theory is that when it says
> >
> > mode:  outline
> >
> > it tells emacs to go into something called outline mode. Maybe an outline
> > is a selection of particular lines, such as I find displayed when I type
> > y in reply to the prompt.
> 
> Your theory is basically correct.

Thanks, that's good to know. So, should I be looking in c-mode.el for the
reason that emacs is able to respond to this

mode:  outline

in what looks like a comment in a C file?

What is the exact point at which emacs stops treating the comment as text
and starts taking commands from it?

> Besides Leo's suggestion you might want to have a look at: 
> 
> ,----[ C-h v outline-regexp RET ]
> | outline-regexp is a variable defined in `outline.el'.
> | Its value is "[*\f]+"

I also tried
C-h v electric-c-semi RET

and it complained that it couldn't find it.
-- 
Ignorantly,
Allan Adler <ara@zurich.csail.mit.edu>
* Disclaimer: I am a guest and *not* a member of the MIT CSAIL. My actions and
* comments do not reflect in any way on MIT. Also, I am nowhere near Boston.

Re: some emacs commands at end of file

[Robert D. Crawford]

Allan Adler <ara@nestle.csail.mit.edu> writes:

> I also tried
> C-h v electric-c-semi RET
>
> and it complained that it couldn't find it.

That's because it is not a variable.  Try C-h f for functions.  

Other help commands you might want to take a look at, especially if one
does not return the information you think it should, as is the case with
what you tried are:

C-h a
apropos

In addition to the C-h v for variables and C-h f for functions.  You can
generally find all the information  you need using one of these commands.

rdc
-- 
Robert D. Crawford                                      rdc1x@comcast.net

The animals are not as stupid as one thinks -- they have neither
doctors nor lawyers.
		-- L. Docquier

Re: some emacs commands at end of file

[Allan Adler]

"Robert D. Crawford" <rdc1x@comcast.net> writes:

> Allan Adler <ara@nestle.csail.mit.edu> writes:
> 
> > I also tried
> > C-h v electric-c-semi RET
> >
> > and it complained that it couldn't find it.
> 
> That's because it is not a variable.  Try C-h f for functions.  

No match.

> Other help commands you might want to take a look at, especially if one
> does not return the information you think it should, as is the case with
> what you tried are:
> 
> C-h a
> apropos

Nothing apropos.

Thanks, however, for reminding me that C-h has all these options.
-- 
Ignorantly,
Allan Adler <ara@zurich.csail.mit.edu>
* Disclaimer: I am a guest and *not* a member of the MIT CSAIL. My actions and
* comments do not reflect in any way on MIT. Also, I am nowhere near Boston.

Re: some emacs commands at end of file

[Robert D. Crawford]

Allan Adler <ara@nestle.csail.mit.edu> writes:

> "Robert D. Crawford" <rdc1x@comcast.net> writes:
>
>> Allan Adler <ara@nestle.csail.mit.edu> writes:
>> 
>> > I also tried
>> > C-h v electric-c-semi RET
>> >
>> > and it complained that it couldn't find it.
>> 
>> That's because it is not a variable.  Try C-h f for functions.  
>
> No match.

Oops.  Sorry about that.  I cannot find this on my system either.  I do,
however have c-electric-semicomma.  It seems that this has been equated
with the function you are looking for at some point.  I guess it is
possible that the name was changed for some reason... consistency maybe?
I do know that the names of things have changed in the past, as the
names of gnus faces were changed in emacs 22.

> Thanks, however, for reminding me that C-h has all these options.

I use them daily.

rdc
-- 
Robert D. Crawford                                      rdc1x@comcast.net

World War Three can be averted by adherence to a strictly enforced dress code!