RE: Intermediate tutorial shipped with Emacs

[Drew Adams <drew.adams@oracle.com>]

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