Specialized Emacs Features ?

Specialized Emacs Features ?

[Jean-Christophe Helary]

What's the point of having a separate document for those "specialized" (?) features?

Jean-Christophe 

Re: Specialized Emacs Features ?

[Eli Zaretskii]

> From: Jean-Christophe Helary <jean.christophe.helary@gmail.com>
> Date: Fri, 2 Jun 2017 21:13:18 +0900
> 
> What's the point of having a separate document for those "specialized" (?) features?

To make the printed Emacs user manual smaller.

Re: Specialized Emacs Features ?

[Jean-Christophe Helary]

> On Jun 2, 2017, at 21:22, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Jean-Christophe Helary <jean.christophe.helary@gmail.com>
>> Date: Fri, 2 Jun 2017 21:13:18 +0900
>> 
>> What's the point of having a separate document for those "specialized" (?) features?
> 
> To make the printed Emacs user manual smaller.

It makes sense. But it's not clear what's the line between what is "specialized" and what is not...
If we want to make a smaller printed manual it seems to me there are other chapters that we can move out to a "specialized" manual.

For ex. (with a few chapters moved around):

Standard Manual:

• 1 The Organization of the Screen
• 2 Kinds of User Input
• 3 Keys
• 4 Keys and Commands
• 5 Entering Emacs
• 6 Exiting Emacs
• 52 Quitting and Aborting
• 46 Saving Emacs Sessions
• 10 Help

• 18 File Handling
• 7 Basic Editing Commands
• 22 International Character Set Support
• 16 Commands for Fixing Typos
• 15 Searching and Replacement
• 43 Sorting Text
• 24 Indentation
• 11 The Mark and the Region
• 12 Killing and Moving Text
• 13 Registers
• 17 Keyboard Macros
• 47 Recursive Editing Levels
• 42 Printing Hard Copies
• 30 Dired, the Directory Editor

• 8 The Minibuffer
• 9 Running Commands by Name
• 40 Running Shell Commands from Emacs

• 14 Controlling the Display
• 19 Using Multiple Buffers
• 20 Multiple Windows
• 21 Frames and Graphical Displays

• 23 Major and Minor Modes
• 25 Commands for Human Languages
• 26 Editing Programs
• 27 Compiling and Testing Programs
• 28 Maintaining Large Programs
• 29 Abbrevs
• 44 Editing Pictures
• 45 Editing Binary Files
• 37 Document Viewing
• 48 Hyperlinking and Navigation Features
• 49 Other Amusements

• 35 Host Security
• 36 Network Security
• 41 Using Emacs as a Server

• 53 Dealing with Emacs Trouble
• 54 Reporting Bugs
• 55 Contributing to Emacs Development
• 56 How To Get Help with GNU Emacs

Moved to Specialized manual
• 31 The Calendar and the Diary
• 32 Sending Mail
• 33 Reading Mail with Rmail
• 34 Gnus
• 38 Web Browsing with EWW
• 39 Embedded WebKit Widgets
• 50 Emacs Lisp Packages
• 51 Customization

Jean-Christophe 

Re: Specialized Emacs Features ?

[Eli Zaretskii]

> From: Jean-Christophe Helary <jean.christophe.helary@gmail.com>
> Date: Fri, 2 Jun 2017 22:04:57 +0900
> 
> >> What's the point of having a separate document for those "specialized" (?) features?
> > 
> > To make the printed Emacs user manual smaller.
> 
> It makes sense. But it's not clear what's the line between what is "specialized" and what is not...

It's a judgment call.

> Moved to Specialized manual
> • 31 The Calendar and the Diary
> • 32 Sending Mail
> • 33 Reading Mail with Rmail
> • 34 Gnus
> • 38 Web Browsing with EWW
> • 39 Embedded WebKit Widgets
> • 50 Emacs Lisp Packages
> • 51 Customization

