bug#24891: 25.1: Falsehood on page "Major Modes" of Emacs manual.

bug#24891: 25.1: Falsehood on page "Major Modes" of Emacs manual.

[Alan Mackenzie]

Hello, Emacs.

In the Emacs manual, page "Major Modes" appears the following:

    all programming language modes run `prog-mode-hook', prior to
    running their own mode hooks.

This is not true.  A counter example is stand alone CC Mode.  There will
be other examples, too, in code not maintained by Emacs.  I suggest
amending this sentence to something like:

    many programming language modes (including all these distributed
    with Emacs) run `prog-mode-hook', prior to runnuing their own mode
    hooks.

-- 
Alan Mackenzie (Nuremberg, Germany).

bug#24891: 25.1: Falsehood on page "Major Modes" of Emacs manual.

[Drew Adams]

> In the Emacs manual, page "Major Modes" appears the following:
>
>     all programming language modes run `prog-mode-hook', prior to
>     running their own mode hooks.
>
> I suggest amending this sentence to something like:
> 
>     many programming language modes (including all these distributed
>     with Emacs) run `prog-mode-hook', prior to runnuing their own
>     mode hooks.

+1.

But: these -> those,
     runnuing -> running,
     and we can drop the comma before "prior".

And I'm not sure why we need to or should say "(including...)".  Why?

I'd suggest just this:

  many programming language modes run `prog-mode-hook' before
  running their own mode hooks

Or even "some" instead of "many".  What does it matter how
many do this?

bug#24891: 25.1: Falsehood on page "Major Modes" of Emacs manual.

[Evgeny Roubinchtein]

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

Is it the case that the modes that do run prog-mode-hook are exactly the
modes derived from prog-mode?

On Sun, Nov 6, 2016 at 6:19 PM, Drew Adams <drew.adams@oracle.com> wrote:

> > In the Emacs manual, page "Major Modes" appears the following:
> >
> >     all programming language modes run `prog-mode-hook', prior to
> >     running their own mode hooks.
> >
> > I suggest amending this sentence to something like:
> >
> >     many programming language modes (including all these distributed
> >     with Emacs) run `prog-mode-hook', prior to runnuing their own
> >     mode hooks.
>
> +1.
>
> But: these -> those,
>      runnuing -> running,
>      and we can drop the comma before "prior".
>
> And I'm not sure why we need to or should say "(including...)".  Why?
>
> I'd suggest just this:
>
>   many programming language modes run `prog-mode-hook' before
>   running their own mode hooks
>
> Or even "some" instead of "many".  What does it matter how
> many do this?
>
>
>
>
>

[-- Attachment #2: Type: text/html, Size: 1553 bytes --]

bug#24891: 25.1: Falsehood on page "Major Modes" of Emacs manual.

[Dmitry Gutov]

On 07.11.2016 00:18, Alan Mackenzie wrote:

> This is not true.  A counter example is stand alone CC Mode.  There will
> be other examples, too, in code not maintained by Emacs.  I suggest
> amending this sentence to something like:
>
>     many programming language modes (including all these distributed
>     with Emacs) run `prog-mode-hook', prior to runnuing their own mode
>     hooks.

I believe the idea is to equate "programming language mode" with 
"deriving from prog-mode".

To give a strong signal to major mode authors.

bug#24891: 25.1: Falsehood on page "Major Modes" of Emacs manual.

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  >     all programming language modes run `prog-mode-hook', prior to
  >     running their own mode hooks.

  > This is not true.  A counter example is stand alone CC Mode.

Shouldn't we arrange for that to get fixed?

-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.

bug#24891: 25.1: Falsehood on page "Major Modes" of Emacs manual.

[Alan Mackenzie]

Hello, Richard.

On Mon, Nov 07, 2016 at 09:43:29AM -0500, Richard Stallman wrote:
> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]

