Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS

Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS

[solidius4747]

Hi everyone,

I wrote part 3: http://tuhdo.github.io/emacs-tutor3.html

It includes popular packages that people are using. If you are new to Emacs, it would be useful.

Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS

[James Freer]

On 01/07/2014, solidius4747@gmail.com <solidius4747@gmail.com> wrote:
> Hi everyone,
>
> I wrote part 3: http://tuhdo.github.io/emacs-tutor3.html
>
> It includes popular packages that people are using. If you are new to Emacs,
> it would be useful.
>

I'm very grateful for the time you have spent although now after a
couple of weeks I have learnt enough to be happy with. I've found
using emacs-nox and forgetting about the gui is worthwhile and taking
time to learn from the cheatsheet. It would be nice to have the 'mini
manual' in pdf then one could print it out and read on the train (or
similar times when one is away from the PC).

thanks
james

Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS

[Emanuel Berg]

James Freer <jessejazza3.uk@gmail.com> writes:

> I'm very grateful for the time you have spent
> although now after a couple of weeks I have learnt
> enough to be happy with. I've found using emacs-nox
> and forgetting about the gui is worthwhile and taking
> time to learn from the cheatsheet. It would be nice
> to have the 'mini manual' in pdf then one could print
> it out and read on the train (or similar times when
> one is away from the PC).

Do my ears deceive me?! Finally a guy with class!
F*ing right!

I haven't seen the particular document, though. I will
read it tonight and probably get back to the OP with
some comments.

If you don't like to just print and read the HTML, you
can use several tools to get it to PDF. You can use
html2ps, and then ps2pdf - html2ps is in the repos,
ps2pdf is part of ghostscript, which is likewise in the
repos. (There are other ways to do this as well.)

-- 
underground experts united:
http://user.it.uu.se/~embe8573

Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS

[James Freer]

On Tue, 1 Jul 2014, Emanuel Berg wrote:

> James Freer <jessejazza3.uk@gmail.com> writes:
>
>> I'm very grateful for the time you have spent
>> although now after a couple of weeks I have learnt
>> enough to be happy with. I've found using emacs-nox
>> and forgetting about the gui is worthwhile and taking
>> time to learn from the cheatsheet. It would be nice
>> to have the 'mini manual' in pdf then one could print
>> it out and read on the train (or similar times when
>> one is away from the PC).
>
> Do my ears deceive me?! Finally a guy with class!
> F*ing right!
>
> I haven't seen the particular document, though. I will
> read it tonight and probably get back to the OP with
> some comments.
>
> If you don't like to just print and read the HTML, you
> can use several tools to get it to PDF. You can use
> html2ps, and then ps2pdf - html2ps is in the repos,
> ps2pdf is part of ghostscript, which is likewise in the
> repos. (There are other ways to do this as well.)

html2ps
I'll have to look up

I knew about ps2pdf and pdf2ps as I use it to send faxes. (yes fax still has 
a use). Or maybe I need to look at other methods.

When I 'read on a train' - in truth I really meant that I like the pdf to print 
out, bind, and then use like a book for bedtime reading. keen beginner eh.

james

Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS

[Emanuel Berg]

solidius4747@gmail.com writes:

> I wrote part 3:
> http://tuhdo.github.io/emacs-tutor3.html
>
> It includes popular packages that people are
> using. If you are new to Emacs, it would be useful.

I wouldn't call that tutorial "mini"!

It is clear you put a very big effort into this. You
should get a medal, or some part of the gold stashed in
IET, the International Emacs Treasury (if there is
one).

But, this makes me think, did you experience any
shortcomings or "gaps" in the official Emacs manual?
Perhaps you could integrate your project with it,
somehow. If not, the official Emacs people should put a
link to your project from the official site, at least,
if they didn't already.