These all sound like too important to omit from the user manual.
E.g., how can we omit Customization?  Or Emacs Lisp Packages?

Re: Specialized Emacs Features ?

[Jean-Christophe Helary]

>> Moved to Specialized manual
>> • 31 The Calendar and the Diary
>> • 32 Sending Mail
>> • 33 Reading Mail with Rmail
>> • 34 Gnus
>> • 38 Web Browsing with EWW
>> • 39 Embedded WebKit Widgets
>> • 50 Emacs Lisp Packages
>> • 51 Customization
> 
> These all sound like too important to omit from the user manual.
> E.g., how can we omit Customization?  Or Emacs Lisp Packages?


As far as *printing* is concerned, I don't know whether it is very hard to create a "basic" manual and an "advanced" manual from the files that create the *whole* manual (standard+specialized) when creating the printed files, but it seems to be only a matter of configuring a few files. For digital versions, all the informations should be in *the* emacs manual.

I have 2 other issues regarding the manual:
• I'm not finding the "specialized" manual in Info mode.
• The emacs manual is *not* an introductory manual, so I don't think we should have an "Advanced Features" section where most of the chapters could actually be placed in sections that relate to their contents (as I kind of proposed in the re-shuffling I sent in my earlier mail).

Jean-Christophe 

Re: Specialized Emacs Features ?

[Eli Zaretskii]

> From: Jean-Christophe Helary <jean.christophe.helary@gmail.com>
> Date: Fri, 2 Jun 2017 22:38:34 +0900
> 
> As far as *printing* is concerned, I don't know whether it is very hard to create a "basic" manual and an "advanced" manual from the files that create the *whole* manual (standard+specialized) when creating the printed files, but it seems to be only a matter of configuring a few files.

You should talk to the FSF about this, it is they who publish printed
manuals and sell them.  I have no idea what they consider when they
decide on these issues.

> For digital versions, all the informations should be in *the* emacs manual.

I'm not sure I understand what that means.  What is a "digital"
version?

> • I'm not finding the "specialized" manual in Info mode.

How are you looking?  E.g., the first menu item in emacs-xtra.texi is
"Autorevert", and if I type "g Autorevert RET" in the Emacs manual, I
get to that node.

IOW, the chapters of this manual are chapters and sections in the
Emacs manual in Info format.  There's no separate manual in Info.

> • The emacs manual is *not* an introductory manual, so I don't think we should have an "Advanced Features" section where most of the chapters could actually be placed in sections that relate to their contents (as I kind of proposed in the re-shuffling I sent in my earlier mail).

You interpret "Advanced" too literally in this case.  I think it's a
euphemism.

Re: Specialized Emacs Features ?

[Jean-Christophe Helary]

> On Jun 2, 2017, at 23:05, Eli Zaretskii <eliz@gnu.org> wrote:
> 
> You should talk to the FSF about this, it is they who publish printed
> manuals and sell them.  I have no idea what they consider when they
> decide on these issues.

Ok.

>> • I'm not finding the "specialized" manual in Info mode.
> 
> IOW, the chapters of this manual are chapters and sections in the
> Emacs manual in Info format.  There's no separate manual in Info.

I was naively looking for a separate manual in the main Info ToC. Apologies.

>> • The emacs manual is *not* an introductory manual, so I don't think we should have an "Advanced Features" section where most of the chapters could actually be placed in sections that relate to their contents (as I kind of proposed in the re-shuffling I sent in my earlier mail).
> 
> You interpret "Advanced" too literally in this case.  I think it's a euphemism.

:) Yes, but the "Advanced Features" section is a mess that should be reorganized.

Jean-Christophe

Re: Specialized Emacs Features ?

[Yuri Khan]

On Fri, Jun 2, 2017 at 9:35 PM, Jean-Christophe Helary
<jean.christophe.helary@gmail.com> wrote:

>> You interpret "Advanced" too literally in this case.  I think it's a euphemism.
>
> :) Yes, but the "Advanced Features" section is a mess that should be reorganized.

Perhaps by moving everything into it.

Re: Specialized Emacs Features ?

[Jean-Christophe Helary]

> On Jun 2, 2017, at 23:56, Yuri Khan <yuri.v.khan@gmail.com> wrote:
> 
> On Fri, Jun 2, 2017 at 9:35 PM, Jean-Christophe Helary
> <jean.christophe.helary@gmail.com> wrote:
> 
>>> You interpret "Advanced" too literally in this case.  I think it's a euphemism.
>> 
>> :) Yes, but the "Advanced Features" section is a mess that should be reorganized.
> 
> Perhaps by moving everything into it.

Thanks to Eli's comment I see that I was confused as to where the "specialized" chapters actually were in the documentation.

Now, forward to the structure of the current manual... Let's say we keep the separation between "normal" and "specialized" as far as the printed copies are concerned, we can still rearrange the way the manual is structured right now to put related features together and get rid of that silly "advanced features" section:

• 1 The Organization of the Screen
• 2 Kinds of User Input
• 3 Keys
• 4 Keys and Commands
• 5 Entering Emacs
• 6 Exiting Emacs
• 52 Quitting and Aborting
• 46 Saving Emacs Sessions
• 10 Help

• 8 The Minibuffer
• 9 Running Commands by Name
• 40 Running Shell Commands from Emacs

• 18 File Handling
• 7 Basic Editing Commands
• 22 International Character Set Support
• 16 Commands for Fixing Typos
• 15 Searching and Replacement
• 43 Sorting Text
• 24 Indentation
• 11 The Mark and the Region
• 12 Killing and Moving Text
• 13 Registers
• 17 Keyboard Macros
• 47 Recursive Editing Levels
• 30 Dired, the Directory Editor
• 42 Printing Hard Copies

• 14 Controlling the Display
• 19 Using Multiple Buffers
• 20 Multiple Windows
• 21 Frames and Graphical Displays

• 23 Major and Minor Modes
• 25 Commands for Human Languages
• 31 The Calendar and the Diary
• 26 Editing Programs
• 27 Compiling and Testing Programs
• 28 Maintaining Large Programs
• 29 Abbrevs
• 44 Editing Pictures
• 45 Editing Binary Files
• 37 Document Viewing
• 48 Hyperlinking and Navigation Features
• 49 Other Amusements

• 35 Host Security
• 36 Network Security
• 32 Sending Mail
• 33 Reading Mail with Rmail
• 34 Gnus
• 38 Web Browsing with EWW
• 39 Embedded WebKit Widgets
• 41 Using Emacs as a Server

• 50 Emacs Lisp Packages
• 51 Customization

• 53 Dealing with Emacs Trouble
• 54 Reporting Bugs
• 55 Contributing to Emacs Development
• 56 How To Get Help with GNU Emacs

Jean-Christophe 

Re: Specialized Emacs Features ?

[Eli Zaretskii]

