Major and minor modes

Major and minor modes

[M.R.P.]

Can anyone explain to me clearly how Major modes and minor modes work 
together. Can any minor mode work within any major mode? How do these 
work together?

Re: Major and minor modes

[Jean-Christophe Helary]

> On Jun 14, 2017, at 8:58, M.R.P. <wintermute24x7@icloud.com> wrote:
> 
> Can anyone explain to me clearly how Major modes and minor modes work together. Can any minor mode work within any major mode? How do these work together?

Everything is explained in Chapter 20 of the Emacs Manual.

Jean-Christophe 

RE: Major and minor modes

[Drew Adams]

> > Can anyone explain to me clearly how Major modes and minor modes work
> together. Can any minor mode work within any major mode? How do these work
> together?
> 
> Everything is explained in Chapter 20 of the Emacs Manual.

Depends what Emacs version you use.  For versions 24 and 25
it is chapter 23, "Major and Minor Modes".  For version 23
it is chapter 27, "Major Modes" and section and 57.1, "Minor
Modes".  It is here:
http://www.gnu.org/software/emacs/manual/html_node/emacs/Modes.html

In sum, a major mode is buffer-specific.
As such, it typically does something appropriate for that
buffer content.

A minor mode can be buffer-specific (local) or not (global).
Minor-mode key bindings override major-mode key bindings.
A minor mode can do anything at all.  What it does need not
be specific for the content of any particular buffer, and
hence for any particular major mode.

Re: Major and minor modes

[Emanuel Berg]

M.R.P. wrote:

> Can anyone explain to me clearly how Major
> modes and minor modes work together. Can any
> minor mode work within any major mode?

In general, the major mode is the big frame
and there is one and only one major mode to
help you edit the text in the buffer. So for C,
it is C/l defined in cc-mode.el, and so on.

The minor mode is a small piece of
functionality, like Line-Number to have the
current line shown in the mode bar. It is
a good thing it can be used in all but whatever
major mode so it doesn't have to be duplicated.

In principle I suppose you can have as many
minor modes as you want for any major mode but
it isn't difficult to predict a scenario where
the minor modes contradict each other and/or
work in opposite ways to what makes sense for
the underlying major mode.

I never heard of anyone putting up fences in
their code to prevent that, and it is a good
thing they didn't as that would make all code
interdependent and besides people aren't that
stupid to setup a system that doesn't make
sense anyway. And if they are, let's go
nuts already.

-- 
underground experts united
http://user.it.uu.se/~embe8573

Re: Major and minor modes

[Jean-Christophe Helary]

> On Jun 14, 2017, at 10:49, Drew Adams <drew.adams@oracle.com> wrote:
> 
>>> Can anyone explain to me clearly how Major modes and minor modes work
>> together. Can any minor mode work within any major mode? How do these work
>> together?
>> 
>> Everything is explained in Chapter 20 of the Emacs Manual.
> 
> Depends what Emacs version you use.  For versions 24 and 25
> it is chapter 23, "Major and Minor Modes".  For version 23
> it is chapter 27, "Major Modes" and section and 57.1, "Minor
> Modes".

Interesting. I just noticed that the HTML and the PDF do not have the same chapter numbering.

The PDF for 24.5 and for 26.0.50 (that I built this morning) both use chapter 20 for modes.

Jean-Christophe 

Re: Major and minor modes

[Emanuel Berg]

Jean-Christophe Helary
<jean.christophe.helary@gmail.com> writes:

> Interesting. I just noticed that the HTML and the
> PDF do not have the same chapter numbering.
>
> The PDF for 24.5 and for 26.0.50 (that I built this
> morning) both use chapter 20 for modes.

Better to use the built-in info Emacs manual. Then you
can't go wrong :)

-- 
underground experts united
http://user.it.uu.se/~embe8573

Re: Major and minor modes

[Emanuel Berg]

Drew Adams <drew.adams@oracle.com> writes:

> A minor mode can be buffer-specific (local) or not
> (global). Minor-mode key bindings override
> major-mode key bindings.

Good point. This goes against the intuition of some
people who think what is bigger should be the boss,
period.

One can think of it like a compass needle. It works on
the magneticism of Earth itself. However put a small
magnet next to it, and it will override the entire
planet! It is thoughtworthy.

I suppose the "size" in this matter isn't the size
alone but also the *proximity*, just like with Emacs
major and minor modes, the minor mode being closer to
the user...

-- 
underground experts united
http://user.it.uu.se/~embe8573

Re: Major and minor modes

[Krishnakant]