>   >     all programming language modes run `prog-mode-hook', prior to
>   >     running their own mode hooks.

>   > This is not true.  A counter example is stand alone CC Mode.

> Shouldn't we arrange for that to get fixed?

No, because it's not broken.  One of the purposes of stand alone CC Mode
is to run on versions of (X)Emacs other than the latest Emacs.
Traditionally, define-derived-mode has had defects which have resulted
in bugs revealed by CC Mode - hopefully the last of these has now been
fixed.  So it's handy to have a CC Mode which isn't defined by
define-derived-mode.

The main point of my bug report still stands - there are an unknown
number of programming language modes out there which are not derived
from prog-mode.  This makes the sentence fragment referred to untrue, so
it should be modified.

> -- 
> Dr Richard Stallman
> President, Free Software Foundation (gnu.org, fsf.org)
> Internet Hall-of-Famer (internethalloffame.org)
> Skype: No way! See stallman.org/skype.html.

-- 
Alan Mackenzie (Nuremberg, Germany).

bug#24891: 25.1: Falsehood on page "Major Modes" of Emacs manual.

[Alan Mackenzie]

Hello, Evgeny.

On Sun, Nov 06, 2016 at 06:55:29PM -0500, Evgeny Roubinchtein wrote:
> Is it the case that the modes that do run prog-mode-hook are exactly the
> modes derived from prog-mode?

It is, yes.  It would be sort of nice to put this in the manual, but that
manual is the Emacs manual, not the Elisp manual, where it really
belongs.  Maybe a footnote pointing at the Elisp manual would be the
thing, here.

-- 
Alan Mackenzie (Nuremberg, Germany).

bug#24891: 25.1: Falsehood on page "Major Modes" of Emacs manual.

[Alan Mackenzie]

Hello, Drew.

On Sun, Nov 06, 2016 at 03:19:57PM -0800, Drew Adams wrote:
> > In the Emacs manual, page "Major Modes" appears the following:

> >     all programming language modes run `prog-mode-hook', prior to
> >     running their own mode hooks.

> > I suggest amending this sentence to something like:

> >     many programming language modes (including all these distributed
> >     with Emacs) run `prog-mode-hook', prior to runnuing their own
> >     mode hooks.

> +1.

> But: these -> those,
>      runnuing -> running,

Yes, thanks.

>      and we can drop the comma before "prior".

Maybe, maybe not.  The bit beginning with "prior" isn't qualifying what
comes before, it's adding an extra bit of independent information, so the
comma is justified.

> And I'm not sure why we need to or should say "(including...)".  Why?

I'm told there are users who put things in prog-mode-hook to get effects
in (nearly) all programming modes.  It will avoid confusing them.  Also,
on a purely pragmatic point, the "(including...)" bit is likely to reduce
objections to my proposed change, allowing it to get into Emacs 25.2 more
smoothly.

> I'd suggest just this:

>   many programming language modes run `prog-mode-hook' before
>   running their own mode hooks

> Or even "some" instead of "many".  What does it matter how
> many do this?

"Some" is not incorrect, but it's not quite accurate either.  "Some"
tends to carry connotations of "not that many" in English when a context
hasn't been established.  I think it's the case that most programming
language modes are now derived from prog-mode, so "many" warns users to
be aware of exceptions.

-- 
Alan Mackenzie (Nuremberg, Germany).

bug#24891: 25.1: Falsehood on page "Major Modes" of Emacs manual.

[Drew Adams]

> >      and we can drop the comma before "prior".
> 
> Maybe, maybe not.  The bit beginning with "prior" isn't qualifying
> what comes before, it's adding an extra bit of independent information,
> so the comma is justified.

I don't agree.  It is not an independent clause - it cannot stand
alone.  It is an adverbial clause that qualifies how (when) the modes
run the p-g-m hook.

> > And I'm not sure why we need to or should say "(including...)".
> > Why?
> 
> I'm told there are users who put things in prog-mode-hook to get
> effects in (nearly) all programming modes.  It will avoid confusing
> them.

OK.

> Also, on a purely pragmatic point, the "(including...)" bit is likely to
> reduce objections to my proposed change, allowing it to get into Emacs 25.2
> more smoothly.

;-)