> From: Jean-Christophe Helary <jean.christophe.helary@gmail.com>
> Date: Sat, 3 Jun 2017 00:11:53 +0900
> 
> Now, forward to the structure of the current manual... Let's say we keep the separation between "normal" and "specialized" as far as the printed copies are concerned, we can still rearrange the way the manual is structured right now to put related features together and get rid of that silly "advanced features" section:
> 
> • 1 The Organization of the Screen
> • 2 Kinds of User Input
> • 3 Keys
> • 4 Keys and Commands
> • 5 Entering Emacs
> • 6 Exiting Emacs
> • 52 Quitting and Aborting
> • 46 Saving Emacs Sessions
> • 10 Help
> 
> • 8 The Minibuffer
> • 9 Running Commands by Name
> • 40 Running Shell Commands from Emacs
> 
> • 18 File Handling
> • 7 Basic Editing Commands
> • 22 International Character Set Support
> • 16 Commands for Fixing Typos
> • 15 Searching and Replacement
> • 43 Sorting Text
> • 24 Indentation
> • 11 The Mark and the Region
> • 12 Killing and Moving Text
> • 13 Registers
> • 17 Keyboard Macros
> • 47 Recursive Editing Levels
> • 30 Dired, the Directory Editor
> • 42 Printing Hard Copies
> 
> • 14 Controlling the Display
> • 19 Using Multiple Buffers
> • 20 Multiple Windows
> • 21 Frames and Graphical Displays
> 
> • 23 Major and Minor Modes
> • 25 Commands for Human Languages
> • 31 The Calendar and the Diary
> • 26 Editing Programs
> • 27 Compiling and Testing Programs
> • 28 Maintaining Large Programs
> • 29 Abbrevs
> • 44 Editing Pictures
> • 45 Editing Binary Files
> • 37 Document Viewing
> • 48 Hyperlinking and Navigation Features
> • 49 Other Amusements
> 
> • 35 Host Security
> • 36 Network Security
> • 32 Sending Mail
> • 33 Reading Mail with Rmail
> • 34 Gnus
> • 38 Web Browsing with EWW
> • 39 Embedded WebKit Widgets
> • 41 Using Emacs as a Server
> 
> • 50 Emacs Lisp Packages
> • 51 Customization
> 
> • 53 Dealing with Emacs Trouble
> • 54 Reporting Bugs
> • 55 Contributing to Emacs Development
> • 56 How To Get Help with GNU Emacs

Could you explain what principles led to this order?  It looks strange
to me to have, for example, "Saving Emacs Sessions" before "Basic
Editing Commands", or "Sorting Text" before "Killing and Moving text".

Re: Specialized Emacs Features ?

[Jean-Christophe Helary]

> On Jun 3, 2017, at 0:55, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Jean-Christophe Helary <jean.christophe.helary@gmail.com>
>> Date: Sat, 3 Jun 2017 00:11:53 +0900
>> 
>> Now, forward to the structure of the current manual... Let's say we keep the separation between "normal" and "specialized" as far as the printed copies are concerned, we can still rearrange the way the manual is structured right now to put related features together and get rid of that silly "advanced features" section:
>> 
>> • 1 The Organization of the Screen
>> • 2 Kinds of User Input
>> • 3 Keys
>> • 4 Keys and Commands
>> • 5 Entering Emacs
>> • 6 Exiting Emacs
>> • 52 Quitting and Aborting
>> • 46 Saving Emacs Sessions
>> • 10 Help
>> 
>> • 8 The Minibuffer
>> • 9 Running Commands by Name
>> • 40 Running Shell Commands from Emacs
>> 
>> • 18 File Handling
>> • 7 Basic Editing Commands
>> • 22 International Character Set Support
>> • 16 Commands for Fixing Typos
>> • 15 Searching and Replacement
>> • 43 Sorting Text
>> • 24 Indentation
>> • 11 The Mark and the Region
>> • 12 Killing and Moving Text
>> • 13 Registers
>> • 17 Keyboard Macros
>> • 47 Recursive Editing Levels
>> • 30 Dired, the Directory Editor
>> • 42 Printing Hard Copies
>> 
>> • 14 Controlling the Display
>> • 19 Using Multiple Buffers
>> • 20 Multiple Windows
>> • 21 Frames and Graphical Displays
>> 
>> • 23 Major and Minor Modes
>> • 25 Commands for Human Languages
>> • 31 The Calendar and the Diary
>> • 26 Editing Programs
>> • 27 Compiling and Testing Programs
>> • 28 Maintaining Large Programs
>> • 29 Abbrevs
>> • 44 Editing Pictures
>> • 45 Editing Binary Files
>> • 37 Document Viewing
>> • 48 Hyperlinking and Navigation Features
>> • 49 Other Amusements
>> 
>> • 35 Host Security
>> • 36 Network Security
>> • 32 Sending Mail
>> • 33 Reading Mail with Rmail
>> • 34 Gnus
>> • 38 Web Browsing with EWW
>> • 39 Embedded WebKit Widgets
>> • 41 Using Emacs as a Server
>> 
>> • 50 Emacs Lisp Packages
>> • 51 Customization
>> 
>> • 53 Dealing with Emacs Trouble
>> • 54 Reporting Bugs
>> • 55 Contributing to Emacs Development
>> • 56 How To Get Help with GNU Emacs
> 
> Could you explain what principles led to this order?