Read my blog at https://digitallyfreeblog.wordpress.com/

Hopefully you will get more clarity on that subject.

Happy hacking.

Krishnakant.


On Wednesday 14 June 2017 07:19 AM, Drew Adams wrote:
>>> Can anyone explain to me clearly how Major modes and minor modes work
>> together. Can any minor mode work within any major mode? How do these work
>> together?
>>
>> Everything is explained in Chapter 20 of the Emacs Manual.
> Depends what Emacs version you use.  For versions 24 and 25
> it is chapter 23, "Major and Minor Modes".  For version 23
> it is chapter 27, "Major Modes" and section and 57.1, "Minor
> Modes".  It is here:
> http://www.gnu.org/software/emacs/manual/html_node/emacs/Modes.html
>
> In sum, a major mode is buffer-specific.
> As such, it typically does something appropriate for that
> buffer content.
>
> A minor mode can be buffer-specific (local) or not (global).
> Minor-mode key bindings override major-mode key bindings.
> A minor mode can do anything at all.  What it does need not
> be specific for the content of any particular buffer, and
> hence for any particular major mode.
>

RE: Major and minor modes

[Phillip Lord]

On Wed, June 14, 2017 1:49 am, Drew Adams wrote:
> A minor mode can be buffer-specific (local) or not (global).
> Minor-mode key bindings override major-mode key bindings.
> A minor mode can do anything at all.  What it does need not
> be specific for the content of any particular buffer, and hence for any
> particular major mode.


I have thought for a long time that there are two forms of minor mode
which should be handled differently. Originally minor modes were clearly
meant to be global (auto-fill, line-number mode that sort of thing). But
there are lots of "single major mode" minor modes. Examples would be some
of the electric minor modes, things like Slime, CIDER or ensime which are
all minor modes more or less specific.

My own feeling is that minor modes have poor usability for these purposes.

Phil

Re: Major and minor modes

[Héctor Lahoz]

Emanuel Berg wrote:
> In principle I suppose you can have as many
> minor modes as you want for any major mode but
> it isn't difficult to predict a scenario where
> the minor modes contradict each other and/or
> work in opposite ways to what makes sense for
> the underlying major mode.
> 
> I never heard of anyone putting up fences in
> their code to prevent that, and it is a good
> thing they didn't as that would make all code
> interdependent and besides people aren't that
> stupid to setup a system that doesn't make
> sense anyway. And if they are, let's go
> nuts already.

Interesting matter. I have never thought of it
thoroughly but it seems it is more difficult
to write a minor mode. Because a minor mode
doesn't know what other minor modes are in
effect when it is running (environment).

Then I have this question. One major mode is
suitable for a type of data. Everything is text
but it is formatted differently. Usually in the
same buffer you have several sections with
different types. So, for example, you could have
some C code, then some text and then an ASCII
picture. What I do is changing the major mode
as I edit the different sections. Is there
some way to tell Emacs what major mode should
be used for each section so it can switch the mode
automatically when point enters that section?

Besides, major modes usually handle the buffer
as a whole thing for parsing and that stuff.

Re: Major and minor modes

[Emanuel Berg]

Héctor Lahoz <hectorlahoz@gmail.com> writes:

> Interesting matter. I have never thought of it
> thoroughly but it seems it is more difficult to
> write a minor mode. Because a minor mode doesn't
> know what other minor modes are in effect when it is
> running (environment).

They typically don't need to care about that because
it isn't that complicated. It is often a small piece
of functionality and the more isolated it can be the
better, and often it isn't difficult to do as it is
completely natural so you don't even think about it.

> Then I have this question. One major mode is
> suitable for a type of data. Everything is text but
> it is formatted differently. Usually in the same
> buffer you have several sections with different
> types. So, for example, you could have some C code,
> then some text and then an ASCII picture. What I do
> is changing the major mode as I edit the different
> sections. Is there some way to tell Emacs what major
> mode should be used for each section so it can
> switch the mode automatically when point enters
> that section?

There are solutions to deal with that but those are
exceptions. You keep the C source and the ASCII
picture apart. This is the same as above. It is sound
preceding. It makes everything more easy,
including Emacs.

-- 
underground experts united
http://user.it.uu.se/~embe8573

Re: Major and minor modes

[tomas]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Wed, Jun 14, 2017 at 10:19:01AM +0200, Emanuel Berg wrote:

[...]

> > Then I have this question. One major mode is
> > suitable for a type of data. Everything is text but
> > it is formatted differently. Usually in the same
> > buffer you have several sections with different
> > types [...]