Feedback on the material itself: the part on MELPA,
what I can see it misses one essential part, namely how
to *submit* code: both how that is done in practice,
and guidelines on the Elisp itself (or references, if
you don't feel like writing this all over).

Keep it up!

-- 
underground experts united

Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS

[solidius4747]

Vào 21:38:24 UTC+7 Thứ ba, ngày 01 tháng bảy năm 2014, jessejazza đã viết:
> On Tue, 1 Jul 2014, Emanuel Berg wrote:
> 
> 
> 
> > James Freer <jessejazza3.uk@gmail.com> writes:
> 
> >
> 
> >> I'm very grateful for the time you have spent
> 
> >> although now after a couple of weeks I have learnt
> 
> >> enough to be happy with. I've found using emacs-nox
> 
> >> and forgetting about the gui is worthwhile and taking
> 
> >> time to learn from the cheatsheet. It would be nice
> 
> >> to have the 'mini manual' in pdf then one could print
> 
> >> it out and read on the train (or similar times when
> 
> >> one is away from the PC).
> 
> >
> 
> > Do my ears deceive me?! Finally a guy with class!
> 
> > F*ing right!
> 
> >
> 
> > I haven't seen the particular document, though. I will
> 
> > read it tonight and probably get back to the OP with
> 
> > some comments.
> 
> >
> 
> > If you don't like to just print and read the HTML, you
> 
> > can use several tools to get it to PDF. You can use
> 
> > html2ps, and then ps2pdf - html2ps is in the repos,
> 
> > ps2pdf is part of ghostscript, which is likewise in the
> 
> > repos. (There are other ways to do this as well.)
> 
> 
> 
> html2ps
> 
> I'll have to look up
> 
> 
> 
> I knew about ps2pdf and pdf2ps as I use it to send faxes. (yes fax still has 
> 
> a use). Or maybe I need to look at other methods.
> 
> 
> 
> When I 'read on a train' - in truth I really meant that I like the pdf to print 
> 
> out, bind, and then use like a book for bedtime reading. keen beginner eh.
> 
> 
> 
> james

I'm glad that you like my tutorial. I'm working on how to generate a pdf document with org-mode. Not sure how many pages my "mini manual" actually consumes. I didn't intend it to be a book in the first place.

Vào 06:12:10 UTC+7 Thứ ba, ngày 08 tháng bảy năm 2014, Emanuel Berg đã viết:
> solidius4747@gmail.com writes:
> 
> 
> 
> > I wrote part 3:
> 
> > http://tuhdo.github.io/emacs-tutor3.html
> 
> >
> 
> > It includes popular packages that people are
> 
> > using. If you are new to Emacs, it would be useful.
> 
> 
> 
> I wouldn't call that tutorial "mini"!
> 
> 
> 
> It is clear you put a very big effort into this. You
> 
> should get a medal, or some part of the gold stashed in
> 
> IET, the International Emacs Treasury (if there is
> 
> one).
> 
> 
> 
> But, this makes me think, did you experience any
> 
> shortcomings or "gaps" in the official Emacs manual?
> 
> Perhaps you could integrate your project with it,
> 
> somehow. If not, the official Emacs people should put a
> 
> link to your project from the official site, at least,
> 
> if they didn't already.
> 
> 
> 
> Feedback on the material itself: the part on MELPA,
> 
> what I can see it misses one essential part, namely how
> 
> to *submit* code: both how that is done in practice,
> 
> and guidelines on the Elisp itself (or references, if
> 
> you don't feel like writing this all over).
> 
> 
> 
> Keep it up!
> 
> 
> 
> -- 
> 
> underground experts united

Thanks! 

As I stated in Part 1 in "Why I wrote this guide" section, it is because I feel the Emacs manual is designed to be more like a reference material than a beginner material. It also does not mention about popular 3rd party packages, and popular package archives like MELPA. Where should new users to Emacs find this information? They will have to waste time to rediscover packages that people used long ago. I want to get productive with Emacs as fast as possible. Telling people to read the whole Emacs Lisp manual before able to customizing/extending Emacs is likely to push them away from Emacs.

As for submitting code to MELPA, I don't think it's necessary to include in the guide, because clearly the targeted audience is beginners who just start their journey with customizing/extending Emacs. It's unlikely they will roll a package on their own after finishing the guide anyway.

Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS

[solidius4747]

Vào 06:12:10 UTC+7 Thứ ba, ngày 08 tháng bảy năm 2014, Emanuel Berg đã viết:

> I wouldn't call that tutorial "mini"!

It's mini relative to size of the official manuals.

Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS

[Emanuel Berg]

solidius4747@gmail.com writes:

> As I stated in Part 1 in "Why I wrote this guide"
> section, it is because I feel the Emacs manual is
> designed to be more like a reference material than a
> beginner material.

I only have a very old version of the manual - Emacs
18, I think - but I read that twice. It wasn't
difficult to understand but I noticed there were gaps
in it when I compared how I used Emacs. There was no
mention of Gnus and I don't remember if RMAIL was
mentioned, for example, but there were material on the
message-mode, perhaps to be used between Unix boxes on
an intranet (?) - of course, if those things weren't
around then, they couldn't have been included - but as
for being a reference, I don't remember it being too
difficult to digest, on the contrary I remember it
being pleasant to read (big sheets, wide margins, clear
and normal language, and so on).

> It also does not mention about popular 3rd party
> packages, and popular package archives like MELPA.

It is not only the manual who is quiet about MELPA. I
didn't know of it until recently, when I learned about
it - ironically - on gnu.emacs.sources.

In this book

@Book{cameron,
author = {Cameron and Elliot and Loy and Raymond and Rosenblatt},
title = {Learning GNU Emacs},
publisher = {O'Reilly},
year = 2004,
ISBN = {0-596-00648-9},
edition = {3rd edition}}

there is a very short chapter on packages and online,
unofficial repositories, but it doesn't say how to use
it and it doesn't mention MELPA or even ELPA.

So, all the more reason (in my mind) for you to mention
it in more detail, or at least to provide a reference
to "how to broadcast" as that is as vital a part as is
downloading/installing. It just seems clear to me.

> Where should new users to Emacs find this
> information? They will have to waste time to
> rediscover packages that people used long ago.

Right, that's always the case. However, just knowing
about MELPA won't have people discovering what they
want instantly. Of course, first they must know what
they want, which always takes time, and is natural and
nothing that we should (could) influence (to any extent
anyway). But the second part is: finding what they
want. So how do you search MELPA? And how do you know
what to search for, if you terminology is different
from the person who wrote the package? Great things to
discuss here, as well as to include...

> I want to get productive with Emacs as fast as
> possible.

Everything in time...

> Telling people to read the whole Emacs Lisp manual
> before able to customizing/extending Emacs is likely
> to push them away from Emacs.

We should of course never tell anyone to read the
manual, and especially not the whole Elisp manual :) We
can post URLs. Best way is for course to do that, but
also explain how it relates to the particular problem,
and even support example Elisp. But sometimes there
isn't the energy, time or will to do that, and then a
HTTP manual in small chapters is great so you at least
can give the URL.

> As for submitting code to MELPA, I don't think it's
> necessary to include in the guide, because clearly
> the targeted audience is beginners who just start
> their journey with customizing/extending Emacs. It's
> unlikely they will roll a package on their own after
> finishing the guide anyway.

Well, I disagree here. First, the beginners will use
your tutorial, yes, but that's not it. They will also
write Elisp and configure Emacs and use Emacs and the
online help. They are likely to also come across the
Emacs manual, the Elisp manual, perhaps even the Gnus
manual, and of course the EmacsWiki if they happen to
Google problems (very likely). You yourself said MELPA
didn't get enough attention (and I agree), so if the
readers come across it in your book, at some point they
will ask - "how do I use MELPA in a more advanced way:
searching, filtering, submitting?" - at that point, if
the readers first came across it in your book, they
will instinctively reach for that book. If they read
about it somewhere else, they'll go for that source, of
course. But we (you) cannot influence that, can be?
Better make your own source as complete as possible.

-- 
underground experts united

Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS

[Emanuel Berg]

solidius4747@gmail.com writes:

>> I wouldn't call that tutorial "mini"!
>
> It's mini relative to size of the official manuals.

OK, again, I read an age-old one. That was perhaps 200
pages. Perhaps the more recent ones are huge. That
would certainly reflect the scope. I'll get one, if I
can...

But the word "mini", you tend to think of something
small. The Persian miniatures. A minibike. OK, a
minibike is relative a normal bike. But it is still
small :)

Seriously, you wrote it, you name it - even Linus
Torvalds is fine with distros calling it GNU/Linux. I
guess he was just born that generous... ;)

-- 
underground experts united

RE: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS

[Drew Adams]

> I only have a very old version of the manual - Emacs
> 18, I think - but I read that twice.

Really?  You have _only_ an old version?

If you have a version of Emacs more recent than 18 then you should
also have its manual, as part of Emacs.

(And if you do have the manual for your version then you should be
reading that, not (just) the Emacs 18 manual.)

Even if, for some reason, you do not have a more recent manual
than 18, recent manuals are available online.  For example:
http://www.gnu.org/software/emacs/manual/.

Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS

[solidius4747]

Vào 22:09:49 UTC+7 Thứ ba, ngày 08 tháng bảy năm 2014, Emanuel Berg đã viết:

> I only have a very old version of the manual - Emacs
> 
> 18, I think - but I read that twice. It wasn't
> 
> difficult to understand but I noticed there were gaps
> 
> in it when I compared how I used Emacs. There was no
> 
> mention of Gnus and I don't remember if RMAIL was
> 
> mentioned, for example, but there were material on the
> 
> message-mode, perhaps to be used between Unix boxes on
> 
> an intranet (?) - of course, if those things weren't
> 
> around then, they couldn't have been included - but as
> 
> for being a reference, I don't remember it being too
> 
> difficult to digest, on the contrary I remember it
> 
> being pleasant to read (big sheets, wide margins, clear
> 
> and normal language, and so on).
> 
> 
> 
> > It also does not mention about popular 3rd party
> 
> > packages, and popular package archives like MELPA.
> 
> 
> 
> It is not only the manual who is quiet about MELPA. I
> 
> didn't know of it until recently, when I learned about
> 
> it - ironically - on gnu.emacs.sources.
> 
> 
> 
> In this book
> 
> 
> 
> @Book{cameron,
> 
> author = {Cameron and Elliot and Loy and Raymond and Rosenblatt},
> 
> title = {Learning GNU Emacs},
> 
> publisher = {O'Reilly},
> 
> year = 2004,
> 
> ISBN = {0-596-00648-9},
> 
> edition = {3rd edition}}
> 
> 
> 
> there is a very short chapter on packages and online,
> 
> unofficial repositories, but it doesn't say how to use
> 
> it and it doesn't mention MELPA or even ELPA.
> 
> 
> 
> So, all the more reason (in my mind) for you to mention
> 
> it in more detail, or at least to provide a reference
> 
> to "how to broadcast" as that is as vital a part as is
> 
> downloading/installing. It just seems clear to me.
>

The recent GNU Emacs Manual is more than 600 pages long: http://www.gnu.org/software/emacs/manual/pdf/emacs.pdf 

It includes packages like Semantic, EDE, Calc, GUD... (I am using these packages myself). That's a lot of features. Certainly, users won't need to learn of those to be productive. It's likely that users usually read cover from cover, so they will be distracted by unnecessary stuffs not needed at the moment. The exported PDF of part 1 is only 43 pages long and part 3 is 83 pages long. Certainly mini compared to the actual manual. I also added screencasts to demonstrate what Emacs is capable of. I want to ensure the new users that learning Emacs worth their time. I also explicitly stated that the official Emacs manual is the next place they should look for if they want to get the most of Emacs. My manual only provides a starting point.
 
> Right, that's always the case. However, just knowing
> 
> about MELPA won't have people discovering what they
> 
> want instantly. Of course, first they must know what
> 
> they want, which always takes time, and is natural and
> 
> nothing that we should (could) influence (to any extent
> 
> anyway). But the second part is: finding what they
> 
> want. So how do you search MELPA? And how do you know
> 
> what to search for, if you terminology is different
> 
> from the person who wrote the package? Great things to
> 
> discuss here, as well as to include...

MELPA is really useful. It helped me to discover many useful packages and ease package management. Before that, I added packages as submodules in my .emacs.d git repo. I think once users know MELPA, even if they do not know what they want, they will explore the packages, install and play with it - like I did - and discover features not available in other editors; for example, Helm, Magit, undo-tree...


> We should of course never tell anyone to read the
> 
> manual, and especially not the whole Elisp manual :) We
> 
> can post URLs. Best way is for course to do that, but
> 
> also explain how it relates to the particular problem,
> 
> and even support example Elisp. But sometimes there
> 
> isn't the energy, time or will to do that, and then a
> 
> HTTP manual in small chapters is great so you at least
> 
> can give the URL.

I did provide it in part 3, not to the manual, but encourage new users to directly use Emacs for looking up functions and stuffs, as you can see in the section "Just enough Emacs Lisp" for each listed function. But probably I will provide a link to the function in the official Elisp manual, so they can compare and contrast.


> Well, I disagree here. First, the beginners will use
> 
> your tutorial, yes, but that's not it. They will also
> 
> write Elisp and configure Emacs and use Emacs and the
> 
> online help. They are likely to also come across the
> 
> Emacs manual, the Elisp manual, perhaps even the Gnus
> 
> manual, and of course the EmacsWiki if they happen to
> 
> Google problems (very likely). You yourself said MELPA
> 
> didn't get enough attention (and I agree), so if the
> 
> readers come across it in your book, at some point they
> 
> will ask - "how do I use MELPA in a more advanced way:
> 
> searching, filtering, submitting?" - at that point, if
> 
> the readers first came across it in your book, they
> 
> will instinctively reach for that book. If they read
> 
> about it somewhere else, they'll go for that source, of
> 
> course. But we (you) cannot influence that, can be?
> 
> Better make your own source as complete as possible.

Yes, I know. That's the route I worked through when I was new to Emacs. But I still want new users to be productive with Emacs as possible, with minimal Elisp. To be honest, I'm not an expert with Emacs Lisp; I'm still learning (I actually want to be proficient with Common Lisp first) and I only have limited experience with Racket from some Coursera courses ("Introduction to Systematic Design" - which uses the book How to Design Program and "Programming Languages" that I wrote a small evaluator for a made up language).

I always encourage users to seek help from the official manual and especially, within Emacs itself, in all of my articles. In part 3, I only want to introduce enough Emacs Lisp that new users can feel comfortable with using MELPA to add package for extending Emacs, rather than taking the hard route, that is actually learn and write Elisp. I think, after new users use various Emacs packages from the community comfortable, they will see the power of Emacs and have an interest in learning Elisp, just like I did. That's why I listed many popular and useful packages, one by one in this part, along with how to set up the packages properly to start using it. I believe, by repeating adding packages and Elisp code configuration, new users will get comfortable with Elisp and extending Emacs in general. My goal is to have an interested-in-Emacs reader to get what I demonstrated in part 1 in about a month or less.

As for searching and filtering packages using the package manager, I will add it.

Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS

[solidius4747]

Vào 22:15:45 UTC+7 Thứ ba, ngày 08 tháng bảy năm 2014, Emanuel Berg đã viết:
> solidius4747@gmail.com writes:
> 
> 
> 
> >> I wouldn't call that tutorial "mini"!
> 
> >
> 
> > It's mini relative to size of the official manuals.
> 
> 
> 
> OK, again, I read an age-old one. That was perhaps 200
> 
> pages. Perhaps the more recent ones are huge. That
> 
> would certainly reflect the scope. I'll get one, if I
> 
> can...
> 
> 
> 
> But the word "mini", you tend to think of something
> 
> small. The Persian miniatures. A minibike. OK, a
> 
> minibike is relative a normal bike. But it is still
> 
> small :)
> 
> 
> 
> Seriously, you wrote it, you name it - even Linus
> 
> Torvalds is fine with distros calling it GNU/Linux. I
> 
> guess he was just born that generous... ;)
> 
> 
> 
> -- 
> 
> underground experts united

