Re: Why does the tutorial talk about C-n/C-p etc?

[Marcin Borkowski <mbork@mbork.pl>]

On 2016-03-13, at 20:03, Eli Zaretskii <eliz@gnu.org> wrote:

>> From: Clément Pit--Claudel <clement.pit@gmail.com>
>> Date: Sun, 13 Mar 2016 14:41:54 -0400
>> 
>> Here are a few things that I struggled with when I started using Emacs (phrased in terms of concepts that I was already familiar with)
>> 
>> * Opening and saving a file
>> * Copying (or cutting) and pasting
>> * Undoing, and in particular the notion of undoing an undo
>> * Using C-u as a prefix
>> * Searching (and replacing)
>> * The notion of major and minor modes

And how to exit Emacs;-).

How about an "official" "tip of the day" feature?  Like showing a "Did
you know...?" tip /in the scratch buffer/ (or the splash screen)?

>> Interestingly, the tutorial does cover all of this; but it also tried to train me to be efficient at things that I didn't care (like having me jump around the buffer, paging through things with C-v, etc): what I wanted was a five minutes introduction which would:
>> 
>> * Give me enough to survive in Emacs with more or less the same productivity as I has in GEdit (which was pretty low)
>> * Teach me a few cool features so that I felt compelled to keep using Emacs
>> 
>> Based on this, it would be easy to pick up more stuff along the way.
>> 
>> Speaking of cool features, here are a few ones that are very simple to comprehend, but that I find very useful; I think the tutorial could expose them:
>> 
>> * C-SPC C-SPC to mark a point
>> * C-u C-SPC to jump to a previously marked point
>> * C-w marking the following word during a search

+1 for all these.  Also, C-M-v.  Also, transposing commands.  Also,
[insert your favorite cool & useful stuff here]...

> I see your point.  But here's the problem:
>
>  * The tutorial explicitly aims at making you more productive than
>    you'd be in GEdit or Notepad, as high productivity is one of
>    Emacs's string selling points
>  * The set of "cool features" that users would like to be taught is
>    highly variable from one user to another, and their superset is way
>    too large for a tutorial
>
> The only practical solution to the dilemma is to have multiple
> tutorials.  This is not ideal, either, because many newcomers will not
> know enough to choose the ones they want, but it's a step in the right
> direction (IMO).

Agreed.  On the other hand, the same can be said about the manual, which
is not extremely concise...

> The only problem is to find volunteers who'd actually write such
> tutorials.

I already started to exchange ideas with Phil, and have like 8kB of one
of such possible tutorials.  I'd be happy to write more; I like writing
in a natural language, though as a non-native English speaker (and not
having a disguise like Eli's;-)) I will probably need my texts
polished by someone.

I could contribute to a tutorial about basics of Elisp (for people
prefering a more interactive approach than Chassell's book) - this is
actually the one I started writing. Also, Org-mode.  Dired might be
tricky to pull off, but we can artificially create a simple directory
structure somewhere in /tmp to play around with - and then it would be
really nice.  Calc already has a good tutorial/introduction.

And we definitely need a tutorial on asking Emacs about its state - all
those descibe-.* commands, C-h bindings, apropos-.* commands etc.

It also just occurred to me that instead of writing tutorials for
various programming languages, we could have one general tutorial for
coding and one for writing prose.  I could contribute especially to the
latter one.

>> In addition, I think many people get attracted to Emacs for a particular programming language, so I like the suggestion of the tutorial branching up into various directions after exposing the basics.
>
> I actually think that a tutorial should demonstrate the common stuff,
> i.e. how the same commands do different things in each major mode.
> For the details that are specific to each mode users should read the
> respective manuals and doc strings, as describing them in a tutorial
> will make that tutorial be very much like the manual ;-)

Yes and no.  Manual should be comprehensive, and a tutorial can be just
a quick showcase of possibilities.

An important question is: may a tutorial mention/suggest a Melpa package
(assuming it's GPL'd, for instance)?

>> One final idea: maybe the tutorial could showcase more of Emacs' fancy features? Like syntax highlighting, spell checking, image support, indentation, and similar things? Right now it's a plain text buffer in fundamental mode.
>
> Excellent ideas, but again: we need someone to step forward and
> actually do all that.  Most of us are not good at writing such
> interactive documentation.

OK, how about some showing off;-)?  I authored two books (one on pure
math, in English, and one - coauthored with a friend - which is an
introductory textbook on LaTeX, in Polish).  I'm in the process of
writing two more (both in English, one solo and one with two coauthors).
I also prepared a few short e-learning courses, some of them consisting
of videocasts with accompanying textual material, and one of them (which
is work in progress) being a highly interactive course on basics of
mathematical analysis.  This one is probably closest to a "tutorial",
since in each part the student is expected to answer a series of short
and simple questions, and the answers taken together form a proof of
a theorem.

I don't claim that I'm "good" at writing such things.  But definitely
I (a) do have some experience at it, (b) like writing such stuff a lot,
(c) am willing to write a few for Emacs, and (d) have my FSF papers
signed.

I will need, however, people to help.  At least to proofread and
criticize what I'll have written (especially to help make it short,
since I tend to be too verbose), also to brainstorm ideas.

I'm rather busy now, and it's not likely to change a lot in the near
future.  However, I have assigned an hour a day for writing prose, and
I'd be happy to devote 15-30 minutes of that for Emacs tutorials within
the next few weeks.

Best,

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