Intermediate tutorial shipped with Emacs

Intermediate tutorial shipped with Emacs

[Spencer Baugh]

Hi emacs-devel,

I think it would be good if Emacs shipped with an intermediate tutorial,
covering topics beyond the basic tutorial. Reading the entire manual is
great, but wouldn't it be nice if there was a short/medium-length
overview of some of the cool features of Emacs? Kind of like
http://www.gnu.org/software/emacs/tour/ but omitting the introductory
material covered by the tutorial, and more up to date. (That page
doesn't mention eshell, for example!)

There are surely many documents on the web that tour intermediate Emacs
features; I've written one myself. But I think it would be better if
such a document was part of Emacs, either as part of the manual or
otherwise, as easily accessible as the tutorial.

Topics-wise, I envision it would briefly cover things like:
- keyboard macros
- TRAMP
- the various ways to get help inside Emacs
- narrowing
- dired
- calc
- et cetera

The hope would be to give users a taste of some of the more advanced
features of Emacs. Then, if they are faced with a situation that one of
those features that they read about in the intermediate tutorial would
be useful for, they'll search the help system for more information
rather than be frustrated.

As an example, consider narrowing. If a user didn't already know
narrowing existed, they probably wouldn't even bother searching for the
feature; it isn't obvious how useful until you know about it. A user
without knowledge of narrowing would use other hacks.

As I said earlier, I have written such a document in org, because I
needed reference material to provide my students when I do Emacs
workshops. (It's still mostly a draft, and it's somewhat specific to the
workshops, so if you want to see it send me mail.) 

So, I wanted to see if emacs-devel thought this was a good idea, or a
bad idea, or if anyone had any suggestions. I would be happy to adapt
the document I've already written if that makes sense.

Thanks,
Spencer Baugh

Re: Intermediate tutorial shipped with Emacs

[Eli Zaretskii]

> From: Spencer Baugh <sbaugh@catern.com>
> Date: Fri, 18 Sep 2015 22:19:41 -0400
> 
> I think it would be good if Emacs shipped with an intermediate tutorial,
> covering topics beyond the basic tutorial.

It would, indeed.  The problem is, as always, what does "intermediate
tutorial" means for Emacs.

> Topics-wise, I envision it would briefly cover things like:
> - keyboard macros
> - TRAMP
> - the various ways to get help inside Emacs
> - narrowing
> - dired
> - calc
> - et cetera

Past discussions more or less concluded that there should be a series
of intermediate-level tutorials, each one covering topics in some
distinct area.  So the topics you present above, that are unrelated to
each other and probably reflect your personal interests (or even some
random selection) are probably not the way to go.  Tramp should
probably be in a tutorial dedicated to remote editing and URL-related
features; narrowing should be in a tutorial that also explains
folding, outline mode, hide-ifdef, and other similar features.  Calc
is a topic by itself (doesn't it include its own tutorial in its
manual?), perhaps together with Calculator.  Etc. etc. -- I would
suggest first to come up with a list of the areas, or at least produce
a couple of tutorials along these lines.

> The hope would be to give users a taste of some of the more advanced
> features of Emacs. Then, if they are faced with a situation that one of
> those features that they read about in the intermediate tutorial would
> be useful for, they'll search the help system for more information
> rather than be frustrated.

That's a challenge in itself: how do you give "a taste" of a feature
without describing it in full, or close to that.  The manual doesn't
describe all of the facets of each feature it covers, only the
important stuff, leaving the rest to be discovered by the user by
using the help system and the source.  You need some clear rules about
where to stop the "give a taste" description to avoid being another
version of the corresponding manual sections.

> As an example, consider narrowing. If a user didn't already know
> narrowing existed, they probably wouldn't even bother searching for the
> feature; it isn't obvious how useful until you know about it. A user
> without knowledge of narrowing would use other hacks.

A very good example.  Narrowing is described in the manual in a
58-line section.  How would you go about giving the user a "taste of"
narrowing, without essentially telling the same story in slightly
different words?  It's not trivial (but not impossible, either).

> As I said earlier, I have written such a document in org, because I
> needed reference material to provide my students when I do Emacs
> workshops. (It's still mostly a draft, and it's somewhat specific to the
> workshops, so if you want to see it send me mail.) 
> 
> So, I wanted to see if emacs-devel thought this was a good idea, or a
> bad idea, or if anyone had any suggestions. I would be happy to adapt
> the document I've already written if that makes sense.

More documentation is always a good idea, IMO.

Thanks.

Re: Intermediate tutorial shipped with Emacs

[Stephen J. Turnbull]

Eli Zaretskii writes:

 > Past discussions more or less concluded that there should be a series
 > of intermediate-level tutorials, each one covering topics in some
 > distinct area.  So the topics you present above, that are unrelated to
 > each other and probably reflect your personal interests (or even some
 > random selection) are probably not the way to go.

+1 to "probably".  I didn't resonate to that list myself, but I can't
really say that "most" new users wouldn't.

 > That's a challenge in itself: how do you give "a taste" of a feature
 > without describing it in full, or close to that.

"Not describing it in full" is pretty much the definition of "a
taste".

I would envision this intermediate tutorial as a series of "HOWTO"
do common tasks.  It would only explain enough of the feature to
implement the HOWTO, and provide links to the manual.

 > > So, I wanted to see if emacs-devel thought this was a good idea,
 > > or a bad idea, or if anyone had any suggestions. I would be happy
 > > to adapt the document I've already written if that makes sense.

I think that's the way to go.  Maybe post it or a link to it on the
EmacsWiki.

Re: Intermediate tutorial shipped with Emacs

[Rasmus]

"Stephen J. Turnbull" <stephen@xemacs.org> writes:

>  > That's a challenge in itself: how do you give "a taste" of a feature
>  > without describing it in full, or close to that.
>
> "Not describing it in full" is pretty much the definition of "a
> taste".
>
> I would envision this intermediate tutorial as a series of "HOWTO"
> do common tasks.  It would only explain enough of the feature to
> implement the HOWTO, and provide links to the manual.

I guess it's also a question of exposing nice features such a narrowing.
Sort of like the "discovery" tooltip shown in some programs, typically at
startup.

So I think a tutorial is as much about exposing "cool features".

Rasmus

-- 
Summon the Mothership!

Re: Intermediate tutorial shipped with Emacs

[Stephen J. Turnbull]

Rasmus writes:

 > I guess it's also a question of exposing nice features such a narrowing.
 > Sort of like the "discovery" tooltip shown in some programs, typically at
 > startup.

That kind of thing treat an arbitrarily long list of topics, since it
picks one more or less at random on each invocation.  One useful tip
in the first 5 or so and the user is hooked.  A tutorial devoting the
equivalent of a half-page to a page (occasionally more) to a single
topic can't work that way, it's only going to hold the reader's
attention so long, and after that they will put it away permanently.

RE: Intermediate tutorial shipped with Emacs

[Drew Adams]

> > I think it would be good if Emacs shipped with an intermediate tutorial,
> > covering topics beyond the basic tutorial.

Where "beyond" just means some stuff that is not covered in
the first tutorial.  It need not imply "more advanced" or
"more difficult".

It could be good to have such tutorials shipped with Emacs,
but that's not a requirement.  This is something that people
can easily contribute to (anywhere, in any way), and it can
sometimes be helpful to point to non-vanilla extensions.

> It would, indeed.  The problem is, as always, what does
> "intermediate tutorial" means for Emacs.
> 
> > Topics-wise, I envision it would briefly cover things like:
> > - keyboard macros
> > - TRAMP
> > - the various ways to get help inside Emacs
      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Yes.  And that's the reason I'm replying to this thread.  And
"get help" is an extensible concept.  For this topic, it's about
about getting help about getting help, and it goes way beyond
just `C-h', `apropos', and `C-h r'.

> > - narrowing
> > - dired
> > - calc
> > - et cetera
> 
> Past discussions more or less concluded that there should be a series
> of intermediate-level tutorials, each one covering topics in some
> distinct area.

Not necessarily "in some distinct area" (depending on what you
mean by that).  "Topics" need not mean separate areas of use
cases or separate features.  Some topics and some information
can be used everywhere in Emacs.

> So the topics you present above, that are unrelated to
> each other and probably reflect your personal interests (or even
> some random selection) are probably not the way to go.  Tramp
> should probably be in a tutorial dedicated to remote editing
> and URL-related features; 

> narrowing should be in a tutorial that also explains folding,
> outline mode, hide-ifdef, and other similar features.

Now there's a good example of what I mean by some topics being
_generally_ useful.  Narrowing is useful pretty much everywhere.
The other ways you cite of hiding & revealing information are not.

All share the characteristic of hiding and revealing (as do
some other features), but from that list only narrowing is
applicable everywhere.

> > As an example, consider narrowing. If a user didn't already know
> > narrowing existed, they probably wouldn't even bother searching for the
> > feature; it isn't obvious how useful until you know about it. A user
> > without knowledge of narrowing would use other hacks.
> 
> A very good example.  Narrowing is described in the manual in a
> 58-line section.  How would you go about giving the user a "taste of"
> narrowing, without essentially telling the same story in slightly
> different words?  It's not trivial (but not impossible, either).

I would perhaps put narrowing in a tutorial that shows making
use of the region in various ways.

[And if this were on the wiki or otherwise outside vanilla
Emacs, I would show how you can have multiple narrowings that
you can flip among, and multiple regions that you can act on,
together or separately.  That's from my library `zones.el',
but there are probably some other extensions that also let
you make more use of regions and narrowings.]

> > As I said earlier, I have written such a document in org, because I
> > needed reference material to provide my students when I do Emacs
> > workshops. (It's still mostly a draft, and it's somewhat specific to the
> > workshops, so if you want to see it send me mail.)
> >
> > So, I wanted to see if emacs-devel thought this was a good idea, or a
> > bad idea, or if anyone had any suggestions. I would be happy to adapt
> > the document I've already written if that makes sense.
> 
> More documentation is always a good idea, IMO.

OK, so some more doc might help.  And certainly there are
features, some of them basic or commonly used, some of them
less so, that users could benefit from seeing in action (video,
tutorials, etc.).  Showing examples of _what you can do_ with
a feature can be very helpful, and it is not really the aim
of our manuals, which are mostly reference (and rightfully so).

In a somewhat different direction (and the reason I'm replying
to this thread), it can be helpful to show users more about
how they can *ask Emacs* itself.

That means a tutorial about *help*, *apropos* commands and
using the *manuals* productively, sure, but also some *Lisp*
basics, with emphasis on how you can use them to ask Emacs
about itself - the current state, what happened, why, what
you can/cannot do next, etc.

This means some info about: evaluation; symbols; lists;
faces; text & overlay properties; strings, including
propertized; commands & other functions; startup, packages,
`load-path', and Customize; defcustom, defun, etc.; key
bindings, keymaps, and menus; `C-g', recursive minibuffers,
and `M-:'; `debug' & backtraces; how to file a bug report;
hooks & modes; and other info that many of us use everyday
but that new users might have no clue is available (because
it typically is not, in environments they are familiar with).

The emphasis would be on knowing something about such
things in order to ask Emacs questions that a non-expert
(or even an expert sometimes) might have.  It would also
cover common misconceptions, gotchas, what you can do
when you are lost, etc.

Much of the power of Emacs comes from the ease with which
you can dig into it to understand what is happening,
including what is going "wrong" according to your
expectations.  Emacs is open, from top to bottom.  How to
open it and peer within is the fundamental Emacs question
and the key to using Emacs as Emacs.

The second question of the following bug report is a good
example, and there are plenty of others, of how a user with
just a few additional pointers could have found the info
and understanding he was looking for:
http://debbugs.gnu.org/cgi/bugreport.cgi?bug=21510.
(Could he have found that info in the manual?  Of course.
That's not the question here.  Tutorials can also help.)

Nothing wrong with asking on a mailing list or forum, or
reporting a problem, of course - quite the contrary.  But
Emacs is especially easy to dig into, asking for info, and
learning Emacs has a lot to do with learning how to _ask
Emacs_.  Knowing _that_ you can do this, and then knowing
_how_ to do it, are not obvious to a newbie.

Asking Emacs does involve speaking Lisp to some extent,
and I think that some basic Lisp should be part of such
a tutorial from the _beginning_.  You need to be able to
find your way around basic Lisp constructs and ask Lisp,
to ask Emacs productively.

Re: Intermediate tutorial shipped with Emacs

[Spencer Baugh]

Eli Zaretskii <eliz@gnu.org> writes:
> Past discussions more or less concluded that there should be a series
> of intermediate-level tutorials, each one covering topics in some
> distinct area.  So the topics you present above, that are unrelated to
> each other and probably reflect your personal interests (or even some
> random selection) are probably not the way to go.  Tramp should
> probably be in a tutorial dedicated to remote editing and URL-related
> features; narrowing should be in a tutorial that also explains
> folding, outline mode, hide-ifdef, and other similar features.  Calc
> is a topic by itself (doesn't it include its own tutorial in its
> manual?), perhaps together with Calculator.  Etc. etc. -- I would
> suggest first to come up with a list of the areas, or at least produce
> a couple of tutorials along these lines.

I do like the idea of a series of tutorials. It would probably be easier
to produce tutorials that cover groups of related features rather than
all of Emacs, and each tutorial would probably be better for it.  The
two groupings you just named sound pretty good. I agree that either
producing a list of areas to write tutorials about, or just going ahead
and writing one of those tutorials, would be a good first step.

Still, I think it is important that new users be able to quickly get a
broad sense of the categories of features available in Emacs. Perhaps a
node that links to all these tutorials, and describes the subject area
of each of them in a paragraph or two of text? This would not only
include the tutorials about "remote-editing and URLs" and "hiding and
showing text", but also the Calc tutorial and other tutorials that
already exist.

That is kind of like the Emacs manual's top node, but perhaps more
helpful for discovering new features, since it could be more descriptive
than the single-line summaries, and also have less material to search
through by virtue of grouping some features together.

"Stephen J. Turnbull" <stephen@xemacs.org> writes:
> +1 to "probably".  I didn't resonate to that list myself, but I can't
> really say that "most" new users wouldn't.

The list I made is indeed just a random selection of topics, but ones
that I think most users would have immediate uses for. Obviously this is
somewhat subjective, I'm not really beholden to that list, it was just
to start the conversation.

> I would envision this intermediate tutorial as a series of "HOWTO"
> do common tasks.  It would only explain enough of the feature to
> implement the HOWTO, and provide links to the manual.

I like HOWTOs and FAQs, but I'm not sure what kind of tasks would be
suitable for explanation in the manual; I'd be worried about the manual
seeming dated or purpose-specific. If a tutorial just focuses on the
abilities of Emacs, then I don't think that problem arises.

>  > > So, I wanted to see if emacs-devel thought this was a good idea,
>  > > or a bad idea, or if anyone had any suggestions. I would be happy
>  > > to adapt the document I've already written if that makes sense.
>
> I think that's the way to go.  Maybe post it or a link to it on the
> EmacsWiki.

Yes, I'll definitely get around to doing that.

Re: Intermediate tutorial shipped with Emacs

[Eli Zaretskii]

> From: Spencer Baugh <sbaugh@catern.com>
> Cc: emacs-devel@gnu.org
> Date: Sat, 19 Sep 2015 12:13:25 -0400
> 
> Still, I think it is important that new users be able to quickly get a
> broad sense of the categories of features available in Emacs. Perhaps a
> node that links to all these tutorials, and describes the subject area
> of each of them in a paragraph or two of text?

I think this is impractical.  Emacs has so many different categories
of features in so many completely unrelated fields of application,
that it'd be a challenge to organize such a list in any way that
allows a user to quickly find the categories she might be interested
in.  Keep in mind that just explaining what is included in a category
might take a non-trivial amount of text.

> That is kind of like the Emacs manual's top node

Exactly!  So we already have that material in place.

> but perhaps more helpful for discovering new features, since it
> could be more descriptive than the single-line summaries, and also
> have less material to search through by virtue of grouping some
> features together.

Beware: "more descriptive" might also mean "too long".
Discoverability is hampered by having to wade through too long
descriptions of the stuff to be discovered.

For those reasons, I suggest a bottom-up approach: first let's have a
few of such tutorials, and then let's think how to help users discover
them.  As long as the number of tutorials is small, just their list is
good enough, IMO.  So we can postpone a more serious "guide to
tutorials" when we have enough of them to necessitate such a guide.

Re: Intermediate tutorial shipped with Emacs

[Marcin Borkowski]

On 2015-09-19, at 12:00, Rasmus <rasmus@gmx.us> wrote:

> I guess it's also a question of exposing nice features such a narrowing.
> Sort of like the "discovery" tooltip shown in some programs, typically at
> startup.

Why not implement exactly this, and suggest to put

(show-random-tip)

into your init.el at the end of the existing tutorial?

> Rasmus

Best,

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Faculty of Mathematics and Computer Science
Adam Mickiewicz University

Re: Intermediate tutorial shipped with Emacs

[Marcin Borkowski]

On 2015-09-19, at 09:22, Eli Zaretskii <eliz@gnu.org> wrote:

>> From: Spencer Baugh <sbaugh@catern.com>
>> Date: Fri, 18 Sep 2015 22:19:41 -0400
>> 
>> As an example, consider narrowing. If a user didn't already know
>> narrowing existed, they probably wouldn't even bother searching for the
>> feature; it isn't obvious how useful until you know about it. A user
>> without knowledge of narrowing would use other hacks.
>
> A very good example.  Narrowing is described in the manual in a
> 58-line section.  How would you go about giving the user a "taste of"
> narrowing, without essentially telling the same story in slightly
> different words?  It's not trivial (but not impossible, either).

My 2 cents:

* I like the idea of having "batteries included", and the tutorial being
  part of Emacs.  However, aren't e.g. Sacha Chua's Emacs chats better
  for that purpose, where a human being explains his particular
  use-case?

* Also, along these lines: maybe such tutorials should be centered
  around "scenarios", and not features?  Like, take a "scenario" called
  "C editing".  Then you can mention narrowing, compilation mode, maybe
  rgrep and a few other things.  Or, take a scenario "HTML editing".
  Then you can have SGML mode, TRAMP, maybe Org-mode and exporting, etc.
  Also, in such tutorials it would make sense to mention ELPA packages
  (and possibly MELPA, too).

Best,

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Faculty of Mathematics and Computer Science
Adam Mickiewicz University

Re: Intermediate tutorial shipped with Emacs

[Filipp Gunbin]

On 18/09/2015 22:19 -0400, Spencer Baugh wrote:

> I think it would be good if Emacs shipped with an intermediate tutorial,
> covering topics beyond the basic tutorial. Reading the entire manual is
> great, but wouldn't it be nice if there was a short/medium-length
> overview of some of the cool features of Emacs? Kind of like
> http://www.gnu.org/software/emacs/tour/ but omitting the introductory
> material covered by the tutorial, and more up to date. (That page
> doesn't mention eshell, for example!)

I remember that almost five years ago I finally ended the year of
fruitless attempts to convert Emacs into an IDE like ones I used before
and realized that I need to learn text editing.  I had much work at the
moment and did not have time to read the manual in-depth and this
article [1] helped me to get into it.

I find the text & the format nearly ideal to what I expect from a short
"intermediate manual" - a bit of naming things and a bit of explaining.

Other manuals from the same author were not as useful as this one,
mainly because the topics are less wide than "editing and movement", but
still sometimes I find something new in his texts.

This leads to another (quite obvious) thought: more features should be
documented in the manual.  Even a quick mentioning will be enough to
give a pointer.

Filipp

[1] https://www.masteringemacs.org/article/effective-editing-movement