Re: Emacs Book Vs Emacs Manuals

[Eli Zaretskii]

> From: Vaidheeswaran C <vaidheeswaran.chinnaraju@gmail.com>
> Date: Sun, 17 May 2015 21:05:26 +0530
> 
> On Saturday 16 May 2015 01:02 PM, Eli Zaretskii wrote:
> 
> > Again, I think we already do all that in the Emacs manuals, where
> > appropriate.
> 
> - Emacs Manual :: I am arguing for FSF-blessed, Task-oriented "Emacs
>                   Primer".

And I am trying to tell you that a task-oriented Emacs Book might not
be the best idea.

> - 'Appropriate' :: The word "Approrpriate" is situational.  Who
>                    decides what is appropriate?  The maintainers, the
>                    users or the author of the manual.

The maintainers, who are also the authors of the manual.  It is always
the author who decides, and users then submit bug reports if they
don't like the result.

> In so far as "Emacs Primer" is concerned, the Noobs become
> authorities.  If they say something is "inappropriate" (from where
> they stand), then it will be deemed as such, without further
> disputation.

The issue at hand is not what is "inappropriate", but what is
"appropriate".  Saying that some material is described in a way that
hampers understanding and usability is not enough for fixing the
inadequacy: whoever fixes that has to come up with a more
"appropriate" alternative.

IOW, the users complain about the "inappropriate", and no one casts
doubt in their right to do so.  But the complaint alone is not enough
to come up with a better alternative.  And that is what I was talking
about.

> > But please note the catch in this approach, if used indiscriminately:
> > the number of potential "Tasks" that an Emacs user can face is
> > virtually infinite.  These tasks break into certain "building blocks",
> > which are combined in many different ways.  If you always describe the
> > "tasks", then you will need to repeat the description of these
> > building blocks time and time again, which is a disadvantage.
> 
> The question is: Whose "disadvantage" are you talking about?

Everyone's.

> > IOW, the above methodology is suitable only to relatively simple tools
> > that support a small number of well-defined tasks.  Emacs is not like
> > that, especially if you take ELisp into consideration, because that's
> > a reasonably general-purpose programming language, where the
> > task-based approach is unsuitable, IMO.
> 
> In so far as "Emacs Primer" is concerned, Elisp will be out-of-scope.

If so, you are limiting the usability of your book too much.  Most of
customizations, for example, need to use Lisp, or at least understand
it.  If you leave it out of scope, your book will be abandoned by many
users, because most of the tips they will find in the net do use Lisp.

> The cookbooks and recipes are particularly popular and useful
> http://www.emacswiki.org/emacs/ElispCookbook.

I'm saying that a cookbook approach is not advisable, to say the
least, for a tool as complex and versatile/flexible as Emacs.