> There are solutions to deal with that but those are
> exceptions [...]
 
This is a well-known problem for those poor souls dealing
with "things Web", where you have nested languages (CSS
and Javascript in HTML, HTML in PHP and things). Thus,
several approaches to the problem of "multiple major modes"
have developed. But yes, that's a point where we might
need a more "fundamental" solution.

See https://www.emacswiki.org/emacs/MultipleModes

For another, somewhat refreshing, but different approach
(embedding snippets of code in many languages in some text,
and getting the results of executing those snippets back
into the text, the whole literate programming kaboodle),
start, e.g. here: http://orgmode.org/worg/org-contrib/babel/

Careful! this one has rabbit-hole quality ;-)

Cheers
- -- t
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.12 (GNU/Linux)

iEYEARECAAYFAllA+RUACgkQBcgs9XrR2kZ4dACcCNbQMKUzRgcmjoqZSdiQcdOE
LpwAn35uKBxojdDn4WkwQ25/1Bb5GpNt
=ijLS
-----END PGP SIGNATURE-----

Re: Major and minor modes

[Emanuel Berg]

> This is a well-known problem for those poor
> souls dealing with "things Web", where you
> have nested languages (CSS and Javascript in
> HTML, HTML in PHP and things)

You said it: poor souls.

Is it unavoidable to nest languages? PHP I see
the situation because it produces HTML from
inline code. With CSS tho isn't a reference in
the HTML file enough?

Another example are Perl scripts to do
databases and have SQL commands executed.
That shouldn't be necessary tho as Perl is
a programming language and surely can just as
well extract those command from designated
seekwell files...

JavaScript obviously I only did at computer
school and as soon as it was done I drank ten
beers to make sure I forgot all about it...

-- 
underground experts united
http://user.it.uu.se/~embe8573

Re: Major and minor modes

[Emanuel Berg]

Another thing to note is that the major mode is
just a tool, a good tool, but not a necessary
tool for every lite code snippet.

Here (last) is an example. It is a zsh wrapper
to some awk code that I found on the net.
Of course, that made the need for awk-mode even
smaller. But I did edit the awk, in the
Shell-script[zsh] mode, without even thinking
about not being in awk-mode.

And that is actually a good rule of thumb.
When you experience not being in the right mode
is a disadvantage to your work, then you should
think of a way to factor out the foreign code.

numbers () {
    # thank you: https://unix.stackexchange.com/a/13779
    echo "items\tsum\tlow\thigh\tmedian\tmean"
    sort -n | awk '
          BEGIN {
            c = 0;
            sum = 0;
          }
          $1 ~ /^[0-9]*(\.[0-9]*)?$/ {
            a[c++] = $1;
            sum += $1;
          }
          END {
            ave = int(sum/c) + 1;
            if ( (c % 2) == 1 ) {
              median = a[ int(c/2) ];
            } else {
              median = ( a[c/2] + a[c/2-1] ) / 2;
            }
            OFS="\t";
            print c, sum, a[0], a[c-1], median, ave
          }
        '
}

-- 
underground experts united
http://user.it.uu.se/~embe8573

Re: Major and minor modes

[tomas]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Wed, Jun 14, 2017 at 11:25:07AM +0200, Emanuel Berg wrote:
> > This is a well-known problem for those poor
> > souls dealing with "things Web", where you
> > have nested languages (CSS and Javascript in
> > HTML, HTML in PHP and things)
> 
> You said it: poor souls.

But very subjective anyway. I half-regret having said that.

> Is it unavoidable to nest languages?

No. Is it unavoidable to use computers? No. Some like doing
that, though.

> PHP I see the situation because it produces HTML
> from inline code. With CSS tho isn't a reference
> in the HTML file enough?

Yes. Does the standard allow embedding? Yes. Some people like
doing it differently, and luckily, neither you nor me are entitled
(or empowered) to impose that.

Moreover, in this case, if you want to understand some random
page you got from the Web (assuming you want to stay with your
beloved Emacs), mixed-mode will come in handy. I know I appreciate
it, for sure.

> Another example are Perl scripts to do
> databases and have SQL commands executed.

There are tons of those -- everything "domain specific language"
goes a bit in that direction.

> JavaScript obviously I only did at computer
> school and as soon as it was done I drank ten
> beers to make sure I forgot all about it...

Don't underestimate Javascript. There's a lot to learn from that
(in the negative, but also in the positive).

Actually... don't underestimate anything ;-D

Cheers
- -- t
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.12 (GNU/Linux)

