Emacs Manual under a categorisation scheme

Emacs Manual under a categorisation scheme

[Christopher Dimech]

With the Emacs Manual having 54 sections, could it be be categorised under a much smaller
scheme (perhaps five or eight).  This is to easily and quickly go through it for the
information one wants by using a category system.

For instance, the GNU Manuals Online is arranged by a limited number of categories.
See https://www.gnu.org/manual/manual.html

The Emacs Manual could follow in a similar way.

Re: Emacs Manual under a categorisation scheme

[Eli Zaretskii]

> From: Christopher Dimech <dimech@gmx.com>
> Date: Tue, 12 Jul 2022 18:13:55 +0200
> Sensitivity: Normal
> 
> With the Emacs Manual having 54 sections, could it be be categorised under a much smaller
> scheme (perhaps five or eight).  This is to easily and quickly go through it for the
> information one wants by using a category system.

I don't think I understand what kind of category system do you have in
mind.  Please elaborate and/or show an example.

> For instance, the GNU Manuals Online is arranged by a limited number of categories.
> See https://www.gnu.org/manual/manual.html

This has about 40 categories: not a far cry from our 54 chapters.

To look for some subject, one is supposed to use the Info-index
command, bound to 'i' inside Info.  There's no need to look up
subjects by reading the chapter titles.

RE: [External] : Re: Emacs Manual under a categorisation scheme

[Drew Adams]

> To look for some subject, one is supposed to use the Info-index
> command, bound to 'i' inside Info.  There's no need to look up
> subjects by reading the chapter titles.

+1.
___

BTW, it helps (IMO) to use a `substring'
completion style for `i' (and `g' and...)

Maybe Emacs could define a category `info'
and predefine its completion style as
`(substring)' or some such.

Re: Emacs Manual under a categorisation scheme

[Christopher Dimech]

> Sent: Wednesday, July 13, 2022 at 4:27 AM
> From: "Eli Zaretskii" <eliz@gnu.org>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: emacs-devel@gnu.org
> Subject: Re: Emacs Manual under a categorisation scheme
>
> > From: Christopher Dimech <dimech@gmx.com>
> > Date: Tue, 12 Jul 2022 18:13:55 +0200
> > Sensitivity: Normal
> >
> > With the Emacs Manual having 54 sections, could it be be categorised under a much smaller
> > scheme (perhaps five or eight).  This is to easily and quickly go through it for the
> > information one wants by using a category system.
>
> I don't think I understand what kind of category system do you have in
> mind.  Please elaborate and/or show an example.

One could arrange either by difficulty or frequency.

Basically, using a higher level categorisation to the 54 chapters, with each
high level category being independent of the others.  One can then quickly
skip whole categories one is not interested in, even when using the manual on
the website.

1. Comprehending the Graphical Display
2. Running Commands (by Name, using Minibuffer read and completion)
3. Editing Commands (moving and killing text)
4. Using and Controlling the Graphical Display (buffer, window, frame)
5. Major and Minor Modes
6. Using Help
7. Programming and Markup Modes
8. Compiling, Testing, and Maintaining Programs
9. Running Shell Commands
10. Calendar, Diary, Document Viewing
10. Web Applications (EWW, Mail)
11. Emacs Customisation
12. Handling Problems (crashes, reporting bugs)



> > For instance, the GNU Manuals Online is arranged by a limited number of categories.
> > See https://www.gnu.org/manual/manual.html
>
> This has about 40 categories: not a far cry from our 54 chapters.
>
> To look for some subject, one is supposed to use the Info-index
> command, bound to 'i' inside Info.  There's no need to look up
> subjects by reading the chapter titles.
>

Re: Emacs Manual under a categorisation scheme

[Eli Zaretskii]

> From: Christopher Dimech <dimech@gmx.com>
> Cc: emacs-devel@gnu.org
> Date: Tue, 12 Jul 2022 18:57:20 +0200
> 
> > I don't think I understand what kind of category system do you have in
> > mind.  Please elaborate and/or show an example.
> 
> One could arrange either by difficulty or frequency.
> 
> Basically, using a higher level categorisation to the 54 chapters, with each
> high level category being independent of the others.  One can then quickly
> skip whole categories one is not interested in, even when using the manual on
> the website.
> 
> 1. Comprehending the Graphical Display
> 2. Running Commands (by Name, using Minibuffer read and completion)
> 3. Editing Commands (moving and killing text)
> 4. Using and Controlling the Graphical Display (buffer, window, frame)
> 5. Major and Minor Modes
> 6. Using Help
> 7. Programming and Markup Modes
> 8. Compiling, Testing, and Maintaining Programs
> 9. Running Shell Commands
> 10. Calendar, Diary, Document Viewing
> 10. Web Applications (EWW, Mail)
> 11. Emacs Customisation
> 12. Handling Problems (crashes, reporting bugs)

I don't see how this is significantly different from the chapters we
have now.  You can categorize Emacs in any number of ways, but the one
we have is IMNSHO completely adequate.  What you propose is also
adequate (although incomplete, so I cannot easily judge it except as
an example), but I don't see why it is superior.