1st section is about starting/quitting and getting help.
2nd is about running commands.
3rd is about text editing
4th is about the display
5th is about the main advertised modes
6th is about networking
7th is about extending Emacs
8th is about the project in general (although 53 could be in the 1st section)

>  It looks strange to me to have, for example, "Saving Emacs Sessions" before "Basic
> Editing Commands"

Maybe, but Saving emacs sessions is more related to quitting than to anything else.

> , or "Sorting Text" before "Killing and Moving text".

Indeed, but Mark&Region/Killing/Registers are all related and Sorting is closer to general text editing.

But there is definitely room for improvement.

Jean-Christophe 

Re: Specialized Emacs Features ?

[Eli Zaretskii]

> From: Jean-Christophe Helary <jean.christophe.helary@gmail.com>
> Date: Sat, 3 Jun 2017 01:15:38 +0900
> 
> >  It looks strange to me to have, for example, "Saving Emacs Sessions" before "Basic
> > Editing Commands"
> 
> Maybe, but Saving emacs sessions is more related to quitting than to anything else.
> 
> > , or "Sorting Text" before "Killing and Moving text".
> 
> Indeed, but Mark&Region/Killing/Registers are all related and Sorting is closer to general text editing.

IME, learning a new tool is more efficient if done in a spiral than in
a tree-like depth-first order.

Re: Specialized Emacs Features ?

[Jean-Christophe Helary]

> On Jun 3, 2017, at 2:34, Eli Zaretskii <eliz@gnu.org> wrote:
> 
> IME, learning a new tool is more efficient if done in a spiral than in
> a tree-like depth-first order.

I agree, and I'm not suggesting that we impose a learning method to the reader. The manual is fully linked and referenced and as such is already fully "spiralable".

I'm just concerned about that "advanced features" section that looks like a list of chapters that were just put there as an afterthought. For ex, the "sort text" item should really be after 22.7. There is no reason why it appears as an advanced feature. There is a "networking" section that could be created by just adding a section title etc.

I'm just talking about a little gardening in the manual.

Jean-Christophe

Re: Specialized Emacs Features ?

[Clément Pit-Claudel]

On 2017-06-02 19:46, Jean-Christophe Helary wrote:
> I agree, and I'm not suggesting that we impose a learning method to the reader. The manual is fully linked and referenced and as such is already fully "spiralable".

That's not how I understood "in a spiral": I understood it as meaning that the current manual can be read front to back, and that it proceeds roughly in breadth-first order.  Gathering related topic causes you to learn a lot about a particular topic before you learn anything about the next one.

Re: Specialized Emacs Features ?

[Jean-Christophe Helary]

> On Jun 3, 2017, at 8:55, Clément Pit-Claudel <cpitclaudel@gmail.com> wrote:
> 
> On 2017-06-02 19:46, Jean-Christophe Helary wrote:
>> I agree, and I'm not suggesting that we impose a learning method to the reader. The manual is fully linked and referenced and as such is already fully "spiralable".
> 
> That's not how I understood "in a spiral": I understood it as meaning that the current manual can be read front to back, and that it proceeds roughly in breadth-first order.  Gathering related topic causes you to learn a lot about a particular topic before you learn anything about the next one.

I understand that. And we can discuss theory of learning and reading books for ever, which is not what I am trying to do.