iEYEARECAAYFAllBCN4ACgkQBcgs9XrR2kYarQCdEM+KuWUrvyUA+xKXaCw5m3uM
vtMAnAy4qjoK6yW2FNau/YujixJMLmo/
=L3Vn
-----END PGP SIGNATURE-----

Re: Major and minor modes

[Emanuel Berg]

> Don't underestimate Javascript. There's a lot
> to learn from that (in the negative, but also
> in the positive).

Sure - it is like "Old English". If you drink
enough of it, you start to like it...

-- 
underground experts united
http://user.it.uu.se/~embe8573

Re: Major and minor modes

[Emanuel Berg]

<tomas@tuxteam.de> writes:

> Moreover, in this case, if you want to understand
> some random page you got from the Web (assuming you
> want to stay with your beloved Emacs), mixed-mode
> will come in handy. I know I appreciate it,
> for sure.

As for me, in the world of computers and in other
worlds as well, putting up with stuff that isn't to my
liking by tweaking tools only delay the inevitable
blow-up and failure.

If you don't like the way the dig is going, getting
the best shovels will not keep frustration at bay
for long.

> There are tons of those -- everything "domain
> specific language" goes a bit in that direction.

... - how exactly do you define that?

I always thought of Elisp, SQL, LaTeX, the dialects of
BASIC, etc. to be domain specific.

And I didn't mix up major modes every doing that!

-- 
underground experts united
http://user.it.uu.se/~embe8573

Re: Major and minor modes

[Emanuel Berg]

Emanuel Berg <moasen@zoho.com> writes:

>> There are tons of those -- everything "domain
>> specific language" goes a bit in that direction.
>
> ... - how exactly do you define that?
>
> I always thought of Elisp, SQL, LaTeX, the dialects
> of BASIC, etc. to be domain specific.

Perhaps one should make a distinction between
"platform specific" and "domain specific"?

LaTeX is domain specific to documents and SQL is
domain specific to databases.

But Elisp, while platform specific to Emacs, the
domain is limited only in the Turing sense, which
I never pretended to understand anyway (except for on
exam day).

-- 
underground experts united
http://user.it.uu.se/~embe8573

Re: Major and minor modes

[tomas]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Wed, Jun 14, 2017 at 01:39:55PM +0200, Emanuel Berg wrote:
> <tomas@tuxteam.de> writes:
> 
> > Moreover, in this case, if you want to understand
> > some random page you got from the Web (assuming you
> > want to stay with your beloved Emacs), mixed-mode
> > will come in handy. I know I appreciate it,
> > for sure.
> 
> As for me, in the world of computers and in other
> worlds as well, putting up with stuff that isn't to my
> liking by tweaking tools only delay the inevitable
> blow-up and failure.

But you don't want to be at the mercy of websites out
there, do you? So best to have a sharp sword to slice
them in half, when they come, bouncing and throbbing
upon you (sorry for the somewhat disturbing imagery).

I haven't resigned to see the web out there *only*
through the browser, although it seems we are losing
this battle at the moment (the only serious browser
manufacturer out there is at the same time the dominant
ad placement seller: what can possibly go wrong?)

> If you don't like the way the dig is going, getting
> the best shovels will not keep frustration at bay
> for long.

Cannons! Big, loaded cannons. Not shovels. Some AI
to unravel the secret protocol going on between their
server and the disgusting blob of Javascript they just
sent me to execute on *my* computer ;-) 

> > There are tons of those -- everything "domain
> > specific language" goes a bit in that direction.
> 
> ... - how exactly do you define that?
> 
> I always thought of Elisp, SQL, LaTeX, the dialects of
> BASIC, etc. to be domain specific.

Regular expressions. Date-time formats. Query languages à la
miniKanren. HTTP query strings. CSS selectors. GraphViz graph
descriptors. PGF/TiKZ. Do I really need to continue ;-)

Cheers
- -- tomás
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.12 (GNU/Linux)

iEYEARECAAYFAllBKdEACgkQBcgs9XrR2kZY9wCeMd03z0Zq/UwCrE4gHqEdLv90
GUMAnAramu6n1m2Fy+iJNyhQY6bzh6u6
=6l8F
-----END PGP SIGNATURE-----

Re: Major and minor modes

[Barry Margolin]

In article <z-SdnaV-lJGz4d3EnZ2dnUU7-cHNnZ2d@giganews.com>,
 "M.R.P." <wintermute24x7@icloud.com> wrote:

> Can anyone explain to me clearly how Major modes and minor modes work 
> together. Can any minor mode work within any major mode? How do these 
> work together?