Re: Emacs Manual under a categorisation scheme

[Christopher Dimech]

> Sent: Wednesday, July 13, 2022 at 5:06 AM
> From: "Eli Zaretskii" <eliz@gnu.org>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: emacs-devel@gnu.org
> Subject: Re: Emacs Manual under a categorisation scheme
>
> > From: Christopher Dimech <dimech@gmx.com>
> > Cc: emacs-devel@gnu.org
> > Date: Tue, 12 Jul 2022 18:57:20 +0200
> >
> > > I don't think I understand what kind of category system do you have in
> > > mind.  Please elaborate and/or show an example.
> >
> > One could arrange either by difficulty or frequency.
> >
> > Basically, using a higher level categorisation to the 54 chapters, with each
> > high level category being independent of the others.  One can then quickly
> > skip whole categories one is not interested in, even when using the manual on
> > the website.
> >
> > 1. Comprehending the Graphical Display
> > 2. Running Commands (by Name, using Minibuffer read and completion)
> > 3. Editing Commands (moving and killing text)
> > 4. Using and Controlling the Graphical Display (buffer, window, frame)
> > 5. Major and Minor Modes
> > 6. Using Help
> > 7. Programming and Markup Modes
> > 8. Compiling, Testing, and Maintaining Programs
> > 9. Running Shell Commands
> > 10. Calendar, Diary, Document Viewing
> > 10. Web Applications (EWW, Mail)
> > 11. Emacs Customisation
> > 12. Handling Problems (crashes, reporting bugs)
>
> I don't see how this is significantly different from the chapters we
> have now.  You can categorize Emacs in any number of ways, but the one
> we have is IMNSHO completely adequate.  What you propose is also
> adequate (although incomplete, so I cannot easily judge it except as
> an example), but I don't see why it is superior.
>

Yes, it is as an example as I agree it is not complete.  It is a higher
level categorisation without changing the actual chapters you have now.

It was a response on some user comments stating that the whole lot looks
overwhelming.

You could also make a number of scenarios on what the user wants to search
so he can be directed to the relevant information faster.

Re: Emacs Manual under a categorisation scheme

[Eli Zaretskii]

> From: Christopher Dimech <dimech@gmx.com>
> Cc: emacs-devel@gnu.org
> Date: Tue, 12 Jul 2022 19:16:35 +0200
> 
> Yes, it is as an example as I agree it is not complete.  It is a higher
> level categorisation without changing the actual chapters you have now.

I don't think it's higher level.  It's approximately on the same
level.  Quite a few of the categories correspond one-to-one to our
chapters, with slightly different names.

Re: Emacs Manual under a categorisation scheme

[Christopher Dimech]

> Sent: Wednesday, July 13, 2022 at 5:23 AM
> From: "Eli Zaretskii" <eliz@gnu.org>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: emacs-devel@gnu.org
> Subject: Re: Emacs Manual under a categorisation scheme
>
> > From: Christopher Dimech <dimech@gmx.com>
> > Cc: emacs-devel@gnu.org
> > Date: Tue, 12 Jul 2022 19:16:35 +0200
> >
> > Yes, it is as an example as I agree it is not complete.  It is a higher
> > level categorisation without changing the actual chapters you have now.
>
> I don't think it's higher level.  It's approximately on the same
> level.  Quite a few of the categories correspond one-to-one to our
> chapters, with slightly different names.

It is just an idea so there will not be so many chapters.  Or keep all the
chapters with a collection of chapters under some overarching heading.

Re: Emacs Manual under a categorisation scheme

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

  > It is just an idea so there will not be so many chapters.  Or keep all the
  > chapters with a collection of chapters under some overarching heading.

To add another higher level of grouping would be feasible,
since it would not require much change in the text we have.
It might be helpful for some users, but I tend to think it
would not make a big difference.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Emacs Manual under a categorisation scheme

[Christopher Dimech]

> Sent: Wednesday, July 13, 2022 at 3:18 PM
> From: "Richard Stallman" <rms@gnu.org>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: eliz@gnu.org, emacs-devel@gnu.org
> Subject: Re: Emacs Manual under a categorisation scheme
>
> [[[ 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. ]]]
>
>   > It is just an idea so there will not be so many chapters.  Or keep all the
>   > chapters with a collection of chapters under some overarching heading.
>
> To add another higher level of grouping would be feasible,
> since it would not require much change in the text we have.
> It might be helpful for some users, but I tend to think it
> would not make a big difference.

It would help through the node system.  Export users can skip
the initial nodes, whilst newcomers can skip the latter nodes.

There can be a list on how to read the manual according to different
needs.  For instance, for newcomers suggestion on using first three nodes,
eighth node, and thirteenth node.  And so on for other users.  Some users
have commented how long the manual looks.


> --
> Dr Richard Stallman (https://stallman.org)
> Chief GNUisance of the GNU Project (https://gnu.org)
> Founder, Free Software Foundation (https://fsf.org)
> Internet Hall-of-Famer (https://internethalloffame.org)
>
>
>