The current Elisp manual is over 1000 pages long: https://www.gnu.org/software/emacs/manual/pdf/elisp.pdf . Mine is over 100 pages long in PDF, so I think it's safe to call it mini.


As for the Emacs Manual, it is currently over 600 pages long: http://www.gnu.org/software/emacs/manual/pdf/emacs.pdf . Mine is over 43 pages long. I also cover how to install and the issue with Capslock/Control, and how to swap the two to get a better Emacs experience (and other things that use Control in general).

Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS

[Robert Thorpe]

Emanuel Berg <embe8573@student.uu.se> writes:

> solidius4747@gmail.com writes:
>
...
>
> I only have a very old version of the manual - Emacs
> 18, I think - but I read that twice. It wasn't
> difficult to understand but I noticed there were gaps
> in it when I compared how I used Emacs. There was no
> mention of Gnus and I don't remember if RMAIL was
> mentioned, for example, but there were material on the
> message-mode, perhaps to be used between Unix boxes on
> an intranet (?) - of course, if those things weren't
> around then, they couldn't have been included - but as
> for being a reference, I don't remember it being too
> difficult to digest, on the contrary I remember it
> being pleasant to read (big sheets, wide margins, clear
> and normal language, and so on).

I recommend using a new version of the Emacs manual set.  The last
version of Emacs 18 was released more than 21 years ago.  The current
manual describes RMAIL in detail.  A separate manual describes GNUS,
that manual is part of the set.  "Message-mode" is the mode for
composing email and newsgroup posts that comes with GNUS.  It's used
by GNUS, RMAIL and several other programs.  It's frequently used, I'm
using it now, that's why it's included in the manual set.  Of-course
reading an old manual is still useful, many things haven't changed.

Most of the manuals provide basic help on using a feature *and* more
advanced info.  So, the manuals can be read as a reference, or read
selectively.  I'm in the process of re-reading the Emacs manual myself.
I've found quite a lot of useful stuff.

This isn't a criticism of solidius4747's tutorial.  I haven't had a
chance to read it yet, so I can't comment.  I agree that there are
many things that should be treated in the manual that aren't there.

BR,
Rob

Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS

[Emanuel Berg]

Drew Adams <drew.adams@oracle.com> writes:

>> I only have a very old version of the manual - Emacs
>> 18, I think - but I read that twice.
>
> Really?  You have _only_ an old version?

Yes. It is actually a very cool item. The pages are in
A4 and it has a light-blue cover and dark-blue heft. A
big section is about the GNU philosophy. It is in
questions and answers, and in the questions there is
criticism of the whole idea. That's brave! You get the
feeling it was much more alive back then and not just a
set of axioms, a "stamp" you accept in principle but
nonetheless ignore in practice, eager to get to the
technology part of whatever documentation or piece of
source.

> If you have a version of Emacs more recent than 18
> then you should also have its manual, as part of
> Emacs.

Well, this is actually not the case as was recently
discussed in another thread. With 'info Emacs' I get
the Emacs FAQ, not the manual. There was mention of
some bad blood between the Emacs people and the Debian
people, who considered the Emacs manual non-free (no idea
why). I have of course access to the non-free repos, but
there is no emacs-doc like with gcc which documentation
(the manpage) Debian also has issues with.

Wait - I think I got it, it is probably
emacs24-common-non-dfsg, right? DFSG is "Debian Free
Software Guidelines".

> (And if you do have the manual for your version then
> you should be reading that, not (just) the Emacs 18
> manual.)

Well, should and should... I'm not going to read it on
the screen by the computer, that's for sure.

> Even if, for some reason, you do not have a more
> recent manual than 18, recent manuals are available
> online.  For example:
> http://www.gnu.org/software/emacs/manual/

Yes, this seems to be the PDF, ready to print:

http://www.gnu.org/software/emacs/manual/pdf/emacs.pdf

Alright, I'll do it. I know you contributed to it so
I'll just blame you for everything I don't like. But
actually I think I'll like all or most of it.

-- 
underground experts united

Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS

[Emanuel Berg]

solidius4747@gmail.com writes:

> The recent GNU Emacs Manual is more than 600 pages
> long:
> http://www.gnu.org/software/emacs/manual/pdf/emacs.pdf
>
> It includes packages like Semantic, EDE, Calc,
> GUD... (I am using these packages myself). That's a
> lot of features. Certainly, users won't need to learn
> of those to be productive.

It depends what packages and what users, and what they
do.

> It's likely that users usually read cover from cover

I think that is very unlikely for the majority of Emacs
users. But it is not a bad idea to do - on the
contrary...

> so they will be distracted by unnecessary stuffs not
> needed at the moment. The exported PDF of part 1 is
> only 43 pages long and part 3 is 83 pages
> long. Certainly mini compared to the actual manual.

I think "mini" is 1-3 pages. But you wrote it, you name
it. of course.

> I also added screencasts to demonstrate what Emacs is
> capable of.

Screencast = screenshot or dump? If so, that's
great. Those are very informative for the trained eye
and there is no coincidence that computer magazines are
always littered with those. In the accursed computer
science world, they don't do that a lot (at all) but
there is actually no one stopping you, so just do it
where it helps. One thing with the computer magazines
though, they tend to include very small screenshots,
often you cannot see. I think screenshots should be
half a page or at least one fourth a page to be truly
telling. Often it doesn't help to litter them with
arrows and boxes. It is better to add this in the
description beneath the image, with "down left" (etc.)
instead of arrows and the like.

> I want to ensure the new users that learning Emacs
> worth their time. I also explicitly stated that the
> official Emacs manual is the next place they should
> look for if they want to get the most of Emacs. My
> manual only provides a starting point.

Yeah, I suppose it isn't wrong to think up some logical
order but in reality I don't think it works that way
most of the time. I don't think people start reading
one thing, completes it, then the next thing at a
somewhat higher level, until they master it. They read
some, experiment some, use the help some, Google some,
...

> MELPA is really useful. It helped me to discover many
> useful packages and ease package management. Before
> that, I added packages as submodules in my .emacs.d
> git repo. I think once users know MELPA, even if they
> do not know what they want, they will explore the
> packages, install and play with it - like I did - and
> discover features not available in other editors; for
> example, Helm, Magit, undo-tree...

If they know how to do that... And you have a good
opportunity to teach them what you know.

> As for searching and filtering packages using the
> package manager, I will add it.

Yeah? :) Cool.

-- 
underground experts united

Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS

[Emanuel Berg]

solidius4747@gmail.com writes:

> The current Elisp manual is over 1000 pages long:
> https://www.gnu.org/software/emacs/manual/pdf/elisp.pdf
> . Mine is over 100 pages long in PDF, so I think it's
> safe to call it mini.

Yeah, again, it is not a big issue, you call it what
you want as you wrote it, it is just in my mind "mini"
is something small. Kebnekaise is the highest mountain
in Sweden (2,106 m). Compared to K2 (8,611 m) it isn't
high at all. But I wouldn't call it a mini-mountain
just the same. You know what I'm saying?

PS. If the Danes had a mountain, it would have been
high, too. DS.

/The overground expert

-- 
underground experts united

Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS

[solidius4747]

Vào 04:36:55 UTC+7 Thứ tư, ngày 09 tháng bảy năm 2014, Emanuel Berg đã viết:

> It depends what packages and what users, and what they
> 
> do.

Well I was wrong. The Emacs manual does not cover those packages. Over 600 pages dedicate to Emacs alone.


> I think that is very unlikely for the majority of Emacs
> 
> users. But it is not a bad idea to do - on the
> 
> contrary...

Yes I know since the official manuals are huge. But if they have smaller and simpler books (i.e. how to books), they will usually read cover by cover. And when I say reading the whole book, I mean they actually spend time playing with Emacs, but use the book as the primary learning source most of the time, similar to someone leare a new programming language with a book.

> Screencast = screenshot or dump? If so, that's
> 
> great. Those are very informative for the trained eye
> 
> and there is no coincidence that computer magazines are
> 
> always littered with those. In the accursed computer
> 
> science world, they don't do that a lot (at all) but
> 
> there is actually no one stopping you, so just do it
> 
> where it helps. One thing with the computer magazines
> 
> though, they tend to include very small screenshots,
> 
> often you cannot see. I think screenshots should be
> 
> half a page or at least one fourth a page to be truly
> 
> telling. Often it doesn't help to litter them with
> 
> arrows and boxes. It is better to add this in the
> 
> description beneath the image, with "down left" (etc.)
> 
> instead of arrows and the like.

Screencast is a recording of screen using video or image like GIF. I used GIF for demonstrating what Emacs looks like when it has 3rd party packages and properly configured. For example, I showed users  that Emacs is also capable of context-sensitive completion for C/C++, GUD GDB provides an easy to use and interactive user interface, with colors, Magit...
 
> Yeah, I suppose it isn't wrong to think up some logical
> 
> order but in reality I don't think it works that way
> 
> most of the time. I don't think people start reading
> 
> one thing, completes it, then the next thing at a
> 
> somewhat higher level, until they master it. They read
> 
> some, experiment some, use the help some, Google some,
> 
> ...

Yes, that's why I wrote this tutorial. I want users to collect experience here and there from various sources. That's why I wrote part 3, a collection of useful and popular packages, with useful configurations, to prevent users from rediscover from somewhere. In part 1, I provided exercises in most sections for users to practice. The exercises are common use cases for Emacs features, i.e. why should we save window configurations in register and how to use it effectively.

Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS

[Robert Thorpe]

Emanuel Berg <embe8573@student.uu.se> writes:

> Drew Adams <drew.adams@oracle.com> writes:
...
> Wait - I think I got it, it is probably
> emacs24-common-non-dfsg, right? DFSG is "Debian Free
> Software Guidelines".

That's right.  As I mentioned when we were talking about this last week.

BR,
Robert Thorpe

Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS

[Robert Thorpe]

solidius4747@gmail.com writes:

> Vào 04:36:55 UTC+7 Thứ tư, ngày 09 tháng bảy năm 2014, Emanuel Berg đã viết:
>
>> It depends what packages and what users, and what they
>> 
>> do.
>
> Well I was wrong. The Emacs manual does not cover those packages. Over 600 pages dedicate to Emacs alone.

They aren't covered in the Emacs manual itself, but they are covered in
the *Manual Set* you get with Emacs which consists of ~50 manuals.
Generally, large packages have their own manual and smaller ones are
within the Emacs manual.

BR,
Robert Thorpe

Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS

[Emanuel Berg]

Robert Thorpe <rt@robertthorpeconsulting.com> writes:

> I recommend using a new version of the Emacs manual
> set.  The last version of Emacs 18 was released more
> than 21 years ago.  The current manual describes
> RMAIL in detail.  A separate manual describes GNUS,
> that manual is part of the set.  "Message-mode" is
> the mode for composing email and newsgroup posts that
> comes with GNUS.

So message-mode comes with Gnus? I thought it was older
than Gnus, pre-Internet, pre-everything, perhaps used
with uucp or even for intra-computer "mails". It
doesn't have the "gnus-" prefix that is very
consistently implemented in the Gnus world.

> It's used by GNUS, RMAIL and several other programs.
> It's frequently used, I'm using it now, that's why
> it's included in the manual set.  Of-course reading
> an old manual is still useful, many things haven't
> changed.

Yes.

-- 
underground experts united

Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS

[Emanuel Berg]

solidius4747@gmail.com writes:

> Screencast is a recording of screen using video or
> image like GIF. I used GIF for demonstrating what
> Emacs looks like when it has 3rd party packages and
> properly configured. For example, I showed users that
> Emacs is also capable of context-sensitive completion
> for C/C++, GUD GDB provides an easy to use and
> interactive user interface, with colors, Magit...

Yes, I think this is what I call screenshot or dump.

In this context, let me mention I found a cool way to
do it for Linux VT/tty/console users. In another
terminal, execute the following zsh function (with the
assumption that Emacs is in /dev/tty1) -

dumpemacs () {
    file=$1.png
    sudo fbgrab -c 1 $file
    sudo chown $USER $file
}

I don't know why you have to do it as superuser and
IIRC it didn't help to 'chmod +s' - also, perhaps the
group should be changed as well - but anyway, the
screenshot looks great - here is a screenshot of me
writing this:

http://user.it.uu.se/~embe8573/screencast.png

-- 
underground experts united

Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS

[Bob Proulx]

Emanuel Berg wrote:
> Well, this is actually not the case as was recently
> discussed in another thread. With 'info Emacs' I get
> the Emacs FAQ, not the manual. There was mention of
> some bad blood between the Emacs people and the Debian
> people, who considered the Emacs manual non-free (no idea
> why).

The problem can be summarized as the manual used a non-free license
with the hope that it would encourage a print shop to print and sell
physical copies of the manual.  But the result is one of unintended
consequences.  Instead of encouraging documentation proliferation it
has the opposite of restricting the flow of it.

Please see this for the details of the reasons.

  http://www.debian.org/vote/2006/vote_001