Some minor modes are modifications to a specific set of major modes, so 
they can only work with those modes. For instance, electric mode 
modifies a number of language modes.

Other minor modes are more general, and can work with any major mode. 
For instance, auto-fill mode. But sometimes it's not very useful -- you 
probably don't want to do auto filling when editing programs rather than 
text.

-- 
Barry Margolin, barmar@alum.mit.edu
Arlington, MA
*** PLEASE post questions in newsgroups, not directly to me ***

Re: Major and minor modes

[Eli Zaretskii]

> From: Jean-Christophe Helary <jean.christophe.helary@gmail.com>
> Date: Wed, 14 Jun 2017 12:49:21 +0900
> 
> Interesting. I just noticed that the HTML and the PDF do not have the same chapter numbering.

I think that's because the PDF version is produced like a printed
manual would be, which means some of the stuff is excluded, while the
HTML version includes everything, like the Info version woul.

Re: Major and minor modes

[Jean-Christophe Helary]

> On Jun 14, 2017, at 23:23, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Jean-Christophe Helary <jean.christophe.helary@gmail.com>
>> Date: Wed, 14 Jun 2017 12:49:21 +0900
>> 
>> Interesting. I just noticed that the HTML and the PDF do not have the same chapter numbering.
> 
> I think that's because the PDF version is produced like a printed
> manual would be, which means some of the stuff is excluded, while the
> HTML version includes everything, like the Info version would.

It's different.

PDF Chapter 2 "Characters, Keys and Commands" has:
[introductory text about the chapter]
2.1 Kinds of User Input
2.2 Keys
2.3 Keys and Commands

but the HTML has:
• 2 Kinds of User Input
• 3 Keys
• 4 Keys and Commands

So in the HTML, PDF sub-chapters are chapters on their own and the introductory text is not present:
"This chapter explains the character sets used by Emacs for input commands, and the fundamental concepts of keys and commands, whereby Emacs interprets your keyboard and mouse input."

PDF Chapter 3 "Entering and Exiting Emacs" corresponds to HTML
• 5 Entering Emacs
• 6 Exiting Emacs

Then, until we reach PDF Chapter 31 "Miscellaneous Commands", everything corresponds and the HTML has introductory texts for each chapter just like the PDF.
PDF 31 corresponds to HTML
• 34 Gnus
• 35 Host Security
• 36 Network Security
• 37 Document Viewing
• 38 Web Browsing with EWW
• 39 Embedded WebKit Widgets
• 40 Running Shell Commands from Emacs
• 41 Using Emacs as a Server
• 42 Printing Hard Copies
• 43 Sorting Text
• 44 Editing Pictures
• 45 Editing Binary Files
• 46 Saving Emacs Sessions
• 47 Recursive Editing Levels
• 48 Hyperlinking and Navigation Features
• 49 Other Amusements

which were the subject of a recent discussion on emacs-devel btw.

Then PDF has:
32 Emacs Lisp Packages................................. 431
33 Customization ...................................... 436
34 Dealing with Common Problems ....................... 468

And that chapter 34 corresponds to HTML
• 52 Quitting and Aborting
• 53 Dealing with Emacs Trouble
• 54 Reporting Bugs
• 55 Contributing to Emacs Development
• 56 How To Get Help with GNU Emacs

That discrepancy is a bit weird.

Jean-Christophe

Re: Major and minor modes

[Jean-Christophe Helary]

As I just wrote, "That discrepancy is a bit weird." *especially* since the Info mode has groupings that don't even correspond to the PDF or the HTML...

I really think we should have more consistency in the way the manual is "visually" structured regardless of the format.