> > I'd suggest just this:
> 
> >   many programming language modes run `prog-mode-hook' before
> >   running their own mode hooks
> 
> > Or even "some" instead of "many".  What does it matter how
> > many do this?
> 
> "Some" is not incorrect, but it's not quite accurate either.  "Some"
> tends to carry connotations of "not that many" in English when a
> context hasn't been established.

Tends to?  No, I don't think so.  Can?  Sure.  But without context
"some" suggests only at least one.  It contrasts with none, not with
many.  "Only some" (esp "only a few"), on the other hand, is as you say.

> I think it's the case that most
> programming language modes are now derived from prog-mode, so "many"
> warns users to be aware of exceptions.

Fair enough.  I'd still use "some", as it tends to have the effect of
soliciting examination of whether to do so (when you write a mode),
and to think about why and why not.  Thinking about whether & why is
more important than how many might use it.

Anyway, these are all minor points, and I don't feel strongly about
any of them.

bug#24891: 25.1: Falsehood on page "Major Modes" of Emacs manual.

[Alan Mackenzie]

Hello, Emacs.

On Sun, Nov 06, 2016 at 10:18:32PM +0000, Alan Mackenzie wrote:

> In the Emacs manual, page "Major Modes" appears the following:

>     all programming language modes run `prog-mode-hook', prior to
>     running their own mode hooks.

> This is not true.  A counter example is stand alone CC Mode.  There will
> be other examples, too, in code not maintained by Emacs.  I suggest
> amending this sentence to something like:

>     many programming language modes (including all these distributed
>     with Emacs) run `prog-mode-hook', prior to runnuing their own mode
>     hooks.

Here's a patch incorporating some of the points other people have made:


diff --git a/doc/emacs/modes.texi b/doc/emacs/modes.texi
index c1564e9..c8da68a 100644
--- a/doc/emacs/modes.texi
+++ b/doc/emacs/modes.texi
@@ -113,7 +113,10 @@ Major Modes
 is enabled in a buffer.  @xref{Hooks}, for more information about
 hooks.  Each mode hook is named after its major mode, e.g., Fortran
 mode has @code{fortran-mode-hook}.  Furthermore, all text-based major
-modes run @code{text-mode-hook}, and all programming language modes
+modes run @code{text-mode-hook}, and many programming language modes
+(including all those distributed with Emacs)@footnote{More
+specifically, the modes which are ''derived'' from @code{prog-mode}
+(@pxref{Derived Modes,,, elisp, The Emacs Lisp Reference Manual}).}
 run @code{prog-mode-hook}, prior to running their own mode hooks.
 Hook functions can look at the value of the variable @code{major-mode}
 to see which mode is actually being entered.


Any objections to me installing this in the Emacs-25 branch?

-- 
Alan Mackenzie (Nuremberg, Germany).

bug#24891: 25.1: Falsehood on page "Major Modes" of Emacs manual.

[Alan Mackenzie]

Hello, Drew.

On Mon, Nov 07, 2016 at 12:51:02PM -0800, Drew Adams wrote:
> > >      and we can drop the comma before "prior".

> > Maybe, maybe not.  The bit beginning with "prior" isn't qualifying
> > what comes before, it's adding an extra bit of independent information,
> > so the comma is justified.

> I don't agree.  It is not an independent clause - it cannot stand
> alone.  It is an adverbial clause that qualifies how (when) the modes
> run the p-g-m hook.

Sorry to keep pounding on at this one, but I see the reason for the comma
now.  It's because the "prior ..." bit applies to the "text-mode-hook"
bit as well as the "prog-mode-hook" bit.  The comma prevents "prior ..."
from attaching exclusively to the "prog-mode-hook" bit.

Anyway, good afternoon (for you), good night (for me)!

[ .... ]

-- 
Alan Mackenzie (Nuremberg, Germany).

bug#24891: 25.1: Falsehood on page "Major Modes" of Emacs manual.

[Alan Mackenzie]

Bug fixed.

-- 
Alan Mackenzie (Nuremberg, Germany).