> I have of course access to the non-free repos, but
> there is no emacs-doc like with gcc which documentation
> (the manpage) Debian also has issues with.
> 
> Wait - I think I got it, it is probably
> emacs24-common-non-dfsg, right? DFSG is "Debian Free
> Software Guidelines".

Right.  emacs24-common-non-dfsg is the package.  Simply install it
from the non-free section.

It is sad that two of the most freedom promoting organizations are at
opposite ends of this documentation issue.  Both are principled.  But
with slightly different principles.

> Well, should and should... I'm not going to read it on
> the screen by the computer, that's for sure.

I do read most of the documentation on the screen.  However I don't
find it as good as a printed book.  Therefore I have a *lot* of
printed books!

> Alright, I'll do it. I know you contributed to it so
> I'll just blame you for everything I don't like. But
> actually I think I'll like all or most of it.

I am still chuckling over this comment of yours.  Nicely done.  :-)

Bob

Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS

[Emanuel Berg]

Bob Proulx <bob@proulx.com> writes:

> The problem can be summarized as the manual used a
> non-free license with the hope that it would
> encourage a print shop to print and sell physical
> copies of the manual.

Too bad that didn't work. I have been to tons of public
libraries and they basically mimic the bookstores, only
their books are older and with "annotations". Some of
the books are still good, but most are those "Learn
Brain Surgery in 24 Days, the Fun and Easy Way" - if
you don't get provoked by such obvious nonsense, those
books can be helpful - still, if you have done
something for but one or two years, those are typically
hopelessly "broad" for your purposes. To find the Emacs
manual at such a bookshelf would be a very pleasant
surprise!

> But the result is one of unintended consequences.
> Instead of encouraging documentation proliferation it
> has the opposite of restricting the flow of it.
>
> Please see this for the details of the reasons.
>
>   http://www.debian.org/vote/2006/vote_001

Thanks, but that was so technical. I don't understand
the issue. But I suppose if you want to have a movement
and you put up rules - and some other part of the
movement that basically share your views, if they do
the same - what will eventually happen if those rules
are many (and specific), some of the will clash and
probably that's what happened here.

> I do read most of the documentation on the screen.
> However I don't find it as good as a printed book.
> Therefore I have a *lot* of printed books!

Yes, documentation on-screen is great in the man page
sense, the online Emacs help sense, when you want to
know some part of the interface. If you do Elisp for
some time, and then switch to C, you feel like an idiot
having to Google stuff because the interface isn't
available (though some of the C is in the
manpages). But there is actually nothing that stops
anyone from writing C (interface) documentation that
would work more or less like the Elisp one.

On the other hand, to you read (page up, page down)
on-screen I don't like. The computer should boost
activity, not consumption of material like those pads
that have enslaved the, eh, "kids" those days.

That's why I also like books to be at a different
"pace" than on-screen material. I appreciate when they
tell the back story, some jokes, whatever, not just
what you need to know to solve an immediate problem. If
the pace of the book is right, you get into a pleasant
state yourselves. Books are great. I wish I had a job
where I could turn in lists of books to my boss, and
he'd buy them for me...

>> Alright, I'll do it. I know you contributed to it so
>> I'll just blame you for everything I don't like. But
>> actually I think I'll like all or most of it.
>
> I am still chuckling over this comment of yours.
> Nicely done.  :-)

Ha ha, stupid jokes aside, if there are any newcomers
to the Emacs or FOSS world lurking (I hope so!) who
haven't figured it out, let me say writing
documentation is time-consuming, difficult, it is an
unsung business, and it can be frustrating as there are
morons around talking trash about the software yet
refusing to read the documentation, that would
instantly solve whatever mess they're in. So the people
who do documentation deserves cred and nothing else.

As for the quality, there can be no better source for
information than the official manual of a long-lived
FOSS project. The reason is, the same material has been
worked up by so many people, age in, age out - you know
how commercial books boast "3rd edition" and so on? But
to our manuals, there as been three million revisions -
it is just a massacre by comparison.

-- 
underground experts united

Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS

[Robert Thorpe]

Emanuel Berg <embe8573@student.uu.se> writes:

> Robert Thorpe <rt@robertthorpeconsulting.com> writes:
>
>> I recommend using a new version of the Emacs manual
>> set.  The last version of Emacs 18 was released more
>> than 21 years ago.  The current manual describes
>> RMAIL in detail.  A separate manual describes GNUS,
>> that manual is part of the set.  "Message-mode" is
>> the mode for composing email and newsgroup posts that
>> comes with GNUS.
>
> So message-mode comes with Gnus? I thought it was older
> than Gnus, pre-Internet, pre-everything, perhaps used
> with uucp or even for intra-computer "mails". It
> doesn't have the "gnus-" prefix that is very
> consistently implemented in the Gnus world.

Message mode has nothing to do with pre-internet stuff.

If you use GNUS then compose a message and key C-h m in the compose
buffer.  It'll say "Message mode defined in `message.el'".  Open
message.el and look at it's directory .../lisp/gnus/ .

BR,
Robert Thorpe

Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS

[Emanuel Berg]

Robert Thorpe <rt@robertthorpeconsulting.com> writes:

> Message mode has nothing to do with pre-internet
> stuff.
>
> If you use GNUS then compose a message and key C-h m
> in the compose buffer.  It'll say "Message mode
> defined in message.el'".  Open message.el and look at
> it's directory .../lisp/gnus/ .

Strange, I remember "message" stuff from that old
manual that didn't cover Gnus. But it could have been
that it was mail-mode or something with Rmail and
-message- in it, just not the mode.

Was there a pre-Internet Emacs newsreader?

Facts for fans: I heard there were two Gnus: Gnus, and
then today's Gnus, ding ("Ding is not Gnus") - very
funny (well), but anyway it didn't take so Gnus
remained Gnus.

-- 
underground experts united

Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS

[Javier]

Emanuel Berg <embe8573@student.uu.se> wrote:
> Yes, documentation on-screen is great in the man page
> sense, the online Emacs help sense, when you want to
> know some part of the interface. If you do Elisp for
> some time, and then switch to C, you feel like an idiot
> having to Google stuff because the interface isn't
> available (though some of the C is in the
> manpages). But there is actually nothing that stops
> anyone from writing C (interface) documentation that
> would work more or less like the Elisp one.

It would be an interesting project to convert those documents to
texinfo format.  With Python it is possible to convert the
documentation (sphinx doc generator) of Python and its libraries to
texinfo, and documentation can be gerated automatically for any
python project to texinfo.

Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS

[Emanuel Berg]

Javier <nospam@nospam.com> writes:

>> Yes, documentation on-screen is great in the man
>> page sense, the online Emacs help sense, when you
>> want to know some part of the interface. If you do
>> Elisp for some time, and then switch to C, you feel
>> like an idiot having to Google stuff because the
>> interface isn't available (though some of the C is
>> in the manpages). But there is actually nothing that
>> stops anyone from writing C (interface)
>> documentation that would work more or less like the
>> Elisp one.
>
> It would be an interesting project to convert those
> documents to texinfo format.  With Python it is
> possible to convert the documentation (sphinx doc
> generator) of Python and its libraries to texinfo,
> and documentation can be gerated automatically for
> any python project to texinfo.

Yeah? What documents?

You can get the Emacs manual in texinfo here:

http://www.gnu.org/software/emacs/manual/texi/emacs.texi.tar.gz

I take it that's what you get with the info command,
only not markuped, of course.

In the the on-line help, the docstrings associated to
defuns and variables, they aren't that advanced.

The arguments should be mentioned, in caps - probably
to make them visible - they get the
`help-argument-name' face. In the source, it looks kind
of strange with arguments not the same case in the
docstring as everywhere else. But in help-mode the
parameters in the definition gets uppercased, so there
it's consistent.

All parameters should be mentioned, in the docstring,
and there should be two spaces after a full stop. This
is something I learned from `checkdoc-current-buffer',
check out this example - it should tell you arg2 isn't
mentioned (apart from some other library related stuff
that doesn't apply). But in reality far from everything
is documented and sometimes it is, but not the
parameters...

(defun test-param-doc (arg1 arg2)
  "ARG1 does this.  Also check out `find-file'."
  (interactive)
  nil) ; eval here

(checkdoc-current-buffer t) ; and here

Some hypertext is possible with `this' method - if
there actually is such a function or whatever, that get
hypertexted and the `button' face in help-mode.

-- 
underground experts united

Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS

[Javier]

> Yeah? What documents?
> 
> You can get the Emacs manual in texinfo here:
> http://www.gnu.org/software/emacs/manual/texi/emacs.texi.tar.gz

I mean having in info format documents like this

http://en.cppreference.com/w/Main_Page

It's just an example, I just mean that there isn't that much
documentation available in info format.  Those documents could
be converted to info, but html->info conversion is too problematic.

Of course emacs/elisp are already documented in info format (as pretty
much everything that is done by the FSF: bash, gcc, coreutils...)





Emanuel Berg <embe8573@student.uu.se> wrote:
> Javier <nospam@nospam.com> writes:
> 
>>> Yes, documentation on-screen is great in the man
>>> page sense, the online Emacs help sense, when you
>>> want to know some part of the interface. If you do
>>> Elisp for some time, and then switch to C, you feel
>>> like an idiot having to Google stuff because the
>>> interface isn't available (though some of the C is
>>> in the manpages). But there is actually nothing that
>>> stops anyone from writing C (interface)
>>> documentation that would work more or less like the
>>> Elisp one.
>>
>> It would be an interesting project to convert those
>> documents to texinfo format.  With Python it is
>> possible to convert the documentation (sphinx doc
>> generator) of Python and its libraries to texinfo,
>> and documentation can be gerated automatically for
>> any python project to texinfo.
> 
> Yeah? What documents?
> 
> You can get the Emacs manual in texinfo here:
> 
> http://www.gnu.org/software/emacs/manual/texi/emacs.texi.tar.gz
> 
> I take it that's what you get with the info command,
> only not markuped, of course.
> 
> In the the on-line help, the docstrings associated to
> defuns and variables, they aren't that advanced.
> 
> The arguments should be mentioned, in caps - probably
> to make them visible - they get the
> `help-argument-name' face. In the source, it looks kind
> of strange with arguments not the same case in the
> docstring as everywhere else. But in help-mode the
> parameters in the definition gets uppercased, so there
> it's consistent.
> 
> All parameters should be mentioned, in the docstring,
> and there should be two spaces after a full stop. This
> is something I learned from `checkdoc-current-buffer',
> check out this example - it should tell you arg2 isn't
> mentioned (apart from some other library related stuff
> that doesn't apply). But in reality far from everything
> is documented and sometimes it is, but not the
> parameters...
> 
> (defun test-param-doc (arg1 arg2)
>  "ARG1 does this.  Also check out `find-file'."
>  (interactive)
>  nil) ; eval here
> 
> (checkdoc-current-buffer t) ; and here
> 
> Some hypertext is possible with `this' method - if
> there actually is such a function or whatever, that get
> hypertexted and the `button' face in help-mode.
> 

Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS

[Robert Thorpe]

Javier <nospam@nospam.com> writes:
...
> It would be an interesting project to convert those documents to
> texinfo format.  With Python it is possible to convert the
> documentation (sphinx doc generator) of Python and its libraries to
> texinfo, and documentation can be gerated automatically for any
> python project to texinfo.

If you're using GNU C or C++ library functions and you have the manuals
installed then C-h S will do the trick.  I think the same is true for
Fortran and Ada too.  But, it would be very useful if more languages and
libraries were supported.  Automatic generation of info from other
documentation formats would be very useful.  It should be possible to
add code to something like pandoc to output info files.

BR,
Robert Thorpe

Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS

[Emanuel Berg]

Javier <nospam@nospam.com> writes:

> I mean having in info format documents like this
>
> http://en.cppreference.com/w/Main_Page
>
> It's just an example, I just mean that there isn't
> that much documentation available in info format.
> Those documents could be converted to info, but
> html->info conversion is too problematic.

Aha, yes, that would be very helpful. I take it neither
C or C++ changes a whole lot these days, and when they
do (I'm sure) they are super-conscious not to break all
the code in the wild (yes, a bit of a paradox: the new
standard's main concern - be compatible with the old
standard!) - so probably it is not worth the effort to
translate on the fly, just something to have as a bunch
of files on your computer would be sufficient.

-- 
underground experts united

Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS

[Jude DaShiell]

I wasn't even aware of ses until earlier today and found that as a 
built-in looking through m-x list-packages.   Fortunately emacs has that 
available since oleo won't build on this amd K8 athelon I have.  A 
built-in that's coming in the next version of emacs will be eww and for 
those of us on command line level of linux (no g.u.i.) by preference, 
masquerrade mode from what I've read over on the emacspeak list may get 
us better web content from several sites that restrict content just 
because a text browser is in use.  One real useful tool I found with 
emacs that's also built-in is orgmode.  That has spreadsheet capacity, 
but implementation in terms of content of fmtline's to my mind is 
abstruse.

On Tue, 8 Jul 2014, solidius4747@gmail.com wrote:
The forms built-in will probably be very useful but this is probably at an 
intermediate level.


> V?o 22:09:49 UTC+7 Th? ba, ng?y 08 th?ng b?y n?m 2014, Emanuel Berg ?? 
> vi?t:
> 
> > I only have a very old version of the manual - Emacs
> > 
> > 18, I think - but I read that twice. It wasn't
> > 
> > difficult to understand but I noticed there were gaps
> > 
> > in it when I compared how I used Emacs. There was no
> > 
> > mention of Gnus and I don't remember if RMAIL was
> > 
> > mentioned, for example, but there were material on the
> > 
> > message-mode, perhaps to be used between Unix boxes on
> > 
> > an intranet (?) - of course, if those things weren't
> > 
> > around then, they couldn't have been included - but as
> > 
> > for being a reference, I don't remember it being too
> > 
> > difficult to digest, on the contrary I remember it
> > 
> > being pleasant to read (big sheets, wide margins, clear
> > 
> > and normal language, and so on).
> > 
> > 
> > 
> > > It also does not mention about popular 3rd party
> > 
> > > packages, and popular package archives like MELPA.
> > 
> > 
> > 
> > It is not only the manual who is quiet about MELPA. I
> > 
> > didn't know of it until recently, when I learned about
> > 
> > it - ironically - on gnu.emacs.sources.
> > 
> > 
> > 
> > In this book
> > 
> > 
> > 
> > @Book{cameron,
> > 
> > author = {Cameron and Elliot and Loy and Raymond and Rosenblatt},
> > 
> > title = {Learning GNU Emacs},
> > 
> > publisher = {O'Reilly},
> > 
> > year = 2004,
> > 
> > ISBN = {0-596-00648-9},
> > 
> > edition = {3rd edition}}
> > 
> > 
> > 
> > there is a very short chapter on packages and online,
> > 
> > unofficial repositories, but it doesn't say how to use
> > 
> > it and it doesn't mention MELPA or even ELPA.
> > 
> > 
> > 
> > So, all the more reason (in my mind) for you to mention
> > 
> > it in more detail, or at least to provide a reference
> > 
> > to "how to broadcast" as that is as vital a part as is
> > 
> > downloading/installing. It just seems clear to me.
> >
> 
> The recent GNU Emacs Manual is more than 600 pages long: http://www.gnu.org/software/emacs/manual/pdf/emacs.pdf 
> 
> It includes packages like Semantic, EDE, Calc, GUD... (I am using these packages myself). That's a lot of features. Certainly, users won't need to learn of those to be productive. It's likely that users usually read cover from cover, so they will be distracted by unnecessary stuffs not needed at the moment. The exported PDF of part 1 is only 43 pages long and part 3 is 83 pages long. Certainly mini compared to the actual manual. I also added screencasts to demonstrate what Emacs is capable of. I want to ensure the new users that learning Emacs worth their time. I also explicitly stated that the official Emacs manual is the next place they should look for if they want to get the most of Emacs. My manual only provides a starting point.
>  
> > Right, that's always the case. However, just knowing
> > 
> > about MELPA won't have people discovering what they
> > 
> > want instantly. Of course, first they must know what
> > 
> > they want, which always takes time, and is natural and
> > 
> > nothing that we should (could) influence (to any extent
> > 
> > anyway). But the second part is: finding what they
> > 
> > want. So how do you search MELPA? And how do you know
> > 
> > what to search for, if you terminology is different
> > 
> > from the person who wrote the package? Great things to
> > 
> > discuss here, as well as to include...
> 
> MELPA is really useful. It helped me to discover many useful packages and ease package management. Before that, I added packages as submodules in my .emacs.d git repo. I think once users know MELPA, even if they do not know what they want, they will explore the packages, install and play with it - like I did - and discover features not available in other editors; for example, Helm, Magit, undo-tree...
> 
> 
> > We should of course never tell anyone to read the
> > 
> > manual, and especially not the whole Elisp manual :) We
> > 
> > can post URLs. Best way is for course to do that, but
> > 
> > also explain how it relates to the particular problem,
> > 
> > and even support example Elisp. But sometimes there
> > 
> > isn't the energy, time or will to do that, and then a
> > 
> > HTTP manual in small chapters is great so you at least
> > 
> > can give the URL.
> 
> I did provide it in part 3, not to the manual, but encourage new users to directly use Emacs for looking up functions and stuffs, as you can see in the section "Just enough Emacs Lisp" for each listed function. But probably I will provide a link to the function in the official Elisp manual, so they can compare and contrast.
> 
> 
> > Well, I disagree here. First, the beginners will use
> > 
> > your tutorial, yes, but that's not it. They will also
> > 
> > write Elisp and configure Emacs and use Emacs and the
> > 
> > online help. They are likely to also come across the
> > 
> > Emacs manual, the Elisp manual, perhaps even the Gnus
> > 
> > manual, and of course the EmacsWiki if they happen to
> > 
> > Google problems (very likely). You yourself said MELPA
> > 
> > didn't get enough attention (and I agree), so if the
> > 
> > readers come across it in your book, at some point they
> > 
> > will ask - "how do I use MELPA in a more advanced way:
> > 
> > searching, filtering, submitting?" - at that point, if
> > 
> > the readers first came across it in your book, they
> > 
> > will instinctively reach for that book. If they read
> > 
> > about it somewhere else, they'll go for that source, of
> > 
> > course. But we (you) cannot influence that, can be?
> > 
> > Better make your own source as complete as possible.
> 
> Yes, I know. That's the route I worked through when I was new to Emacs. But I still want new users to be productive with Emacs as possible, with minimal Elisp. To be honest, I'm not an expert with Emacs Lisp; I'm still learning (I actually want to be proficient with Common Lisp first) and I only have limited experience with Racket from some Coursera courses ("Introduction to Systematic Design" - which uses the book How to Design Program and "Programming Languages" that I wrote a small evaluator for a made up language).
> 
> I always encourage users to seek help from the official manual and especially, within Emacs itself, in all of my articles. In part 3, I only want to introduce enough Emacs Lisp that new users can feel comfortable with using MELPA to add package for extending Emacs, rather than taking the hard route, that is actually learn and write Elisp. I think, after new users use various Emacs packages from the community comfortable, they will see the power of Emacs and have an interest in learning Elisp, just like I did. That's why I listed many popular and useful packages, one by one in this part, along with how to set up the packages properly to start using it. I believe, by repeating adding packages and Elisp code configuration, new users will get comfortable with Elisp and extending Emacs in gen
 eral. My goal is to have an interested-in-Emacs reader to get what I demonstrated in part 1 in about a month or less.
> 
> As for searching and filtering packages using the package manager, I will add it.
> 
> 

jude <jdashiel@shellworld.net>