(And really, the 50+ pages of the "extra features" not being included in the 600+ pages manual *is* extra weird. If the issue were really to save on paper, we'd have a better balance between the manual and the extra features.)

Jean-Christophe 

> On Jun 15, 2017, at 6:58, Jean-Christophe Helary <jean.christophe.helary@gmail.com> wrote:
> 
> 
>> On Jun 14, 2017, at 23:23, Eli Zaretskii <eliz@gnu.org> wrote:
>> 
>>> From: Jean-Christophe Helary <jean.christophe.helary@gmail.com>
>>> Date: Wed, 14 Jun 2017 12:49:21 +0900
>>> 
>>> Interesting. I just noticed that the HTML and the PDF do not have the same chapter numbering.
>> 
>> I think that's because the PDF version is produced like a printed
>> manual would be, which means some of the stuff is excluded, while the
>> HTML version includes everything, like the Info version would.
> 
> It's different.
> 
> PDF Chapter 2 "Characters, Keys and Commands" has:
> [introductory text about the chapter]
> 2.1 Kinds of User Input
> 2.2 Keys
> 2.3 Keys and Commands
> 
> but the HTML has:
> • 2 Kinds of User Input
> • 3 Keys
> • 4 Keys and Commands
> 
> So in the HTML, PDF sub-chapters are chapters on their own and the introductory text is not present:
> "This chapter explains the character sets used by Emacs for input commands, and the fundamental concepts of keys and commands, whereby Emacs interprets your keyboard and mouse input."
> 
> PDF Chapter 3 "Entering and Exiting Emacs" corresponds to HTML
> • 5 Entering Emacs
> • 6 Exiting Emacs
> 
> Then, until we reach PDF Chapter 31 "Miscellaneous Commands", everything corresponds and the HTML has introductory texts for each chapter just like the PDF.
> PDF 31 corresponds to HTML
> • 34 Gnus
> • 35 Host Security
> • 36 Network Security
> • 37 Document Viewing
> • 38 Web Browsing with EWW
> • 39 Embedded WebKit Widgets
> • 40 Running Shell Commands from Emacs
> • 41 Using Emacs as a Server
> • 42 Printing Hard Copies
> • 43 Sorting Text
> • 44 Editing Pictures
> • 45 Editing Binary Files
> • 46 Saving Emacs Sessions
> • 47 Recursive Editing Levels
> • 48 Hyperlinking and Navigation Features
> • 49 Other Amusements
> 
> which were the subject of a recent discussion on emacs-devel btw.
> 
> Then PDF has:
> 32 Emacs Lisp Packages................................. 431
> 33 Customization ...................................... 436
> 34 Dealing with Common Problems ....................... 468
> 
> And that chapter 34 corresponds to HTML
> • 52 Quitting and Aborting
> • 53 Dealing with Emacs Trouble
> • 54 Reporting Bugs
> • 55 Contributing to Emacs Development
> • 56 How To Get Help with GNU Emacs
> 
> That discrepancy is a bit weird.
> 
> Jean-Christophe

Re: Major and minor modes

[Marcin Borkowski]

On 2017-06-14, at 05:59, Emanuel Berg <moasen@zoho.com> wrote:

> Jean-Christophe Helary
> <jean.christophe.helary@gmail.com> writes:
>
>> Interesting. I just noticed that the HTML and the
>> PDF do not have the same chapter numbering.
>>
>> The PDF for 24.5 and for 26.0.50 (that I built this
>> morning) both use chapter 20 for modes.
>
> Better to use the built-in info Emacs manual. Then you
> can't go wrong :)

<shameless plug>
See also http://mbork.pl/2016-12-18_Generating_links_to_info_buffers
</shameless plug>

-- 
Marcin Borkowski

Re: Major and minor modes

[Emanuel Berg]

Jean-Christophe Helary wrote:

> As I just wrote, "That discrepancy is a bit
> weird." *especially* since the Info mode has
> groupings that don't even correspond to the
> PDF or the HTML...

The manual is probably written in the Texinfo
format, then converted into PDF and HTML using
texi2pdf and texi2html. So what you describe
can't really be happening. Right?

-- 
underground experts united
http://user.it.uu.se/~embe8573

Re: Major and minor modes

[Eli Zaretskii]

> From: Jean-Christophe Helary <jean.christophe.helary@gmail.com>
> Date: Thu, 15 Jun 2017 06:58:07 +0900
> 
> PDF Chapter 2 "Characters, Keys and Commands" has:
> [introductory text about the chapter]
> 2.1 Kinds of User Input
> 2.2 Keys
> 2.3 Keys and Commands
> 
> but the HTML has:
> • 2 Kinds of User Input
> • 3 Keys
> • 4 Keys and Commands

Ah, that...  It's because the manual does this:

  @ifnottex
  @raisesections
  @end ifnottex

So when you later have this:

  @node User Input
  @section Kinds of User Input

The @section gets rendered as a chapter in on-line formats (Info and
HTML), and as a section in printed formats.

IOW, a book requires somewhat different considerations wrt its
sectioning than an on-line version of the manual.

> So in the HTML, PDF sub-chapters are chapters on their own and the introductory text is not present:
> "This chapter explains the character sets used by Emacs for input commands, and the fundamental concepts of keys and commands, whereby Emacs interprets your keyboard and mouse input."

That introductory text is conditionally included only in the printed
formats:

  @iftex
  @chapter Characters, Keys and Commands

    This chapter explains the character sets used by Emacs for input
  commands, and the fundamental concepts of @dfn{keys} and
  @dfn{commands}, whereby Emacs interprets your keyboard and mouse
  input.
  @end iftex

> Then PDF has:
> 32 Emacs Lisp Packages................................. 431
> 33 Customization ...................................... 436
> 34 Dealing with Common Problems ....................... 468
> 
> And that chapter 34 corresponds to HTML
> • 52 Quitting and Aborting
> • 53 Dealing with Emacs Trouble
> • 54 Reporting Bugs
> • 55 Contributing to Emacs Development
> • 56 How To Get Help with GNU Emacs
> 
> That discrepancy is a bit weird.

Is it still weird?

RE: Major and minor modes

[Drew Adams]

> > PDF Chapter 2 "Characters, Keys and Commands" has:
> > [introductory text about the chapter]
> > 2.1 Kinds of User Input
> > 2.2 Keys
> > 2.3 Keys and Commands
> >
> > but the HTML has:
> > • 2 Kinds of User Input
> > • 3 Keys
> > • 4 Keys and Commands
> 
> Ah, that...  It's because the manual does this:

<implementation considerations>

> IOW, a book requires somewhat different considerations wrt its
> sectioning than an on-line version of the manual.
>
> > That discrepancy is a bit weird.
> 
> Is it still weird?

Yes.  The PDF or print version of a manual should generally
have the same section numbers (and names) as an HTML or Info
or whatever else version.

It is fine for them to use different formatting.  It is even
fine if they have somewhat different text (e.g. xref text,
contextual paragraphs, whatever).

But section numbers, like section names, are not just content.
They are navigational.  They are used for reference, including
as was the case in this thread: someone pointing to a particular
section by name or number.

[Yes, a _link_ to a section in an online manual is often
preferable to such a purely textual representation.  But that
is not a reason why the section numbers or names should differ.]

As with everything, there might be exceptions.  But what was
shown here does not seem like a good candidate for being an
exception.

(Just one opinion.)

Re: Major and minor modes

[Jean-Christophe Helary]

>> IOW, a book requires somewhat different considerations wrt its
>> sectioning than an on-line version of the manual.
>> 
>>> That discrepancy is a bit weird.
>> 
>> Is it still weird?

Yes, and I have the exact same opinion as Drew on this one.

There are no logical reasons why a part of the manual would be a chapter on its own in one version and a sub chapter in a different version.

Shall we move this discussion to emacs-devel ?

> But section numbers, like section names, are not just content.
> They are navigational.  They are used for reference, including
> as was the case in this thread: someone pointing to a particular
> section by name or number.
> 
> [Yes, a _link_ to a section in an online manual is often
> preferable to such a purely textual representation.  But that
> is not a reason why the section numbers or names should differ.]
> 
> As with everything, there might be exceptions.  But what was
> shown here does not seem like a good candidate for being an
> exception.

Jean-Christophe

RE: Major and minor modes

[Drew Adams]

> Shall we move this discussion to emacs-devel ?

I would say no (but feel free).  Eli will decide anyway,
and probably already has.  I don't see much point in a
big discussion about it.  It's not a very big deal.

It's mainly about communication - referring someone to a
manual section.  In Emacs that's done by (MANUAL) `NODE'.
And on the web it's done by a URL (e.g., a link).

FWIW, in Info I have `G' bound to command `Info-goto-web',
from Info+.  It takes you directly to the same section in
the online manual.  There I copy the URL and post it on
the web, when I want to point someone to the html manual.

I probably use `G' at least once a day, to point someone
to something in the manual, by linking to it.

Pointing them to (MANUAL) `NODE' (i.e., in Emacs) is
generally better, but both are useful.

(https://www.emacswiki.org/emacs/InfoPlus)

Re: Major and minor modes

[Emanuel Berg]

Jean-Christophe Helary wrote:

> Shall we move this discussion to emacs-devel
> ?

You can report it as a bug. `report-emacs-bug'
includes documentation.

-- 
underground experts united
http://user.it.uu.se/~embe8573

Re: Major and minor modes

[Emanuel Berg]

Drew Adams wrote:

> I would say no (but feel free). Eli will
> decide anyway, and probably already has.
> I don't see much point in a big discussion
> about it. It's not a very big deal.

Inconsistent and incomplete documentation isn't
a big deal?

I always thought the HTML and PDF versions were
automatically compiled from the Texinfo source.

If they are, such a discrepancy as this is
a very interesting bug!

If they aren't, we are bound to see a lot of
these things in our remaining days so perhaps
we *should* start thinking of them
as unimportant...

-- 
underground experts united
http://user.it.uu.se/~embe8573

Re: Major and minor modes

[Jean-Christophe Helary]

> On Jun 16, 2017, at 13:44, Emanuel Berg <moasen@zoho.com> wrote:
> 
> I always thought the HTML and PDF versions were
> automatically compiled from the Texinfo source.

They are. They are built with `make docs'.

Jean-Christophe

Re: Major and minor modes

[Emanuel Berg]

Jean-Christophe Helary wrote:

>> I always thought the HTML and PDF versions
>> were automatically compiled from the
>> Texinfo source.
>
> They are. They are built with `make docs'.

So you return to make!

Have a look at the Makefile where the target
"docs" is, and see if you can spot the error.

It might get complicated tho as several
subtargets should emerge. It is the Pandora's
box all over with just a glimmer of hope.

-- 
underground experts united
http://user.it.uu.se/~embe8573

Re: Major and minor modes

[Eli Zaretskii]

> Date: Thu, 15 Jun 2017 20:07:17 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: Eli Zaretskii <eliz@gnu.org>, help-gnu-emacs@gnu.org
> 
> > Shall we move this discussion to emacs-devel ?
> 
> I would say no (but feel free).  Eli will decide anyway,
> and probably already has.

It wasn't my decision.  And you-all seem to misunderstand my part in
this thread: I was just trying to explain Jean-Christophe's
observations, that's all.  I didn't put those directives into the
manual, and I don't really know why that was done.  You can use "git
annotate" to see who did, and then try asking them why did they do
that, or do more forensics I did and find a discussion which led to
the change.

> I don't see much point in a big discussion about it.  It's not a
> very big deal.

I agree.  I also trust those who did it that this was done for some
valid reason, not out of negligence or incompetence.  The Emacs
project treats documentation very seriously, and no such change back
in 2004 could be sneaked without RMS approving it.

If, after all that, someone still wants to open a discussion about
that, feel free.

Re: Major and minor modes

[Jean-Christophe Helary]

> On Jun 16, 2017, at 15:59, Eli Zaretskii <eliz@gnu.org> wrote:

> I was just trying to explain Jean-Christophe's
> observations, that's all.

Thank you as always. I had the idea that the structure was deliberate but your explanations were really useful.

> If, after all that, someone still wants to open a discussion about
> that, feel free.

I'll eventually do, if only to understand the rationale behind such choices.

Jean-Christophe

Re: Major and minor modes

[Narendra Joshi]

Emanuel Berg <moasen@zoho.com> writes:

> Drew Adams <drew.adams@oracle.com> writes:
>
>> A minor mode can be buffer-specific (local) or not
>> (global). Minor-mode key bindings override
>> major-mode key bindings.
>
> Good point. This goes against the intuition of some
> people who think what is bigger should be the boss,
> period.
>
> One can think of it like a compass needle. It works on
> the magneticism of Earth itself. However put a small
> magnet next to it, and it will override the entire
> planet! It is thoughtworthy.
Wow! This is an awesome analogy. I really like it. :)

> I suppose the "size" in this matter isn't the size
> alone but also the *proximity*, just like with Emacs
> major and minor modes, the minor mode being closer to
> the user...

-- 
Narendra Joshi

Re: Major and minor modes

[Krishnakant]

On Saturday 17 June 2017 07:38 PM, Narendra Joshi wrote:
> Emanuel Berg <moasen@zoho.com> writes:
>
>> Drew Adams <drew.adams@oracle.com> writes:
>>
>>> A minor mode can be buffer-specific (local) or not
>>> (global). Minor-mode key bindings override
>>> major-mode key bindings.
>> Good point. This goes against the intuition of some
>> people who think what is bigger should be the boss,
>> period.
>>
>> One can think of it like a compass needle. It works on
>> the magneticism of Earth itself. However put a small
>> magnet next to it, and it will override the entire
>> planet! It is thoughtworthy.
> Wow! This is an awesome analogy. I really like it. :)
>
>> I suppose the "size" in this matter isn't the size
>> alone but also the *proximity*, just like with Emacs
>> major and minor modes, the minor mode being closer to
>> the user...
>
wonderful example, it's some thing I am going to use in my seminars to 
teach Emacs.
The proximity based explanation should be used by every one who tries to 
teach Emacs to newbies.
I am going to add this as a comment to my blog.
Happy hacking.
Krishnakant.