The reality of the manual is that nobody reads it front to back. People start with a few online tutorials, start using Emacs, eventually go through the Tutorial and then search for information on topics either on the web or in the manuals installed on their machines. And even when they know that the manual is here, they don't really try to read it front to back in the end because there is no logical structure in it: why would we consider "moving around words, paragraphs and pages" as "advanced" when it is pretty much the core of the Tutorial ?

The "Advanced Features" section maybe made sense when the printed manual was really a thing (3 decades ago?),  but then people started to abuse it and it is now a place where things that are now considered "basic" are mixed with things that are commonly used and things that are truly advanced...

It reminds me of the documentation for the "trim" argument in split-string. The argument was added in 2013 and instead of putting its documentation at the *end* of the documentation paragraph since it was the last argument of the function, it was put *after* the long list or examples. I moved it where it belonged the other day, but there are plenty of things like this in the manual and in the reference that make it hard to read and in the end hard to understand.

Jean-Christophe

Re: Specialized Emacs Features ?

[Eli Zaretskii]

> From: Jean-Christophe Helary <jean.christophe.helary@gmail.com>
> Date: Sat, 3 Jun 2017 08:46:56 +0900
> 
> > On Jun 3, 2017, at 2:34, Eli Zaretskii <eliz@gnu.org> wrote:
> > 
> > IME, learning a new tool is more efficient if done in a spiral than in
> > a tree-like depth-first order.
> 
> I agree, and I'm not suggesting that we impose a learning method to the reader. The manual is fully linked and referenced and as such is already fully "spiralable".

This argument goes both ways: if the order of chapters doesn't matter,
then why are you suggesting to change it?

But I think the order does matter: you forget about the reader who
reads the printed book.  Books are generally read front to back, so
the order of chapters does matter in that case.

> I'm just concerned about that "advanced features" section that looks like a list of chapters that were just put there as an afterthought. For ex, the "sort text" item should really be after 22.7. There is no reason why it appears as an advanced feature.

It's "advanced" because most users will rarely if ever need to sort
text within Emacs.

> There is a "networking" section that could be created by just adding a section title etc.

I could agree to having Gnus, Rmail, and "Sending Mail" under the same
chapter.  But I see no reason to have them all under "Networking", nor
bringing EWW and WebKit chapters to their side, as that doesn't
necessarily make sense to a user.  And "Host Security" is not about
networking anyway.

> I'm just talking about a little gardening in the manual.

That's fine, but the current structure is not arbitrary, either, so we
must agree on some principles first.  E.g., claiming that the order
doesn't matter is a non-starter, IMO.

Re: Specialized Emacs Features ?

[Eli Zaretskii]

> From: Jean-Christophe Helary <jean.christophe.helary@gmail.com>
> Date: Sat, 3 Jun 2017 09:49:13 +0900
> 
> The "Advanced Features" section maybe made sense when the printed manual was really a thing (3 decades ago?)

There's no "Advanced Features" section in the manual.  There's a
heading "Advanced Features" in the master menu, but it's there just
for some order in the very large menu, that's all.  So I'm not sure
what problem you are trying to solve.  I suggest we take a step back
and first define that problem and agree on its existence.

Re: Specialized Emacs Features ?

[Jean-Christophe Helary]

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


> On Jun 3, 2017, at 15:15, Eli Zaretskii <eliz@gnu.org> wrote:
> 
> I suggest we take a step back and first define that problem and agree on its existence.

Ok.

JC

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

Re: Specialized Emacs Features ?

[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. ]]]

  > The "Advanced Features" section maybe made sense when the printed
  > manual was really a thing (3 decades ago?), but then people
  > started to abuse it and it is now a place where things that are
  > now considered "basic" are mixed with things that are commonly
  > used and things that are truly advanced...

The "Advanced Features" are the facilities you don't need to know to
understand Emacs in general.

-- 
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.