Some ideas with Emacs

Some ideas with Emacs

[Anonymous]

[-- Attachment #1: Type: text/plain, Size: 1084 bytes --]

Hi, I'm a user and a fanatical fans for Emacs. I'd like to share a few ideas for about Emacs Lisp.
Emacs Lisp is powerful, it's undeniable. But when I studied Emacs Lisp, I found that there were too few examples of function use in the tutorial. Also when using Emacs Lisp for Emacs plugin development and configuration, Sometimes you write your own plugins will affect the configuration you write, so I'd like to make a few ideas for Emacs Lisp:
First, suggest to add more examples of functions in the tutorial, most for Emacs Lisp Reference Manual, which can lower the learning threshold.

Second, in developing the Emacs plugins, create a virtual environment, like Python virtualenv, so that we can test the plugin in the virtual environment so that we do not need to affect the configuration outside the virtual environment. That's can implement plugin development environment and configuration isolation.

Although my suggestion may be a little trivial and even useless. But if my suggestions can help beginners like me go further, I think it's worth it.

[-- Attachment #2: Type: text/html, Size: 1146 bytes --]

Re: Some ideas with Emacs

[Marcin Borkowski]

On 2019-11-29, at 10:05, Anonymous <c4droid@foxmail.com> wrote:

> Hi, I'm a user and a fanatical fans for Emacs. I'd like to share a few ideas for about Emacs Lisp.
> Emacs Lisp is powerful, it's undeniable.&nbsp;But when I studied Emacs Lisp, I found that there were too few examples of function use in the tutorial.&nbsp;Also when using Emacs Lisp for Emacs plugin development and configuration,&nbsp;Sometimes you write your own plugins will affect the configuration you write, so I'd like to make a few ideas for Emacs Lisp:
> First, suggest to add more examples of functions in the tutorial, most for Emacs Lisp Reference Manual, which can lower the learning threshold.

I had a plan to write an intermediate book on Elisp, but Real Life™
intervened.  I still have the stuff I managed to write, and if I live
long enough, I'm going to get back to this project (the current plan is
late 2020 - I'm finishing work on another book now, which is long
overdue, and I cannot postpone it more because it is a joint work with
two other people).  Would you be interested?  What would you like to see
in such a book?  (The idea was - and is - to start approximately where
Robert Chassell's "Elisp Intro" ends.)

> Second, in developing the Emacs plugins, create a virtual environment, like Python virtualenv, so that we can test the plugin in the virtual environment so that we do not need to affect the configuration outside the virtual environment. That's can implement plugin development environment and configuration isolation.
>
> Although my suggestion may be a little trivial and even useless.&nbsp;But if my suggestions can help beginners like me go further, I think it's worth it.

AFAIK, this is _far_ from trivial.  However, you can always start
a fresh Emacs instance with -Q.  For more advanced configs, you may
start a fresh Emacs instance with the config directory in /tmp or
whatever.  (Shameless plug: I blogged about it a few weeks ago, see
http://mbork.pl/2019-11-04_Starting_Emacs_with_custom_configuration_directory.)

Now that I think of it, we could even have an Emacs command to start
a fresh Emacs instance with a given file already loaded.  WDYT?

Hth,

--
Marcin Borkowski
http://mbork.pl

Re: Some ideas with Emacs

[=?gb18030?B?QW5vbnltb3Vz?=]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset="gb18030", Size: 3323 bytes --]

I'm interested your book, I'm waiting for a professional book talk about Emacs Lisp and Emacs plugins development.
For environment isolation, maybe put plugin source at /tmp and call emacs with -Q option is best practices. In my mind, I think the plugin develop workflow is:
Real environment:
Write, Modify code
Virtual environment:
Run, test, debug plugin, when debug, real environment using emacs lisp debugger attach virtual environment for debug.

---Original---
From: "Marcin Borkowski"<mbork@mbork.pl&gt;
Date: Fri, Nov 29, 2019 19:16 PM
To: "Anonymous"<c4droid@foxmail.com&gt;;
Cc: "emacs-devel"<emacs-devel@gnu.org&gt;;
Subject: Re: Some ideas with Emacs



On 2019-11-29, at 10:05, Anonymous <c4droid@foxmail.com&gt; wrote:

&gt; Hi, I'm a user and a fanatical fans for Emacs. I'd like to share a few ideas for about Emacs Lisp.
&gt; Emacs Lisp is powerful, it's undeniable.&amp;nbsp;But when I studied Emacs Lisp, I found that there were too few examples of function use in the tutorial.&amp;nbsp;Also when using Emacs Lisp for Emacs plugin development and configuration,&amp;nbsp;Sometimes you write your own plugins will affect the configuration you write, so I'd like to make a few ideas for Emacs Lisp:
&gt; First, suggest to add more examples of functions in the tutorial, most for Emacs Lisp Reference Manual, which can lower the learning threshold.

I had a plan to write an intermediate book on Elisp, but Real Life6¾4
intervened.&nbsp; I still have the stuff I managed to write, and if I live
long enough, I'm going to get back to this project (the current plan is
late 2020 - I'm finishing work on another book now, which is long
overdue, and I cannot postpone it more because it is a joint work with
two other people).&nbsp; Would you be interested?&nbsp; What would you like to see
in such a book?&nbsp; (The idea was - and is - to start approximately where
Robert Chassell's "Elisp Intro" ends.)

&gt; Second, in developing the Emacs plugins, create a virtual environment, like Python virtualenv, so that we can test the plugin in the virtual environment so that we do not need to affect the configuration outside the virtual environment. That's can implement plugin development environment and configuration isolation.
&gt;
&gt; Although my suggestion may be a little trivial and even useless.&amp;nbsp;But if my suggestions can help beginners like me go further, I think it's worth it.

AFAIK, this is _far_ from trivial.&nbsp; However, you can always start
a fresh Emacs instance with -Q.&nbsp; For more advanced configs, you may
start a fresh Emacs instance with the config directory in /tmp or
whatever.&nbsp; (Shameless plug: I blogged about it a few weeks ago, see
http://mbork.pl/2019-11-04_Starting_Emacs_with_custom_configuration_directory.)

Now that I think of it, we could even have an Emacs command to start
a fresh Emacs instance with a given file already loaded.&nbsp; WDYT?

Hth,

--
Marcin Borkowski
http://mbork.pl
i

[-- Attachment #2: Type: text/html, Size: 3705 bytes --]

Re: Some ideas with Emacs

[Emanuel Berg via Emacs development discussions.]

Anonymous wrote:

> I'm interested your book, I'm waiting for a professional book talk about Emacs Lisp and Emacs plugins development.
> For environment isolation, maybe put plugin source at /tmp and call emacs with -Q option is best practices. In my mind, I think the plugin develop workflow is:
> Real environment:
> Write, Modify code
> Virtual environment:
> Run, test, debug plugin, when debug, real environment using emacs lisp debugger attach virtual environment for debug.

OT: What format it this? What's  ?
Non-breaking space?

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Some ideas with Emacs

[Emanuel Berg via Emacs development discussions.]

Marcin Borkowski wrote:

> I had a plan to write an intermediate book on
> Elisp [...]

Do it! :)

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Some ideas with Emacs

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

The Intro to Emacs Lisp needs updating.  Emacs Lisp has changed since
the late Bob Chassell worked on it.

Would you like to update it?  That would be far easier than writing a
new manual from zero, and would be good practice for that.

-- 
Dr Richard Stallman
Founder, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Some ideas with Emacs

[Marcin Borkowski]

On 2019-12-01, at 06:57, Richard Stallman <rms@gnu.org> wrote:

> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
> The Intro to Emacs Lisp needs updating.  Emacs Lisp has changed since
> the late Bob Chassell worked on it.
>
> Would you like to update it?  That would be far easier than writing a
> new manual from zero, and would be good practice for that.

Easier - probably yes.  But Bob Chassell's book is distributed under
GFDL, which may be a good choice for documentation, but is an extremely
bad choice for a book.  Contributing to a GFDL book is pointless IMO.
(I might release my book on some CC license one day, but then it would
have to be an ND variant.)

Best,

-- 
Marcin Borkowski
http://mbork.pl

Re: Some ideas with Emacs

[Marcin Borkowski]

On 2019-12-01, at 11:56, Marcin Borkowski <mbork@mbork.pl> wrote:

> On 2019-12-01, at 06:57, Richard Stallman <rms@gnu.org> wrote:
>
>> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
>> [[[ whether defending the US Constitution against all enemies,     ]]]
>> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>>
>> The Intro to Emacs Lisp needs updating.  Emacs Lisp has changed since
>> the late Bob Chassell worked on it.
>>
>> Would you like to update it?  That would be far easier than writing a
>> new manual from zero, and would be good practice for that.
>
> Easier - probably yes.  But Bob Chassell's book is distributed under
> GFDL, which may be a good choice for documentation, but is an extremely
> bad choice for a book.  Contributing to a GFDL book is pointless IMO.
> (I might release my book on some CC license one day, but then it would
> have to be an ND variant.)

Correction: I read a bit more about GFDL, and I withdraw my opinion that
it is an "extremely bad choice" for a book: I think now that it is not
"extremely bad", but just "bad" or "very bad".  Reason: GFDL has the
"invariant sections" clause.  I guess the author probably could
technically call the whole book an "invariant section" - but then there
is no point to use GFDL anyway, no?

To be more positive, a reasonable license for "free" (as in FSF) book
would allow no modifications except for e.g. footnotes clearly marked as
not written by the original author.  AFAIK, GFDL's "History" section is
way worse than that (since it is a lot more inconvenient for the
reader).

Best,

--
Marcin Borkowski
http://mbork.pl

Re: Some ideas with Emacs

[VanL]

Marcin Borkowski <mbork@mbork.pl> writes:

> To be more positive, a reasonable license for "free" (as in FSF) book
> would allow no modifications except for e.g. footnotes clearly marked as
> not written by the original author.  AFAIK, GFDL's "History" section is
> way worse than that (since it is a lot more inconvenient for the
> reader).

As an example, I'm reading a work under the (CC BY-NC-ND 4.0) in which
contributors have concentrated on their own chapter in a collection of
53.

: AFTERLIVES 
: OF CHINESE 
: COMMUNISM
:
: POLITICAL CONCEPTS 
: FROM MAO TO XI
:
: Edited by Christian Sorace, 
: Ivan Franceschini, 
: and Nicholas Loubere
: 
: This title is published under a 
: Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 
: International (CC BY-NC-ND 4.0).

-- 
LoL,
  əə0@ 一 二 三 言 語 𝔖
  'VLIW architecture?'
  G4 White 78 Black 79

Re: Some ideas with Emacs

[Marcin Borkowski]

On 2019-12-01, at 14:40, VanL <van@scratch.space> wrote:

> Marcin Borkowski <mbork@mbork.pl> writes:
>
>> To be more positive, a reasonable license for "free" (as in FSF) book
>> would allow no modifications except for e.g. footnotes clearly marked as
>> not written by the original author.  AFAIK, GFDL's "History" section is
>> way worse than that (since it is a lot more inconvenient for the
>> reader).
>
> As an example, I'm reading a work under the (CC BY-NC-ND 4.0) in which

Example of what?

> contributors have concentrated on their own chapter in a collection of
> 53.
>
> : AFTERLIVES 
> : OF CHINESE 
> : COMMUNISM
> :
> : POLITICAL CONCEPTS 
> : FROM MAO TO XI
> :
> : Edited by Christian Sorace, 
> : Ivan Franceschini, 
> : and Nicholas Loubere
> : 
> : This title is published under a 
> : Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 
> : International (CC BY-NC-ND 4.0).


-- 
Marcin Borkowski
http://mbork.pl

Re: Some ideas with Emacs

[VanL]

>>> To be more positive, a reasonable license for "free" (as in FSF) book
>>> would allow no modifications except for e.g. footnotes..
>>
>> As an example, I'm reading a work under the (CC BY-NC-ND 4.0) in which
>
> Example of what?
>

CC BY-NC-ND 4.0 is an example of a reasonable license for some.

-- 
IANAL,
  School of Secret Art
  əə0@ 一 二 三 言 語 𝔖
  'VLIW architecture?'
  G4 White 78 Black 79

Re: Some ideas with Emacs

[Marcin Borkowski]

On 2019-12-02, at 05:52, VanL <van@scratch.space> wrote:

>>>> To be more positive, a reasonable license for "free" (as in FSF) book
>>>> would allow no modifications except for e.g. footnotes..
>>>
>>> As an example, I'm reading a work under the (CC BY-NC-ND 4.0) in which
>>
>> Example of what?
>>
>
> CC BY-NC-ND 4.0 is an example of a reasonable license for some.

OK, I didn't understand you.  Yes, it is a reasonable variant.

My reason is that I don't believe in books written as a collaborative
effort.  Such _manuals_ are acceptable, but books not.  A book should be
written by one person or very few people sharing exactly the same
vision.  Otherwise it is going to feel like a patchwork.

An encyclopedia that feels like a patchwork is fine.  A manual that
feels like a patchwork is ok.  A book is not.

IOW, a book - like any other artistic endeavor - has a "stamp" of the
author's personality.  In case of a book of two or three people, this is
blurred, but still possible to do right (though _very_ difficult, and
I'm speaking from personal experience here).  In case of GFDL, you migth
get a mess.

BTW, how many people actually contrinuted to Chassell's Elisp Intro in
a major way?  I'm really curious.

Best,

--
Marcin Borkowski
http://mbork.pl

Re: Some ideas with Emacs

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > BTW, how many people actually contrinuted to Chassell's Elisp Intro in
  > a major way?  I'm really curious.

I don't know -- but it needs updating, so I hope there will soon
be another major contributor.

-- 
Dr Richard Stallman
Founder, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Some ideas with Emacs

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Tue, 03 Dec 2019 00:01:54 -0500
> Cc: van@scratch.space, emacs-devel@gnu.org
> 
>   > BTW, how many people actually contrinuted to Chassell's Elisp Intro in
>   > a major way?  I'm really curious.
> 
> I don't know

The Elisp Intro manual has a "Thank You" section which answers that
question.

Re: Some ideas with Emacs

[Emanuel Berg via Emacs development discussions.]

Eli Zaretskii wrote:

>>> BTW, how many people actually contrinuted
>>> to Chassell's Elisp Intro in a major way?
>>> I'm really curious.
>>
>> I don't know
>
> The Elisp Intro manual has a "Thank You"
> section which answers that question.

Does it also say somewhere how many people use
Emacs every day?

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Some ideas with Emacs

[Eli Zaretskii]

> Date: Tue, 03 Dec 2019 17:21:25 +0100
> From: Emanuel Berg via "Emacs development discussions." <emacs-devel@gnu.org>
> 
> > The Elisp Intro manual has a "Thank You"
> > section which answers that question.
> 
> Does it also say somewhere how many people use
> Emacs every day?

I don't know, but you can look there for yourself and see if it does.

Re: Some ideas with Emacs

[Stefan Monnier]

> Does it also say somewhere how many people use Emacs every day?

Try `M-x how-many RET`


        Stefan

Re: Some ideas with Emacs

[Emanuel Berg via Emacs development discussions.]

Stefan Monnier wrote:

>> Does it also say somewhere how many people
>> use Emacs every day?
>
> Try `M-x how-many RET`

:)

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Some ideas with Emacs

[Marcin Borkowski]

On 2019-12-03, at 16:45, Eli Zaretskii <eliz@gnu.org> wrote:

>> From: Richard Stallman <rms@gnu.org>
>> Date: Tue, 03 Dec 2019 00:01:54 -0500
>> Cc: van@scratch.space, emacs-devel@gnu.org
>> 
>>   > BTW, how many people actually contrinuted to Chassell's Elisp Intro in
>>   > a major way?  I'm really curious.
>> 
>> I don't know
>
> The Elisp Intro manual has a "Thank You" section which answers that
> question.

Not really, I guess - it doesn't say anything about who contributed how
much (and what exactly).  For that, I'd probably have to dive into Git
(not today).

Best,

-- 
Marcin Borkowski
http://mbork.pl

Re: Some ideas with Emacs

[Eli Zaretskii]

> From: Marcin Borkowski <mbork@mbork.pl>
> Cc: rms@gnu.org, van@scratch.space, emacs-devel@gnu.org
> Date: Tue, 03 Dec 2019 20:32:11 +0100
> 
> > The Elisp Intro manual has a "Thank You" section which answers that
> > question.
> 
> Not really, I guess - it doesn't say anything about who contributed how
> much (and what exactly).

That's all the information Bob left us, sorry.  You could try asking
those people, though.

> For that, I'd probably have to dive into Git

No, Git will not tell you anything useful about that.

Re: Some ideas with Emacs

[Marcin Borkowski]

On 2019-12-03, at 20:37, Eli Zaretskii <eliz@gnu.org> wrote:

>> From: Marcin Borkowski <mbork@mbork.pl>
>> Cc: rms@gnu.org, van@scratch.space, emacs-devel@gnu.org
>> Date: Tue, 03 Dec 2019 20:32:11 +0100
>>
>> > The Elisp Intro manual has a "Thank You" section which answers that
>> > question.
>>
>> Not really, I guess - it doesn't say anything about who contributed how
>> much (and what exactly).
>
> That's all the information Bob left us, sorry.  You could try asking
> those people, though.
>
>> For that, I'd probably have to dive into Git
>
> No, Git will not tell you anything useful about that.

Why is that so?  In fact, I tried blaming (and some other tricks), but
indeed, the oldest history of Elisp Intro seems to be lost.  It's
a pity, I guess.

Best,

--
Marcin Borkowski
http://mbork.pl

Re: Some ideas with Emacs

[Eli Zaretskii]

> From: Marcin Borkowski <mbork@mbork.pl>
> Date: Wed, 04 Dec 2019 00:08:51 +0100
> Cc: van@scratch.space, rms@gnu.org, emacs-devel@gnu.org
> 
> > No, Git will not tell you anything useful about that.
> 
> Why is that so?

Because by the time this manual was added to the Emacs repository, it
was already completely written, and all the changes you will see in
Git are very minor, mostly fixing of typos and things that have
changed in Emacs since the manual was first written.

Re: Some ideas with Emacs

[Marcin Borkowski]

On 2019-12-04, at 04:42, Eli Zaretskii <eliz@gnu.org> wrote:

>> From: Marcin Borkowski <mbork@mbork.pl>
>> Date: Wed, 04 Dec 2019 00:08:51 +0100
>> Cc: van@scratch.space, rms@gnu.org, emacs-devel@gnu.org
>> 
>> > No, Git will not tell you anything useful about that.
>> 
>> Why is that so?
>
> Because by the time this manual was added to the Emacs repository, it
> was already completely written, and all the changes you will see in
> Git are very minor, mostly fixing of typos and things that have
> changed in Emacs since the manual was first written.

That's what I suspected.  It's a pity, but I guess we'll have to live
with it.

Best,

-- 
Marcin Borkowski
http://mbork.pl

Re: Some ideas with Emacs

[VanL]

>>   > BTW, how many people actually
>>   > contrinuted to Chassell's Elisp Intro
>>   > in a major way?  I'm really curious.
>> 
>> I don't know

The printed revised 2nd edition, January 2004.
Any idea what percentage of that was by Bob?
Is there a 100% Bob's copy?

-- 
LoL,
  School of Secret Art
  əə0@ 一 二 三 言 語 𝔖

Re: Some ideas with Emacs

[Marcin Borkowski]

On 2019-12-03, at 06:01, Richard Stallman <rms@gnu.org> wrote:

> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
>   > BTW, how many people actually contrinuted to Chassell's Elisp Intro in
>   > a major way?  I'm really curious.
>
> I don't know -- but it needs updating, so I hope there will soon
> be another major contributor.

What exactly needs updating there?

-- 
Marcin Borkowski
http://mbork.pl

Re: Some ideas with Emacs

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > I don't know -- but it needs updating, so I hope there will soon
  > > be another major contributor.

  > What exactly needs updating there?

One thing is that Emacs Lisp now supports lexical scoping.
When Chassell wrote the intro, we had only dynamic scoping.

However, there could well be other things that have changed.
For instance, the newer control constructs such as
when, until, dolist, may not be in the intro, and perhaps
should be.

(I have never read the intro -- when it was written, I already
knew Emacs Lisp ;-).

-- 
Dr Richard Stallman
Founder, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Some ideas with Emacs

[VanL]

>   > What exactly needs updating there?
>
> One thing is that Emacs Lisp now supports lexical scoping.
> When Chassell wrote the intro, we had only dynamic scoping.
>
> However, there could well be other things that have changed.
> For instance, the newer control constructs such as
> when, until, dolist, may not be in the intro, and perhaps
> should be.
>
> (I have never read the intro -- when it was written, I already
> knew Emacs Lisp ;-).

Is the better medium for consumption
12 video streams of 3-minute
episodes narrated by an attractive
nerdy personality like in 'The Schmo and The Pro' channel?

Is there a listing for hardware to
host the fabled GNU system for Emacs?  
As an example, I don't know
if this one qualifies.  [1]



Footnotes: 
[1]  https://www.solid-run.com/nxp-lx2160a-family/honeycomb-workstation/

-- 
LoL,
  School of Secret Art
  əə0@ 一 二 三 言 語 𝔖

Re: Some ideas with Emacs

[Marcin Borkowski]

On 2019-12-06, at 07:51, VanL <van@scratch.space> wrote:

>>   > What exactly needs updating there?
>>
>> One thing is that Emacs Lisp now supports lexical scoping.
>> When Chassell wrote the intro, we had only dynamic scoping.
>>
>> However, there could well be other things that have changed.
>> For instance, the newer control constructs such as
>> when, until, dolist, may not be in the intro, and perhaps
>> should be.
>>
>> (I have never read the intro -- when it was written, I already
>> knew Emacs Lisp ;-).
>
> Is the better medium for consumption
> 12 video streams of 3-minute
> episodes narrated by an attractive
> nerdy personality like in 'The Schmo and The Pro' channel?

Depends.  I very much prefer learning from written text than videos.

-- 
Marcin Borkowski
http://mbork.pl

Re: Some ideas with Emacs

[VanL]

Marcin Borkowski <mbork@mbork.pl> writes:

>>> (I have never read the intro -- when it was written, I already
>>> knew Emacs Lisp ;-).
>>
>> Is the better medium for consumption
>> 12 video streams of 3-minute
>> episodes narrated by an attractive
>> nerdy personality like in 'The Schmo and The Pro' channel?
>
> Depends.  I very much prefer learning from written text than videos.

The video stream medium carries more bits of information per second.  I
prefer reading text on serious matters; not manual nor memoir, but a
series of monographs by specialists.  The elisp intro is expected to be
mechanical automaticity like a Boeing 737-NG to Boeing737-MAX8
self-paced learning on the Apple iPad for an hour.

-- 
VanL,
  School of Secret Art
  əə0@ 一 二 三 言 語 𝔖

Re: Some ideas with Emacs

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

CC licenses with either NC or ND are nonfree licenses.
In particular, ND makes the entire manual into an invariant section.

Invariant sections under the GFDL are ok because they are limited
to political points which are outside the practical topic of the manual.
CC-ND would make the technical substance of the manual invariant,
so we would have to reject it.

This, We could not distribute, or even refer to, a manual carrying
either of those licenses.  Please don't use a GNU mailing list to ask
people to work on them.

-- 
Dr Richard Stallman
Founder, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Some ideas with Emacs

[Marcin Borkowski]

On 2019-12-02, at 06:41, Richard Stallman <rms@gnu.org> wrote:

> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
> CC licenses with either NC or ND are nonfree licenses.
> In particular, ND makes the entire manual into an invariant section.

That is precisely the point of using it.

Also, _please_ do not use the word "manual" here.  A book I'm thinking
of would _not_ be a manual - as I mentioned in my previous message, this
distinction is crucial here.  (I explain one difference below.)

> Invariant sections under the GFDL are ok because they are limited
> to political points which are outside the practical topic of the manual.
> CC-ND would make the technical substance of the manual invariant,
> so we would have to reject it.

Could you define "political points which are outside the practical topic
of the manual"?

Here is what I think (not having a definition, only a vague intuition).
A _manual_ should be e.g. comprehensive (i.e., cover the whole of its
subject).  A _book_ on a subject does not have to be so.  The topic
selection itself might be "political" (depending on the exact
understanding of the word).  This seems to confirm my intuition that
GFDL is a bad choice for books (even though it may be a good choice for
manuals).

> This, We could not distribute, or even refer to, a manual carrying

I would not expect the FSF to distribute such a book.  However, "not
referring" comes to me as a surprise.  The FSF does refer to e.g. MS
Windows (in the Emacs manual, of all places).  How is a CC-NC/CC-ND book
(not "manual"!!!) worse than that?

> either of those licenses.  Please don't use a GNU mailing list to ask
> people to work on them.

Frankly, I do not understand that.  I think I roughly understand why you
consider limiting the freedom of modification of software or manuals
a bad thing.  But again - this is not a manual we are talking about!!!

In your essay on ebooks, you write: "For textbooks and most reference
works, publication of modified versions should be allowed as well, since
that encourages society to improve them".  I think this is not entirely
true.  I agree that out-of-date textbooks are a danger, but I wouldn't
really want to allow non-authors to modify some author's book (even if
they are "professional writers", whatever that means).  I agree that
this is a very shady area - after all, disallowing reuse would put
a stop to much of artistic creativity - but I would at least expect
a modified version to be (a) easily distinguishable from the original
and (b) prepared in such a way that the differeneces between the
original and the modified version are visible without specialized tools
(like diff).  From a cursory examination, GFDL secures (a), but not
necessarily (b).

And by the way, in the same essay you say: "It did its job well—back
then".  As a theoretical exercise, would you have a problem with
a paper-only (so, no electronic version) book on GNU Emacs, distributed
under CC-ND-something, so that people are free to photocopy it?

As an even more theoretical exercise, assume I wanted to write a book
(again, in the traditional sense - paper only, and either CC-ND or even
non-CC altogether - or maybe even electronic version, but with copying
prohibited just like with paper books, so with all the law exemptions
and no DRMs - by the way, this is roughly how ebooks work in my country)
called "Memoirs of an Emacs user", which would be an artistic
representation of my process of Emacs and Org-mode gradually embracing
my life;-) - possibly including practical tips on Emacs usage?  Would
you mind talking about it here?  Would you mind asking people for input
(like, assume I might want to include some short interviews with people
from the Emacs community there)?

(Note: I'm not saying that I _want_ or _can_ write such a book, or that
anyone would find it interesting.  I just want to understand your stance
on books and what is allowed to talk about here, if only to decide if
I agree with you.)

Best,

--
Marcin Borkowski
http://mbork.pl

Re: Some ideas with Emacs

[Stefan Monnier]

> this is a very shady area - after all, disallowing reuse would put
> a stop to much of artistic creativity - but I would at least expect
> a modified version to be (a) easily distinguishable from the original
> and (b) prepared in such a way that the differeneces between the
> original and the modified version are visible without specialized tools
> (like diff).  From a cursory examination, GFDL secures (a), but not
> necessarily (b).

If you want to update an old textbook, I can definitely agree to stating
clearly the original book from which you started, but I see no need to
include a clear separation of what you changed (it might be nice to
include a brief summary, maybe, but I see no reason to request it from
the license).

Similarly, how/why would you list the differences for a translation of
the book (other than "translated from Foo by Bar")?


        Stefan

Re: Some ideas with Emacs

[Marcin Borkowski]

On 2019-12-02, at 19:07, Stefan Monnier <monnier@iro.umontreal.ca> wrote:

>> this is a very shady area - after all, disallowing reuse would put
>> a stop to much of artistic creativity - but I would at least expect
>> a modified version to be (a) easily distinguishable from the original
>> and (b) prepared in such a way that the differeneces between the
>> original and the modified version are visible without specialized tools
>> (like diff).  From a cursory examination, GFDL secures (a), but not
>> necessarily (b).
>
> If you want to update an old textbook, I can definitely agree to stating
> clearly the original book from which you started, but I see no need to
> include a clear separation of what you changed (it might be nice to
> include a brief summary, maybe, but I see no reason to request it from
> the license).

Well, I would expect e.g. all changes marked by footnotes or something
similar.

> Similarly, how/why would you list the differences for a translation of
> the book (other than "translated from Foo by Bar")?

This is a different thing - and most probably requiring a green light
from the original author.

Best,

-- 
Marcin Borkowski
http://mbork.pl

Re: Some ideas with Emacs

[Stefan Monnier]

>> Similarly, how/why would you list the differences for a translation of
>> the book (other than "translated from Foo by Bar")?
> This is a different thing - and most probably requiring a green light
> from the original author.

Not being allowed to write (and share) a translation without the
author's explicit consent is a big downer.  I'd consider this firmly on
the side of "not Free".

I can agree that the author may not want to have his name directly
attached to the translation, but that's a far cry from disallowing
translations altogether.


        Stefan

Re: Some ideas with Emacs

[Marcin Borkowski]

On 2019-12-02, at 22:19, Stefan Monnier <monnier@iro.umontreal.ca> wrote:

>>> Similarly, how/why would you list the differences for a translation of
>>> the book (other than "translated from Foo by Bar")?
>> This is a different thing - and most probably requiring a green light
>> from the original author.
>
> Not being allowed to write (and share) a translation without the
> author's explicit consent is a big downer.  I'd consider this firmly on
> the side of "not Free".

I never said I want to write a "free" (as in FSF) book.  (I wouldn't
totally exclude such a possibility, though, it's just not my current
plan.)  My opinion is that "free" (as in "free software" and "free
documentation") is a bad idea for books in general.

IOW, while I probably could agree that CC-ND might be a bit too harsh,
it is certainly better than GFDL (which is way too lax) in such a case.

In yet another words, even if I decide to release my book under GFDL one
day (assuming I manage to write it, which I consider quite probable -
after all, I'm finishing work on a third book with me as a (co)author),
I still think that at least for books better than mine GFDL is a bad
idea.

> I can agree that the author may not want to have his name directly
> attached to the translation, but that's a far cry from disallowing
> translations altogether.

I didn't say "disallowing".  I said "disallowing without an explicit
consent".  Have you heard the story about the infamous Swedish
translation of LotR?  While I would not compare any of my books (written
or to-be-written) with that of master JRRT, this is an important
cautionary tale.

I can live with manuals/documentation which are not good literature
(even though it's a pity, and I very much prefer ones that are
well-written - see e.g. DEK's The TeXbook).  Not so much for books (even
if _my_ books are only mediocre literature at best).

Best,

--
Marcin Borkowski
http://mbork.pl

Re: Some ideas with Emacs

[Stefan Monnier]

> I never said I want to write a "free" (as in FSF) book.

I'm not talking about any particular book or any particular author, but
I'm concerned here about whether I would consider a license "Free
enough" that I'd feel comfortable recommending the book to someone.

> I didn't say "disallowing".  I said "disallowing without an explicit
> consent".

That's pretty much the same, actually: a license only says what you can
do without asking for additional permission.  It doesn't prevent the
author from giving additional permissions upon request.

> Have you heard the story about the infamous Swedish
> translation of LotR?  While I would not compare any of my books (written
> or to-be-written) with that of master JRRT, this is an important
> cautionary tale.

That's why I said:

    I can agree that the author may not want to have his name directly
    attached to the translation, but that's a far cry from disallowing
    translations altogether.

E.g. I could accept a license which states that any derivative work
(translation or otherwise) needs to use a different title and/or clearly
say not only that it's a derivative of your work but also that it is not
your work.  Or something along these lines.


        Stefan

Re: Some ideas with Emacs

[Marcin Borkowski]

On 2019-12-02, at 23:41, Stefan Monnier <monnier@iro.umontreal.ca> wrote:

>> I never said I want to write a "free" (as in FSF) book.
>
> I'm not talking about any particular book or any particular author, but
> I'm concerned here about whether I would consider a license "Free
> enough" that I'd feel comfortable recommending the book to someone.

OK.  Does that mean that you only recommend "free" books to anyone?  Do
you make a distinction between paper books and electronic books?

Just in case: I'm not attacking you, RMS or anyone else.  I'm trying to
understand your opinions (which I think I disagree with).  Quite
possibly I'm attacking some of your opinions (e.g. because I consider
them false), but this is something else.

>> I didn't say "disallowing".  I said "disallowing without an explicit
>> consent".
>
> That's pretty much the same, actually: a license only says what you can
> do without asking for additional permission.  It doesn't prevent the
> author from giving additional permissions upon request.

I can agree with this.

>> Have you heard the story about the infamous Swedish
>> translation of LotR?  While I would not compare any of my books (written
>> or to-be-written) with that of master JRRT, this is an important
>> cautionary tale.
>
> That's why I said:
>
>     I can agree that the author may not want to have his name directly
>     attached to the translation, but that's a far cry from disallowing
>     translations altogether.
>
> E.g. I could accept a license which states that any derivative work
> (translation or otherwise) needs to use a different title and/or clearly
> say not only that it's a derivative of your work but also that it is not
> your work.  Or something along these lines.

That sounds fairly reasonable to me, I guess.  Does GFDL work this way?

I'm wondering whether there is some middle ground between CC-ND and GFDL
here.  For instance, one of the ideas I have would be to release a book
under a strict license, disallowing even copying verbatim, then under
CC-ND-something after, say, 3-5 years, and then GFDL after another 3-5
years.  This looks pretty fair to me.

On the other hand, such a scheme provokes an obvious question - why not
GFDL right away?  I don't have a good answer to this, I admit.  I would
probably be afraid that I'd lost a fair portion of any financial
compensation.  A book I coauthored was released under CC-BY-NC-SA (I
would probably substitute ND for NC today), and - together with my
coauthor - we almost earned the amount of money we put into it (IOW, we
had a net loss).  That's not entirely encouraging (although to be fair,
we did not aim for profit with that book).

Best,

--
Marcin Borkowski
http://mbork.pl

Re: Some ideas with Emacs

[Stefan Monnier]

> OK.  Does that mean that you only recommend "free" books to anyone?

Not exactly, no, but when there are Free books available, I'll usually
refrain from mentioning others in the same area.

>> E.g. I could accept a license which states that any derivative work
>> (translation or otherwise) needs to use a different title and/or clearly
>> say not only that it's a derivative of your work but also that it is not
>> your work.  Or something along these lines.
> That sounds fairly reasonable to me, I guess.  Does GFDL work this way?

I don't think so, but I'm not sure.  Maybe the invariant section can be
used for that.

I do vaguely remember some software using a license along those lines
which said that any derivative had to use another name (TeX, maybe?).
In some cases you can probably get similar results with a trademark,
which seems to match the underlying intention of being able to protect
your reputation.

> I'm wondering whether there is some middle ground between CC-ND and GFDL
> here.  For instance, one of the ideas I have would be to release a book
> under a strict license, disallowing even copying verbatim, then under
> CC-ND-something after, say, 3-5 years, and then GFDL after another 3-5
> years.  This looks pretty fair to me.

Along the lines of the Ghostscript system which used to release 1-year
old versions under the GPL while keeping the bleeding edge
proprietary, IIRC.


        Stefan

Re: Some ideas with Emacs

[Marcin Borkowski]

On 2019-12-03, at 01:20, Stefan Monnier <monnier@iro.umontreal.ca> wrote:

>> OK.  Does that mean that you only recommend "free" books to anyone?
>
> Not exactly, no, but when there are Free books available, I'll usually
> refrain from mentioning others in the same area.

I see.  The problem in this particular case is that no free books are
available in the same area (in fact, the only book available as of now
is Glickstein's "Writing GNU Emacs Extensions", which I think is not
very up-to-date - and I don't believe it is free, either).

>>> E.g. I could accept a license which states that any derivative work
>>> (translation or otherwise) needs to use a different title and/or clearly
>>> say not only that it's a derivative of your work but also that it is not
>>> your work.  Or something along these lines.
>> That sounds fairly reasonable to me, I guess.  Does GFDL work this way?
>
> I don't think so, but I'm not sure.  Maybe the invariant section can be
> used for that.
>
> I do vaguely remember some software using a license along those lines
> which said that any derivative had to use another name (TeX, maybe?).

Yes, TeX does such a thing.

> In some cases you can probably get similar results with a trademark,
> which seems to match the underlying intention of being able to protect
> your reputation.
>
>> I'm wondering whether there is some middle ground between CC-ND and GFDL
>> here.  For instance, one of the ideas I have would be to release a book
>> under a strict license, disallowing even copying verbatim, then under
>> CC-ND-something after, say, 3-5 years, and then GFDL after another 3-5
>> years.  This looks pretty fair to me.
>
> Along the lines of the Ghostscript system which used to release 1-year
> old versions under the GPL while keeping the bleeding edge
> proprietary, IIRC.

Yes, this is close.

Best,

--
Marcin Borkowski
http://mbork.pl

Re: Some ideas with Emacs

[VanL]

> we almost earned the amount of money we put into it (IOW, we had a net
> loss).  That's not entirely encouraging (although to be fair, we did
> not aim for profit with that book).

There is the possibility to try crowdfunding before starting.  That is
how a non-violent musical genre videogame got started as reported by
GameInformer.

-- 
LoL,
  School of Secret Art
  əə0@ 一 二 三 言 語 𝔖

Re: Some ideas with Emacs

[Marcin Borkowski]

On 2019-12-03, at 09:37, VanL <van@scratch.space> wrote:

>> we almost earned the amount of money we put into it (IOW, we had a net
>> loss).  That's not entirely encouraging (although to be fair, we did
>> not aim for profit with that book).
>
> There is the possibility to try crowdfunding before starting.  That is
> how a non-violent musical genre videogame got started as reported by
> GameInformer.

This is something I consider.  Do you know any crowdfunding platforms
worth recommending?

Best,

-- 
Marcin Borkowski
http://mbork.pl

Re: Some ideas with Emacs

[VanL]

Marcin Borkowski <mbork@mbork.pl> writes:

>>> we almost earned the amount of money we put into it (IOW, we had a net
>>> loss).  That's not entirely encouraging (although to be fair, we did
>>> not aim for profit with that book).
>>
>> There is the possibility to try crowdfunding before starting.  That is
>> how a non-violent musical genre videogame got started as reported by
>> GameInformer.
>
> This is something I consider.  Do you know any crowdfunding platforms
> worth recommending?

The interview with the two developers behind the videogame mentioned
above is buried in one of the recent GameInformer episodes the search
engine can't locate.

I have no experience on any crowdfunding platform, but do use apps and
extensions which began with crowdfunding.  As an example [1], here is a
product in second iteration with crowdfunding reaching $4.6M from 10,732
backers.

You could try listing crowdfunding platforms from Wikipedia and evaluate
their value to you based on product success stories for your audience.

Footnotes: 
[1]  https://invidio.us/watch?v=2hBWQ_uLdj8
     A Very Strange Phone Emerges...
     Light Phone 2 on Indiegogo at 1-minute

-- 
LoL,
  School of Secret Art
  əə0@ 一 二 三 言 語 𝔖

Re: Some ideas with Emacs

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

Most crowdfunding systems require nonfree programs to pay,
and that requires running nonfree software.  Two exceptions
are Goteo, and Code and Supply.


-- 
Dr Richard Stallman
Founder, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Some ideas with Emacs

[Elias Mårtenson]

[-- Attachment #1: Type: text/plain, Size: 316 bytes --]

On Thu, 5 Dec 2019, 12:45 Richard Stallman, <rms@gnu.org> wrote:

>
> Most crowdfunding systems require nonfree programs to pay,
> and that requires running nonfree software.  Two exceptions
> are Goteo, and Code and Supply.
>

Would Liberapay qualify as an acceptable platform for a GNU project?

Regards,
Elias

>

[-- Attachment #2: Type: text/html, Size: 874 bytes --]

Re: Some ideas with Emacs

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Would Liberapay qualify as an acceptable platform for a GNU project?

I don't know anything about it, but you can easily find out by testing it.
Try running IceCat with LibreJS enabled and see if it works to pay.
Also try disabling JS in IceCat and see if it works to pay.
You can also try lynx and see if it works to pay.

If any of those works reliably, we can urge people to use it.

-- 
Dr Richard Stallman
Founder, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Some ideas with Emacs

[Elias Mårtenson]

[-- Attachment #1: Type: text/plain, Size: 637 bytes --]

On Fri, 6 Dec 2019, 12:11 Richard Stallman, <rms@gnu.org> wrote:

> pay.
>
> If any of those works reliably, we can urge people to use it.
>

The source code is apparently CC0 based on the README in their source
repository:
https://github.com/liberapay/liberapay.com/blob/master/README.md#license

Also their legal disclaimers are both readable and reasonable to me, that's
a good sign: https://liberapay.com/about/legal

In fact, to me it looks so good that it feels like I'm missing something.

I'd be more comfortable if someone else looked at the terms of service to
see if they come up with a similar conclusion.

Regards,
Elias

>

[-- Attachment #2: Type: text/html, Size: 1476 bytes --]

Librepay

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

I found I got some advice about librepay in the past.
Their system seems to include holding money in escrow.
The advice I got was to ask to see scans of the passports of
the people who have control over the system, so as to be confident
they will handle the money properly.

-- 
Dr Richard Stallman
Founder, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Librepay

[VanL]

> I found I got some advice about librepay in the past.
> Their system seems to include holding money in escrow.
> The advice I got was to ask to see scans of the passports of
> the people who have control over the system, so as to be confident
> they will handle the money properly.

OpenBSD Amsterdam processes money through PayPal, iDEAL, SEPA. [1]  I
lookup to OpenBSD for having a clue on security matters.


Footnotes: 
[1]  https://openbsd.amsterdam/

-- 
VanL,
  School of Secret Art
  əə0@ 一 二 三 言 語 𝔖        ⊥    'What were the numbers?'  -Donald J. Trump 

Re: Some ideas with Emacs

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > E.g. I could accept a license which states that any derivative work
  > (translation or otherwise) needs to use a different title and/or clearly
  > say not only that it's a derivative of your work but also that it is not
  > your work.  Or something along these lines.

The GFDL has such a requirement.

-- 
Dr Richard Stallman
Founder, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Some ideas with Emacs

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > A _manual_ should be e.g. comprehensive (i.e., cover the whole of its
  > subject).  A _book_ on a subject does not have to be so.

I see the distinction you are making, but it doesn't affect our stance.

Our principles of free documentation apply to any works that we would
distribute or recommend to help people learn to use the software.
Whether it is a manual meant to be complete, or a book that treats any
choice of topics, if it doesn't carry a free license we ought not to
refer users to it in any way.  What we ought to do is use or write
some free documentation to explain the same methods and techniques.

  > Could you define "political points which are outside the practical topic
  > of the manual"?

There is a precise criterion in the GFDL itself.

  >   The FSF does refer to e.g. MS
  > Windows (in the Emacs manual, of all places).  How is a CC-NC/CC-ND book
  > (not "manual"!!!) worse than that?

The Emacs manual does not recommend using Windows.  It refers to
running Emacs on Windows to encourage Windows users to run Emacs.  We
consider it ok to mention the existence of Windows because we expect
users already know about it.  It is unlikely anyone will learn about
the existence of Windows from the Emacs Manual and start using Windows
as a result.

See the section References in the GNU Coding Standards for the way
we judge such questions.

We have the motto that a nonfree program is worse than no program at
all.  What does this mean?

It is clear that a nonfree program might be of some practical use,
whereas a nonexistent program is of zero practical use.  The point of
this motto is precisely that we don't judge solely by practical use.
Our goal is to win freedom, so we prize freedom over practical use.
The nonfree program is not a contribution to the free world -- rather,
it is a trap that we should help people climb out of.

The same applied to documentation (manuals or not).  Documentation simply
means a work that teaches you how to use something.  I think the book
you have in mind would be documentation.

Would you please make your book free, so that it contributes?

  > As an even more theoretical exercise, assume I wanted to write a book...
  > called "Memoirs of an Emacs user", which would be an artistic
  > representation of my process of Emacs and Org-mode gradually embracing
  > my life;-) - possibly including practical tips on Emacs usage?  Would
  > you mind talking about it here?

A book like this would not be documentation -- at least, mostly not.
It would be a sort of memoir.  I think CC-NC-ND is an acceptable
license for a memoir, precisely because it is NOT documentation -- it
does not have the purpose of teaching people practical skills or
guiding them in doing a task.

See https://gnu.org/philosophy/copyright-vs-community.html for more
explanation.

-- 
Dr Richard Stallman
Founder, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Some ideas with Emacs

[Marcin Borkowski]

On 2019-12-03, at 05:58, Richard Stallman <rms@gnu.org> wrote:

> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
>   > A _manual_ should be e.g. comprehensive (i.e., cover the whole of its
>   > subject).  A _book_ on a subject does not have to be so.
>
> I see the distinction you are making, but it doesn't affect our stance.

I see.

What about "non-free", paper-only books I asked about?

> Our principles of free documentation apply to any works that we would
> distribute or recommend to help people learn to use the software.
> Whether it is a manual meant to be complete, or a book that treats any
> choice of topics, if it doesn't carry a free license we ought not to
> refer users to it in any way.  What we ought to do is use or write
> some free documentation to explain the same methods and techniques.

Let me say that I admire your stance (even if I do not agree with it).
I have to say that being convinced about existence of objective moral
principles and defending them firmly is a rare thing nowadays.

>   > Could you define "political points which are outside the practical topic
>   > of the manual"?
>
> There is a precise criterion in the GFDL itself.

I see.

>   >   The FSF does refer to e.g. MS
>   > Windows (in the Emacs manual, of all places).  How is a CC-NC/CC-ND book
>   > (not "manual"!!!) worse than that?
>
> The Emacs manual does not recommend using Windows.  It refers to
> running Emacs on Windows to encourage Windows users to run Emacs.  We
> consider it ok to mention the existence of Windows because we expect
> users already know about it.  It is unlikely anyone will learn about
> the existence of Windows from the Emacs Manual and start using Windows
> as a result.

OK, that makes sense.

> See the section References in the GNU Coding Standards for the way
> we judge such questions.

I read the relevant part.  I think the crucial thing is (again) the
question whether such a book is "documentation" or not.  (In my opinion
it is not.)

> We have the motto that a nonfree program is worse than no program at
> all.  What does this mean?
>
> It is clear that a nonfree program might be of some practical use,
> whereas a nonexistent program is of zero practical use.  The point of
> this motto is precisely that we don't judge solely by practical use.
> Our goal is to win freedom, so we prize freedom over practical use.
> The nonfree program is not a contribution to the free world -- rather,
> it is a trap that we should help people climb out of.

While I do not agree with you here, I admit that this stance is
consistent.  And again, putting morality above practicality is something
I consider in general a rare and good thing.  (BTW, off the top of my
head, I can't think of any organization believing really firmly in its
principles and valuing them above pragmatism even against a majority
besides the Roman Catholic Church and the FSF.)

> The same applied to documentation (manuals or not).  Documentation simply
> means a work that teaches you how to use something.  I think the book
> you have in mind would be documentation.

As I mentioned above, my definition is different.  Let me try to
explain.  (This may be a bit oversimplified, but I want to convey the
general idea.  Also, I will use the word "free" in the sense you use it
to talk about software and documentation.)

Elisp Reference is documentation.  It contains everything you need to
understand Elisp.  Its purpose is to _teach Elisp_.  I think I agree
that documentation to free software should (in the moral sense) be free.

Elisp Intro is _not_ documentation, it is a textbook.  It contains
nothing new you could not learn or easily think up yourself after you
read and understood the Elisp Reference.  Its purpose is to teach Elisp
_in an easier and faster way_.  I think it is nice but not required
(again, in the moral sense) that a textbook about free software is free.

Now what I've written above is not strictly and logically correct:
formally, you don't _ever_ need documentation for free software, because
you have the source code.  So I would guess that there is some
subjectivity here - what is and what is not "documentation" depends on
the audience (a sufficiently advanced programmer does not need even the
Elisp Reference at all).  This problem might mean that either I am
wrong, or it makes sense to consider an "average user" or a similar
construct.

Notice that the "References" section to GNU Coding Standards
(https://www.gnu.org/prep/standards/standards.html#References), which
was mentioned earlier in this thread, seems to suffer from a very
similar problem when it uses the criterion of a non-free program or
system to be "well known".

> Would you please make your book free, so that it contributes?

I am considering this as one of the options.

>   > As an even more theoretical exercise, assume I wanted to write a book...
>   > called "Memoirs of an Emacs user", which would be an artistic
>   > representation of my process of Emacs and Org-mode gradually embracing
>   > my life;-) - possibly including practical tips on Emacs usage?  Would
>   > you mind talking about it here?
>
> A book like this would not be documentation -- at least, mostly not.
> It would be a sort of memoir.  I think CC-NC-ND is an acceptable
> license for a memoir, precisely because it is NOT documentation -- it
> does not have the purpose of teaching people practical skills or
> guiding them in doing a task.
>
> See https://gnu.org/philosophy/copyright-vs-community.html for more
> explanation.

Thanks for your explanation.  I will definitely read that document.

Best regards,

--
Marcin Borkowski
http://mbork.pl

Re: Some ideas with Emacs

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Elisp Reference is documentation.  It contains everything you need to
  > understand Elisp.  Its purpose is to _teach Elisp_.  I think I agree
  > that documentation to free software should (in the moral sense) be free.

  > Elisp Intro is _not_ documentation, it is a textbook.

I think that that definition of "documentation" is too narrow.

Back when companies provided manuals along with their software, and
people generally read these manuals, the manuals generally included
introductions and reference manuals.  For each component, there was an
introduction manual that you read to learn how to use it, and a
reference manual you would use to check specific points once you know,
generally, how to use it.

I wanted to provide this level of documentation for the GNU system,
but the amount of work would have been prohibitive.  To reduce it, I
developed the method whereby a manual starts out as an introduction
and then changes into a reference.  This generally requires a certain
amount of duplication, but much less than 100% duplication, so it
results in big savings of size and of work.

Emacs Lisp is a partial exception.  Because Bob Chassell wrote the intro,
the main manual doesn't have to start out in an introductory manner.

However, the Emacs Manual does start out in an introductory manner.
It is written so you can read it straight through and learn to edit
with Emacs.

Turning to the broader ethical issue, I think that _all_ textbooks,
indeed all educational resources, ought to be free -- because they
exist to be _used_ for a practical job: f teaching or learning a
subject.

A calculus textbook is not documentation, because the subject
it teaches is not how to use some tool or appliance.  But I think
the two are similar in the basic moralily of the cases.

The memoir you proposed writing is not an educational resource.  It
would exist mainly to show your personal point of view, not for
practical use.  Reading it could be interesting, but it would not be
_using_ the memoir.  That is why I reach different conclusions about
the memoir.

  > Now what I've written above is not strictly and logically correct:
  > formally, you don't _ever_ need documentation for free software, because
  > you have the source code.

Our judgments of right and wront for _our_ conduct have to take
account of its likely effects, and that depends on the world we are in.

If our users were superhuman, they might not need any sort of manuals
-- they would read the source code and that would be enough.  They
might not even need to get software from anyone: a smart enough being
could write for itself all software it wants.  But our users are
human, not in general smarter than we ourselves.

  > Notice that the "References" section to GNU Coding Standards
  > (https://www.gnu.org/prep/standards/standards.html#References), which
  > was mentioned earlier in this thread, seems to suffer from a very
  > similar problem when it uses the criterion of a non-free program or
  > system to be "well known".

That is another example of paying attention to the nature of the world
we are in.  If we knew that our users would defend their freedom
firmly once introduced to free software, we could mention nonfree
programs without worrying that readers would start to use them.

But that is not the case.  We need to try to reconcile the goals of
(1) telling people how to get the best use of Emacs when they also use
some nonfree programs, (2) showing we condemn those nonfree programs
for taking away users' freedom, and (3) not encouraging use of them.

I think these goals are _mostly_ compatible: we can do all of them
pretty well together, even if not perfectly.



-- 
Dr Richard Stallman
Founder, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Some ideas with Emacs

[Marcin Borkowski]

On 2019-12-05, at 05:41, Richard Stallman <rms@gnu.org> wrote:

> Turning to the broader ethical issue, I think that _all_ textbooks,
> indeed all educational resources, ought to be free -- because they
> exist to be _used_ for a practical job: f teaching or learning a
> subject.

Having thought about it, I have to say that I am not at all convinced.
Quite the contrary - I would be suspicious about free educational
resources.

Why is that so?  Because if someone provides me with information (be it
of educational nature or otherwise), and I do not pay for it, this means
that it is quite probable that someone else paid for it.  And the goals
of the "someone else" may be very different from my ones.

That might not matter that much in case of a calculus textbook, or Emacs
manual.  But I would *never* give my child a "free history textbook"
(for example) unless I made really sure that the author did not try to
push some nasty agenda with it.  (And I have seen such textbooks myself
- see below.)

Another reason for my suspicions may be the fact that I have lived in
a communist country for some part of my life.  Most people in the US do
not have such experience, and that is probably the reason they allow the
poison of communist ideology to invade their thinking.  (In fact, from
what I read, the US have almost become a communist country nowadays.
I would not want to live there at all!  Free speech in the US is
definitely a thing of past, and I will not be surprised if the US
ditches capitalism and whatever is left of free markets within a decade.
Not that I think free market is a silver bullet, but in many cases it
seems a good economic solution.)

And the idea of free educational resources does smell of communism.
A lot.

Yet another problem with "free educational resources" is: who would pay
for them?  And if nobody, who would create them?  This is of course not
a moral issue, but a pragmatic one - but an issue it is.

Of course, I am perhaps mixing the two meanings of the word "free".  But
this does not matter that much, because if something is "free as in free
beer", that means that someone does not get paid for it, and if
something digital is "free as in freedom" (e.g., free to copy), that
usually means that someone won't get paid for it as much as if it were
"non-free".

Best,

--
Marcin Borkowski
http://mbork.pl

Re: Some ideas with Emacs

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

Please forgive me for taking so long to respond.  I am  backlogged
500 messages I have not yet seen.  I just saw your message today.

I wrote:

  > > Turning to the broader ethical issue, I think that _all_ textbooks,
  > > indeed all educational resources, ought to be free -- because they
  > > exist to be _used_ for a practical job: f teaching or learning a
  > > subject.

You wrote:

  > Quite the contrary - I would be suspicious about free educational
  > resources.

  > Why is that so?  Because if someone provides me with information (be it
  > of educational nature or otherwise), and I do not pay for it, this means
  > that it is quite probable that someone else paid for it.  And the goals
  > of the "someone else" may be very different from my ones.

I believe we are miscommunicating.  When I say "free" it refers to
freedom -- "wolne" in Polish.  I believe you are talking about whether
you have to pay for a copy -- "darmowe".

Our definition of "free" for textbooks is basically our definition
of "free software"; see https://gnu.org/philosophy/free-sw.html.

Special interests with lots of money are already capable of pushing
their positions into textbooks.

When a nonfree educational resources is published, if it contains
bogus claims, you can't change them.  If the resource is free, you can
make a modified version and distribute that.

  >   But I would *never* give my child a "free history textbook"
  > (for example) unless I made really sure that the author did not try to
  > push some nasty agenda with it.

The non-wolne history textbooks in the US have such problems too.  The
book Lies My Teacher Told Me, by James Loewin, explains some.  There
are strong partisan pressures on what to say school textbooks.  And
not just in history -- also in biology, geology and medicine.  But
this is getting off topic for GNU.

For decades, our detractors have claimed that free software can't
exist, or that it has to be inferior, based on arguments similar to
the ones you have made.

Meanwhile, there are now many educational resources which come close
to being wolne without, alas, actually being wolne.  They are called
"open educational resources".  Many come from universities that could
just as well make them wolne.  See
stallman.org/articles/online-education.html.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Some ideas with Emacs

[Stefan Kangas]

Anonymous <c4droid@foxmail.com> writes:

> First, suggest to add more examples of functions in the tutorial,
> most for Emacs Lisp Reference Manual, which can lower the learning
> threshold.

I think this is a fine idea that would make the manual more useful.
But the elisp manual is also printed on paper, and is from what I
understand already very long.  Does it make sense to include examples
in the info manual only?

> Second, in developing the Emacs plugins, create a virtual
> environment, like Python virtualenv, so that we can test the plugin
> in the virtual environment so that we do not need to affect the
> configuration outside the virtual environment. That's can implement
> plugin development environment and configuration isolation.

I think what you would do is something like "emacs -Q -l myenv.el" and
then set up the load-path, requires, and whatever else you need in
myenv.el.

> Although my suggestion may be a little trivial and even useless. But
> if my suggestions can help beginners like me go further, I think
> it's worth it.

We very much need to get more people hacking on Emacs.  So any
suggestion which could help us achieve that is welcome, I think.

Best regards,
Stefan Kangas

Re: Some ideas with Emacs

[Anonymous]

[-- Attachment #1: Type: text/plain, Size: 2221 bytes --]

I mean, include one or two examples for tell reader the describe function how to use, that's enough.
Call emacs with -Q -l option to load plugin development options file, it's also a solution. Suppose I have configured the development environment, but do not have to have the configuration to start, without code completion, have a little uncomfortable for me. :)


---Original---
From: &quot;Stefan Kangas&quot;<stefan@marxist.se&gt;
Date: Fri, Nov 29, 2019 19:37 PM
To: &quot;Anonymous&quot;<c4droid@foxmail.com&gt;;
Cc: &quot;emacs-devel&quot;<emacs-devel@gnu.org&gt;;
Subject: Re: Some ideas with Emacs


Anonymous <c4droid@foxmail.com&gt; writes:

&gt; First, suggest to add more examples of functions in the tutorial,
&gt; most for Emacs Lisp Reference Manual, which can lower the learning
&gt; threshold.

I think this is a fine idea that would make the manual more useful.
But the elisp manual is also printed on paper, and is from what I
understand already very long.&nbsp; Does it make sense to include examples
in the info manual only?

&gt; Second, in developing the Emacs plugins, create a virtual
&gt; environment, like Python virtualenv, so that we can test the plugin
&gt; in the virtual environment so that we do not need to affect the
&gt; configuration outside the virtual environment. That&#39;s can implement
&gt; plugin development environment and configuration isolation.

I think what you would do is something like &quot;emacs -Q -l myenv.el&quot; and
then set up the load-path, requires, and whatever else you need in
myenv.el.

&gt; Although my suggestion may be a little trivial and even useless. But
&gt; if my suggestions can help beginners like me go further, I think
&gt; it&#39;s worth it.

We very much need to get more people hacking on Emacs.&nbsp; So any
suggestion which could help us achieve that is welcome, I think.

Best regards,
Stefan Kangas

[-- Attachment #2: Type: text/html, Size: 2611 bytes --]

Emacs: the Editor for the Next Forty Years (was Re: Some ideas with Emacs)

[Juanma Barranquero]

[-- Attachment #1: Type: text/plain, Size: 327 bytes --]

On Fri, Nov 29, 2019 at 1:04 PM Stefan Kangas <stefan@marxist.se> wrote:

> We very much need to get more people hacking on Emacs.

With reminds me...

Did someone hear (or attend to) Perry E. Metzger's talk in this years'
EmacsConf?

https://media.emacsconf.org/2019/26.html

And if so, does anyone have any opinion about it?

[-- Attachment #2: Type: text/html, Size: 565 bytes --]

Re: Some ideas with Emacs

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Fri, 29 Nov 2019 12:37:31 +0100
> Cc: emacs-devel <emacs-devel@gnu.org>
> 
> Anonymous <c4droid@foxmail.com> writes:
> 
> > First, suggest to add more examples of functions in the tutorial,
> > most for Emacs Lisp Reference Manual, which can lower the learning
> > threshold.
> 
> I think this is a fine idea that would make the manual more useful.
> But the elisp manual is also printed on paper, and is from what I
> understand already very long.  Does it make sense to include examples
> in the info manual only?

I think if we want to have an ELisp tutorial, it should be a separate
manual.  The current ELisp manual is a reference manual, and written
as such.

Re: Some ideas with Emacs

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> I think if we want to have an ELisp tutorial, it should be a separate
> manual.  The current ELisp manual is a reference manual, and written
> as such.

I fail to see why a reference manual can't also include examples.
I've had to search the web to understand how to use things before,
even after having carefully read the relevant parts of the elisp
manual and the doc string.  An example says a thousand words, as the
saying goes...

I think the Python documentation is very good in this regard.  Here is
one example:

https://docs.python.org/3/library/stdtypes.html#mapping-types-dict

To be clear, I'm not suggesting that we should mandate that we should
include examples.  But I'd suggest to optionally add them where it
makes sense, and possibly then only in the info version of the manual
(since we lack space in the print edition).

Best regards,
Stefan Kangas

Re: Some ideas with Emacs

[Eduardo Ochs]

[-- Attachment #1: Type: text/plain, Size: 4028 bytes --]

Hi Anonymous and other people,

most people test small snippets of elisp code by executing sexps with
`C-x C-e' or variants of it, not by loading elisp files. My
(admittedly biased!) feeling is that the best way to help beginners
learn Lisp is by giving them sexps to play with - configurations,
plugins, and even long texts in English, are secondary...

I tried to do something in this direction in a package that I wrote
called "eev" that I often use to teach Emacs and programming to total
beginners - here are some links to it:

  http://angg.twu.net/#eev
  http://angg.twu.net/emacsconf2019.html
  http://elpa.gnu.org/packages/eev.html

It comes with lots of tutorials. If you run

  (find-eev-quick-intro)
  (find-eev-intro)
  (find-eval-intro)

these sexps will open three of its "sandboxed tutorials" in temporary
read-write buffers; I use read-write buffers to let users play with
the sexps in them more easily. Here are links to the htmlized versions
of these three tutorials:

  http://angg.twu.net/eev-intros/find-eev-quick-intro.html
  http://angg.twu.net/eev-intros/find-eev-intro.html
  http://angg.twu.net/eev-intros/find-eval-intro.html

The tutorial in (find-eval-intro) is one of the ones that is still
very messy and in need of being rewritten, but there are is a section
in it I think that is relevant to this discussion. You can access it
with:

  http://angg.twu.net/eev-intros/find-eval-intro.html#10
  (find-eval-intro "10. More on functions")

but let me copy it here...



  10. More on functions
  =====================
  A symbol - for example `f' - can be both a varible and a
  function; its "value as a variable" and its "value as a
  function" are stored in different places. Try:

    (setq f 2)
    (setq f 5)
    (defun f (x) (* x x))
    (defun f (x) (* 10 x))
    (symbol-value    'f)
    (symbol-function 'f)

  This is explained here:

    (find-elnode "Symbol Components")
    (find-elnode "Symbol Components" "value cell")
    (find-elnode "Symbol Components" "function cell")

  The content of a "function cell" is _usually_ a lambda
  expression. See:

    (find-elnode "Lambda Expressions")
    (find-elnode "What Is a Function")
    (find-elnode "What Is a Function" "lambda expression")
    (find-elnode "What Is a Function" "byte-code function")

  Try:

    (setq f 2)
    (setq f 5)
    (set 'f 2)
    (set 'f 5)
    (fset 'f (lambda (x) (* x x)))
    (fset 'f (lambda (x) (* 10 x)))
    (defun f (x) (* 10 x))
    (defun f (x) (* x x))
    (symbol-value    'f)
    (symbol-function 'f)
    (f 4)
    (f f)

    ((lambda (x) (* x x))
     4)
    ((lambda (x) (* 10 x))
     4)


I have only used that particular section in a couple of workshops -
i.e., in situations where the participants could easily try things,
discuss with their neighbors, and ask questions - but the point is
that I feel that we need more material like this... and I would love
to work with other people to produce it.

  Cheers,
    Eduardo Ochs
    http://angg.twu.net/#eev


On Fri, 29 Nov 2019 at 10:44, Stefan Kangas <stefan@marxist.se> wrote:

> Eli Zaretskii <eliz@gnu.org> writes:
>
> > I think if we want to have an ELisp tutorial, it should be a separate
> > manual.  The current ELisp manual is a reference manual, and written
> > as such.
>
> I fail to see why a reference manual can't also include examples.
> I've had to search the web to understand how to use things before,
> even after having carefully read the relevant parts of the elisp
> manual and the doc string.  An example says a thousand words, as the
> saying goes...
>
> I think the Python documentation is very good in this regard.  Here is
> one example:
>
> https://docs.python.org/3/library/stdtypes.html#mapping-types-dict
>
> To be clear, I'm not suggesting that we should mandate that we should
> include examples.  But I'd suggest to optionally add them where it
> makes sense, and possibly then only in the info version of the manual
> (since we lack space in the print edition).
>
> Best regards,
> Stefan Kangas
>
>

[-- Attachment #2: Type: text/html, Size: 5679 bytes --]

Re: Some ideas with Emacs

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Fri, 29 Nov 2019 14:34:44 +0100
> Cc: Anonymous <c4droid@foxmail.com>, Emacs developers <emacs-devel@gnu.org>
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > I think if we want to have an ELisp tutorial, it should be a separate
> > manual.  The current ELisp manual is a reference manual, and written
> > as such.
> 
> I fail to see why a reference manual can't also include examples.

I was talking about a tutorial, not about examples.

We already have examples in the ELisp manual, although it isn't
feasible to have an example for each possible use case.  We could add
more examples where the description is not self-explanatory enough,
but adding too much of them would be infeasible, I think, due to size
considerations.  We will have to consider that on a case by case
basis.

> I've had to search the web to understand how to use things before,
> even after having carefully read the relevant parts of the elisp
> manual and the doc string.

A better strategy is to search the Emacs tree, IME.

> To be clear, I'm not suggesting that we should mandate that we should
> include examples.  But I'd suggest to optionally add them where it
> makes sense, and possibly then only in the info version of the manual
> (since we lack space in the print edition).

We already have examples where we think it's useful.

Re: Some ideas with Emacs

[Anonymous]

[-- Attachment #1: Type: text/plain, Size: 1821 bytes --]

Agree.


---Original---
From: &quot;Eli Zaretskii&quot;<eliz@gnu.org&gt;
Date: Fri, Nov 29, 2019 22:14 PM
To: &quot;Stefan Kangas&quot;<stefan@marxist.se&gt;;
Cc: &quot;c4droid&quot;<c4droid@foxmail.com&gt;;&quot;emacs-devel&quot;<emacs-devel@gnu.org&gt;;
Subject: Re: Some ideas with Emacs


&gt; From: Stefan Kangas <stefan@marxist.se&gt;
&gt; Date: Fri, 29 Nov 2019 14:34:44 +0100
&gt; Cc: Anonymous <c4droid@foxmail.com&gt;, Emacs developers <emacs-devel@gnu.org&gt;
&gt; 
&gt; Eli Zaretskii <eliz@gnu.org&gt; writes:
&gt; 
&gt; &gt; I think if we want to have an ELisp tutorial, it should be a separate
&gt; &gt; manual.&nbsp; The current ELisp manual is a reference manual, and written
&gt; &gt; as such.
&gt; 
&gt; I fail to see why a reference manual can&#39;t also include examples.

I was talking about a tutorial, not about examples.

We already have examples in the ELisp manual, although it isn&#39;t
feasible to have an example for each possible use case.&nbsp; We could add
more examples where the description is not self-explanatory enough,
but adding too much of them would be infeasible, I think, due to size
considerations.&nbsp; We will have to consider that on a case by case
basis.

&gt; I&#39;ve had to search the web to understand how to use things before,
&gt; even after having carefully read the relevant parts of the elisp
&gt; manual and the doc string.

A better strategy is to search the Emacs tree, IME.

&gt; To be clear, I&#39;m not suggesting that we should mandate that we should
&gt; include examples.&nbsp; But I&#39;d suggest to optionally add them where it
&gt; makes sense, and possibly then only in the info version of the manual
&gt; (since we lack space in the print edition).

We already have examples where we think it&#39;s useful.

[-- Attachment #2: Type: text/html, Size: 2229 bytes --]

Re: Some ideas with Emacs

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> > I fail to see why a reference manual can't also include examples.
>
> I was talking about a tutorial, not about examples.

I misunderstood what you meant.  Sorry about that.

> We already have examples in the ELisp manual, although it isn't
> feasible to have an example for each possible use case.  We could add
> more examples where the description is not self-explanatory enough,
> but adding too much of them would be infeasible, I think, due to size
> considerations.  We will have to consider that on a case by case
> basis.

Agreed, and thank you for clarifying.  That makes sense.

Best regards,
Stefan Kangas

Re: Some ideas with Emacs

[Emanuel Berg via Emacs development discussions.]

Eli Zaretskii wrote:

> We could add more examples where the
> description is not self-explanatory
> enough [...]

And when the common use case is somehow
different or unexpected, from reading
the description.

And when there is a really exotic use-case
that no one would ever think of from just
reading the description.

Ever read grammar book for natural (human)
languages? First there are a bunch of rules.
One is like "...?" Then comes examples. And one
is like "aah"!

Finding _the right_ examples is the challenge.
Examples that illustrate the rule(s) and also
tells something interesting in their own right.

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Some ideas with Emacs

[Stefan Monnier]

> I fail to see why a reference manual can't also include examples.

I don't think anyone would suggest that examples don't belong there.
Manpages are typical "reference manuals" and many of them
include(d) examples.

AFACT, currently we have some examples in the Elisp manual and very
few examples in docstrings.
It might be a good idea to encourage the addition of examples either in
docstrings or in the Elisp manual (or both).


        Stefan

Re: Some ideas with Emacs

[Michael Albinus]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> AFACT, currently we have some examples in the Elisp manual and very
> few examples in docstrings.
> It might be a good idea to encourage the addition of examples either in
> docstrings or in the Elisp manual (or both).

Personally, I don't like docstring to be too verbose. Usually, when a
function is documented with both docstrings and a manual, I prefer to
put the examples in the manual.

But that's my taste, and maybe not the best approach. Don't know.

>         Stefan

Best regards, Michael.

Adding examples in the doc (was: Some ideas with Emacs)

[Stefan Monnier]

>> AFACT, currently we have some examples in the Elisp manual and very
>> few examples in docstrings.
>> It might be a good idea to encourage the addition of examples either in
>> docstrings or in the Elisp manual (or both).
> Personally, I don't like docstring to be too verbose.

I tend to agree.  Of course part of it is that a verbose docstring is an
indication that the function is complex to use, but there's also simply
the impact on the visual distance between the function header and the code.

Another issue w.r.t examples is that editing Elisp code within
docstrings is a PITA (you don't get the usual
completion/indentation/... plus you have to be careful with escaping
' and friends so they don't get "shaped").

Also, docstrings have no formal structure and usually contain text, so
if we want to add examples in docstrings, I would prefer we first design
a structure to clearly distinguish text from code so we can render it
more elegantly.

Maybe examples should simply live *outside* of the function definition,
e.g. with

    (defexamples ...)

This might also have the benefit of being able to associate an example
with several functions (when the example shows how to combine calls to
various functions to get a particular result).

> Usually, when a function is documented with both docstrings and
> a manual, I prefer to put the examples in the manual.

I find code in texi files to be less convenient to edit/use.


        Stefan

Re: Adding examples in the doc (was: Some ideas with Emacs)

[Yuan Fu]

[-- Attachment #1: Type: text/plain, Size: 671 bytes --]


>>> AFACT, currently we have some examples in the Elisp manual and very
>>> few examples in docstrings.
>>> It might be a good idea to encourage the addition of examples either in
>>> docstrings or in the Elisp manual (or both).
>> Personally, I don't like docstring to be too verbose.
> 
> I tend to agree.  Of course part of it is that a verbose docstring is an
> indication that the function is complex to use, but there's also simply
> the impact on the visual distance between the function header and the code.

FYI there is a package that does similar things: https://github.com/xuchunyang/elisp-demos <https://github.com/xuchunyang/elisp-demos>

Yuan

[-- Attachment #2: Type: text/html, Size: 1260 bytes --]

Re: Adding examples in the doc

[Michael Albinus]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> Usually, when a function is documented with both docstrings and
>> a manual, I prefer to put the examples in the manual.
>
> I find code in texi files to be less convenient to edit/use.

I always prepare the example in *scratch*. Copied to the texi file only
when it works.

>         Stefan

Best regards, Michael.

Re: Some ideas with Emacs

[Eli Zaretskii]

> From: Michael Albinus <michael.albinus@gmx.de>
> Cc: Stefan Kangas <stefan@marxist.se>,  Eli Zaretskii <eliz@gnu.org>,
>   Anonymous <c4droid@foxmail.com>,  Emacs developers <emacs-devel@gnu.org>
> Date: Fri, 29 Nov 2019 19:58:21 +0100
> 
> Stefan Monnier <monnier@iro.umontreal.ca> writes:
> 
> > AFACT, currently we have some examples in the Elisp manual and very
> > few examples in docstrings.
> > It might be a good idea to encourage the addition of examples either in
> > docstrings or in the Elisp manual (or both).
> 
> Personally, I don't like docstring to be too verbose. Usually, when a
> function is documented with both docstrings and a manual, I prefer to
> put the examples in the manual.

I agree: the examples should be mostly in the manual.  Doc strings
should only have examples if it is otherwise very hard to explain
something.

Re: Some ideas with Emacs

[Michael Albinus]

Eli Zaretskii <eliz@gnu.org> writes:

>> > AFACT, currently we have some examples in the Elisp manual and very
>> > few examples in docstrings.
>> > It might be a good idea to encourage the addition of examples either in
>> > docstrings or in the Elisp manual (or both).
>>
>> Personally, I don't like docstring to be too verbose. Usually, when a
>> function is documented with both docstrings and a manual, I prefer to
>> put the examples in the manual.
>
> I agree: the examples should be mostly in the manual.  Doc strings
> should only have examples if it is otherwise very hard to explain
> something.

Shall we say something like this in "(elisp) Documentation Tips"?

Best regards, Michael.

Re: Some ideas with Emacs

[Eli Zaretskii]

> From: Michael Albinus <michael.albinus@gmx.de>
> Cc: monnier@iro.umontreal.ca,  stefan@marxist.se,  c4droid@foxmail.com,
>   emacs-devel@gnu.org
> Date: Fri, 29 Nov 2019 21:09:18 +0100
> 
> >> Personally, I don't like docstring to be too verbose. Usually, when a
> >> function is documented with both docstrings and a manual, I prefer to
> >> put the examples in the manual.
> >
> > I agree: the examples should be mostly in the manual.  Doc strings
> > should only have examples if it is otherwise very hard to explain
> > something.
> 
> Shall we say something like this in "(elisp) Documentation Tips"?

Not sure I understand what would you like to say there.

Re: Some ideas with Emacs

[Michael Albinus]

Eli Zaretskii <eliz@gnu.org> writes:

>> >> Personally, I don't like docstring to be too verbose. Usually, when a
>> >> function is documented with both docstrings and a manual, I prefer to
>> >> put the examples in the manual.
>> >
>> > I agree: the examples should be mostly in the manual.  Doc strings
>> > should only have examples if it is otherwise very hard to explain
>> > something.
>>
>> Shall we say something like this in "(elisp) Documentation Tips"?
>
> Not sure I understand what would you like to say there.

If a function is too complex to explain it in the docstring on, say one
page of ~24 lines, one shall document it more verbose in the
manual. Examples, if not necessary for understanding the docstring,
shall be shown in the manual. In such cases, there shall be a link to
the manual in the docstring.

If a function requires an exhaustive docstring, it could be an option
to break it into several functions.

Maybe all of this is too restrictive. But you see the intention.

Best regards, Michael.

Re: Some ideas with Emacs

[Eli Zaretskii]

> From: Michael Albinus <michael.albinus@gmx.de>
> Cc: monnier@iro.umontreal.ca,  stefan@marxist.se,  c4droid@foxmail.com,
>   emacs-devel@gnu.org
> Date: Fri, 29 Nov 2019 21:25:48 +0100
> 
> If a function is too complex to explain it in the docstring on, say one
> page of ~24 lines, one shall document it more verbose in the
> manual. Examples, if not necessary for understanding the docstring,
> shall be shown in the manual. In such cases, there shall be a link to
> the manual in the docstring.
> 
> If a function requires an exhaustive docstring, it could be an option
> to break it into several functions.
> 
> Maybe all of this is too restrictive. But you see the intention.

I don't think I'd mind, provided that it's worded as guidelines, not
as rigid rules.

Re: Some ideas with Emacs

[Emanuel Berg via Emacs development discussions.]

Michael Albinus wrote:

> If a function is too complex to explain it in
> the docstring on, say one page of ~24 lines,
> one shall document it more verbose in the
> manual. Examples, if not necessary for
> understanding the docstring, shall be shown
> in the manual. In such cases, there shall be
> a link to the manual in the docstring.

The more links to the manual, the better!

I don't think I've seen a single such link BTW,
but maybe I didn't look close enough. How do
you even include such a link when writing
a docstring?

> If a function requires an exhaustive
> docstring, it could be an option to break it
> into several functions.

Absolutely, bare that in mind.

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Some ideas with Emacs

[Eduardo Ochs]

[-- Attachment #1: Type: text/plain, Size: 380 bytes --]

On Sun, 1 Dec 2019 at 03:27, Emanuel Berg via Emacs development
discussions. <emacs-devel@gnu.org> wrote:

> I don't think I've seen a single such link BTW,
> but maybe I didn't look close enough. How do
> you even include such a link when writing
> a docstring?
>

Like this:
  (info "(elisp)Functions for Key Lookup")

Cheers =) =) =),
  Eduardo Ochs
  http://angg.twu.net/#eev

[-- Attachment #2: Type: text/html, Size: 792 bytes --]

Re: Some ideas with Emacs

[Michael Albinus]

Emanuel Berg via "Emacs development discussions." <emacs-devel@gnu.org>
writes:

> Michael Albinus wrote:
>
>> If a function is too complex to explain it in
>> the docstring on, say one page of ~24 lines,
>> one shall document it more verbose in the
>> manual. Examples, if not necessary for
>> understanding the docstring, shall be shown
>> in the manual. In such cases, there shall be
>> a link to the manual in the docstring.
>
> The more links to the manual, the better!
>
> I don't think I've seen a single such link BTW,
> but maybe I didn't look close enough. How do
> you even include such a link when writing
> a docstring?

C-h v tramp-methods

See at the end of the docstring, the "Notes:" part.

The docstring is much too long, according to my own rules. It is a good
example for moving part of it into the manual.

Best regards, Michael.

Re: Some ideas with Emacs

[Emanuel Berg via Emacs development discussions.]

Eli Zaretskii wrote:

> I agree: the examples should be mostly in the
> manual. Doc strings should only have examples
> if it is otherwise very hard to
> explain something.

Or when there is a very interesting example one
would never think of without seeing it.

There are good examples and examples that don't
really bring anything.

We want the good examples :)

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Some ideas with Emacs

[Clément Pit-Claudel]

On 2019-11-29 13:58, Michael Albinus wrote:
> Personally, I don't like docstring to be too verbose. Usually, when a
> function is documented with both docstrings and a manual, I prefer to
> put the examples in the manual.

I very seldom look at the ELisp manual, mostly because I don't think of it; one thing that would be great would be if there were links to the manual from the docstrings for functions that are covered in both.

Re: Some ideas with Emacs

[João Távora]

Clément Pit-Claudel <cpitclaudel@gmail.com> writes:

> On 2019-11-29 13:58, Michael Albinus wrote:
>> Personally, I don't like docstring to be too verbose. Usually, when a
>> function is documented with both docstrings and a manual, I prefer to
>> put the examples in the manual.
>
> I very seldom look at the ELisp manual, mostly because I don't think
> of it; one thing that would be great would be if there were links to
> the manual from the docstrings for functions that are covered in both.

Agree.  There are some already.  But many many more would be needed

Though wouldn't that unnecessarily spam the docstrings?  Perhaps we
could automatically mark a .el file as documented in a specific node of
the manual and make that node automatically be referenced as "read
more about this in node..."  in the docstring.

João

Re: Some ideas with Emacs

[Emanuel Berg via Emacs development discussions.]

J Távora wrote:

>> I very seldom look at the ELisp manual,
>> mostly because I don't think of it; one
>> thing that would be great would be if there
>> were links to the manual from the docstrings
>> for functions that are covered in both.
>
> Agree. There are some already. But many many
> more would be needed

Can't this be automated?

One can even have an option,
help-dont-show-manual-links if anyone gets
distracted by them :)

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Some ideas with Emacs

[Eli Zaretskii]

> Date: Sun, 01 Dec 2019 07:48:50 +0100
> From: Emanuel Berg via "Emacs development discussions." <emacs-devel@gnu.org>
> 
> Can't this be automated?

It already is: see "C-h S".

Re: Some ideas with Emacs

[Yuan Fu]

> I very seldom look at the ELisp manual, mostly because I don't think of it; one thing that would be great would be if there were links to the manual from the docstrings for functions that are covered in both.

I use helpful.el as it provides many extended features beyond help.el, and the link to the relevant manual node is one of the features. 

Yuan

Re: Some ideas with Emacs

[Stefan Kangas]

Yuan Fu <casouri@gmail.com> writes:

> > I very seldom look at the ELisp manual, mostly because I don't
> > think of it; one thing that would be great would be if there were
> > links to the manual from the docstrings for functions that are
> > covered in both.
>
> I use helpful.el as it provides many extended features beyond
> help.el, and the link to the relevant manual node is one of the
> features.

I agree that this feature would be useful.  Maybe we could try
convincing the author of helpful.el (assuming there is only one) to
contribute the relevant code back to Emacs proper?

See also this bug which asks for this feature:
https://debbugs.gnu.org/cgi/bugreport.cgi?bug=36767

Best regards,
Stefan Kangas

Re: Some ideas with Emacs

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Sat, 30 Nov 2019 05:00:12 +0100
> Cc: Clément Pit-Claudel <cpitclaudel@gmail.com>,
>  Emacs developers <emacs-devel@gnu.org>,
>  Michael Albinus <michael.albinus@gmx.de>,
>  Stefan Monnier <monnier@iro.umontreal.ca>, Eli Zaretskii <eliz@gnu.org>,
>  Anonymous <c4droid@foxmail.com>
> 
> See also this bug which asks for this feature:
> https://debbugs.gnu.org/cgi/bugreport.cgi?bug=36767

Is someone working on providing the features requested there?

Re: Some ideas with Emacs

[Eli Zaretskii]

> Cc: Eli Zaretskii <eliz@gnu.org>, Stefan Kangas <stefan@marxist.se>,
>  Anonymous <c4droid@foxmail.com>, Emacs developers <emacs-devel@gnu.org>
> From: Clément Pit-Claudel <cpitclaudel@gmail.com>
> Date: Fri, 29 Nov 2019 16:42:28 -0500
> 
> would be great would be if there were links to the manual from the docstrings for functions that are covered in both.

Almost all of them are, so it would be a significant bloat of the
Emacs's memory footprint for very little gain.  I suggest that you
instead teach yourself to use "C-h S" every time you wonder whether a
function or variable is described in the manual(s): this command
sounds like exactly what you'd want.  (If you already use it, I guess
I don't understand what would you gain by having the information in
the doc string.)

Re: Some ideas with Emacs

[Emanuel Berg via Emacs development discussions.]

Eli Zaretskii wrote:

>> would be great would be if there were links
>> to the manual from the docstrings for
>> functions that are covered in both.
>
> Almost all of them are, so it would be
> a significant bloat of the Emacs's memory
> footprint for very little gain.

Links would be a bloat?

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Some ideas with Emacs

[Eli Zaretskii]

> Date: Sun, 01 Dec 2019 07:51:20 +0100
> From: Emanuel Berg via "Emacs development discussions." <emacs-devel@gnu.org>
> 
> Eli Zaretskii wrote:
> 
> >> would be great would be if there were links
> >> to the manual from the docstrings for
> >> functions that are covered in both.
> >
> > Almost all of them are, so it would be
> > a significant bloat of the Emacs's memory
> > footprint for very little gain.
> 
> Links would be a bloat?

Each link is what, about 50 characters?  In the modest-size Emacs
session where I'm typing this, I have more than 12000 functions
defined.  Multiply that, and you will see how much the image will grow
in size.

It might not be much, but it isn't zero, either.

Re: Some ideas with Emacs

[Emanuel Berg via Emacs development discussions.]

Eli Zaretskii wrote:

>> Links would be a bloat?
>
> Each link is what, about 50 characters?
> In the modest-size Emacs session where I'm
> typing this, I have more than 12000 functions
> defined. Multiply that, and you will see how
> much the image will grow in size.
>
> It might not be much, but it isn't
> zero, either.

OK, now I start to understand why you don't
want long docstrings!

I never thought about how mere text could
bloat software!

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Some ideas with Emacs

[Michael Welsh Duggan]

Eli Zaretskii <eliz@gnu.org> writes:

>> Cc: Eli Zaretskii <eliz@gnu.org>, Stefan Kangas <stefan@marxist.se>,
>>  Anonymous <c4droid@foxmail.com>, Emacs developers <emacs-devel@gnu.org>
>> From: Clément Pit-Claudel <cpitclaudel@gmail.com>
>> Date: Fri, 29 Nov 2019 16:42:28 -0500
>> 
>> would be great would be if there were links to the manual from the
>> docstrings for functions that are covered in both.
>
> Almost all of them are, so it would be a significant bloat of the
> Emacs's memory footprint for very little gain.  I suggest that you
> instead teach yourself to use "C-h S" every time you wonder whether a
> function or variable is described in the manual(s): this command
> sounds like exactly what you'd want.  (If you already use it, I guess
> I don't understand what would you gain by having the information in
> the doc string.)

Although not trivial to write, this might be able to be auto-generated
to some extent.  If the function being looked up is an internal function
or the file in which the function is implemented is in the emacs
installed lisp files location (usually
$prefix/share/emacs/$VERSION/lisp), then we could look up the function
in them emacs-lisp manual and, if found, we could add a link to that
entry.  This could be implemented in the
`help-fns-describe-function-functions' hook.  The manual look-up would
be a hacked up version of `Info-index` which requires an exact match.
Something similar would be done for variable look-up (in
`help-fns-describe-variable-functions').

I'm not in a position where I could write this myself, but I thought I'd
throw the idea out there in case someone else is interested in writing
such a thing.

-- 
Michael Welsh Duggan
(md5i@md5i.com)

Re: Some ideas with Emacs

[Eli Zaretskii]

> From: Michael Welsh Duggan <mwd@md5i.com>
> Date: Sun, 01 Dec 2019 14:44:48 -0500
> 
> > Almost all of them are, so it would be a significant bloat of the
> > Emacs's memory footprint for very little gain.  I suggest that you
> > instead teach yourself to use "C-h S" every time you wonder whether a
> > function or variable is described in the manual(s): this command
> > sounds like exactly what you'd want.  (If you already use it, I guess
> > I don't understand what would you gain by having the information in
> > the doc string.)
> 
> Although not trivial to write, this might be able to be auto-generated
> to some extent.  If the function being looked up is an internal function
> or the file in which the function is implemented is in the emacs
> installed lisp files location (usually
> $prefix/share/emacs/$VERSION/lisp), then we could look up the function
> in them emacs-lisp manual and, if found, we could add a link to that
> entry.  This could be implemented in the
> `help-fns-describe-function-functions' hook.  The manual look-up would
> be a hacked up version of `Info-index` which requires an exact match.
> Something similar would be done for variable look-up (in
> `help-fns-describe-variable-functions').

Isn't that what "C-h S" already does?

Re: Some ideas with Emacs

[Emanuel Berg via Emacs development discussions.]

Eli Zaretskii wrote:

> Isn't that what "C-h S" already does?

Yes, but one get disencouraged from doing that
since there isn't always a hit. I just now went
thru my *Help* history and found the following
items:

gnus-group-group-name
gnus-group-select-group
gnus-newsgroup-savable-name
gnus-summary-newsgroup-prefix
gnus-summary-open-group-with-article
Man-notify-method
nnheader-replace-chars-in-string
sort-lines

of them, only `sort-lines' were in the manual!

If there is a button, one would immediately
see, "oh, there's more".

Also, to TAB to a button and hit RET is more
comfortable than to place point at the symbol
and then do `C-h S'.

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Some ideas with Emacs

[Eli Zaretskii]

> Date: Sun, 01 Dec 2019 22:35:51 +0100
> From: Emanuel Berg via "Emacs development discussions." <emacs-devel@gnu.org>
> 
> gnus-group-group-name
> gnus-group-select-group
> gnus-newsgroup-savable-name
> gnus-summary-newsgroup-prefix
> gnus-summary-open-group-with-article
> Man-notify-method
> nnheader-replace-chars-in-string
> sort-lines
> 
> of them, only `sort-lines' were in the manual!
> 
> If there is a button, one would immediately
> see, "oh, there's more".

Doesn't "C-h S" give you the same feedback?

Re: Some ideas with Emacs

[Emanuel Berg via Emacs development discussions.]

Eli Zaretskii wrote:

>> If there is a button, one would immediately
>> see, "oh, there's more".
>
> Doesn't "C-h S" give you the same feedback?

A button is a faster, more intuitive and more
exact interface IMO but in terms of feedback
the way I envision it that'd be identical to
`C-h S', yes.

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Some ideas with Emacs

[Yuan Fu]

> 
>>> If there is a button, one would immediately
>>> see, "oh, there's more".
>> 
>> Doesn't "C-h S" give you the same feedback?
> 
> A button is a faster, more intuitive and more
> exact interface IMO but in terms of feedback
> the way I envision it that'd be identical to
> `C-h S', yes.

Many people are not aware of C-h S, it would be nice to include such a button in the output of C-h f/v (so they will know “oh, there’s more”). It’s trivial to implement, too.

Yuan

Re: Some ideas with Emacs

[Emanuel Berg via Emacs development discussions.]

Yuan Fu wrote:

>>>> If there is a button, one would
>>>> immediately see, "oh, there's more".
>>>
>>> Doesn't "C-h S" give you the same feedback?
>>
>> A button is a faster, more intuitive and
>> more exact interface IMO but in terms of
>> feedback the way I envision it that'd be
>> identical to `C-h S', yes.
>
> Many people are not aware of C-h S, it would
> be nice to include such a button in the
> output of C-h f/v (so they will know “oh,
> there’s more”). It’s trivial to
> implement, too.

"Oh, that's right!"

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Some ideas with Emacs

[Michael Albinus]

Eli Zaretskii <eliz@gnu.org> writes:

>> gnus-group-group-name
>> gnus-group-select-group
>> gnus-newsgroup-savable-name
>> gnus-summary-newsgroup-prefix
>> gnus-summary-open-group-with-article
>> Man-notify-method
>> nnheader-replace-chars-in-string
>> sort-lines
>>
>> of them, only `sort-lines' were in the manual!
>>
>> If there is a button, one would immediately
>> see, "oh, there's more".
>
> Doesn't "C-h S" give you the same feedback?

"C-h S" (`info-lookup-symbol') is good for symbols "as found in the
relevant manual". This is OK for symbols which belong to the major mode
of the visited file.

Reading info-look.el it is not clear to me, how I could configure it to
show symbols from the Gnus or Tramp manual, for example.

Best regards, Michael.

Re: Some ideas with Emacs

[Michael Welsh Duggan]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Michael Welsh Duggan <mwd@md5i.com>
>> Date: Sun, 01 Dec 2019 14:44:48 -0500
>> 
>> > Almost all of them are, so it would be a significant bloat of the
>> > Emacs's memory footprint for very little gain.  I suggest that you
>> > instead teach yourself to use "C-h S" every time you wonder whether a
>> > function or variable is described in the manual(s): this command
>> > sounds like exactly what you'd want.  (If you already use it, I guess
>> > I don't understand what would you gain by having the information in
>> > the doc string.)
>> 
>> Although not trivial to write, this might be able to be auto-generated
>> to some extent.  If the function being looked up is an internal function
>> or the file in which the function is implemented is in the emacs
>> installed lisp files location (usually
>> $prefix/share/emacs/$VERSION/lisp), then we could look up the function
>> in them emacs-lisp manual and, if found, we could add a link to that
>> entry.  This could be implemented in the
>> `help-fns-describe-function-functions' hook.  The manual look-up would
>> be a hacked up version of `Info-index` which requires an exact match.
>> Something similar would be done for variable look-up (in
>> `help-fns-describe-variable-functions').
>
> Isn't that what "C-h S" already does?

It appears to, indeed.  All that is needed, then, is to integrate this
as a hyperlink into the C-h [f,v] buffers, without asking initially what
type of symbol you're looking for.

-- 
Michael Welsh Duggan
(md5i@md5i.com)

Re: Some ideas with Emacs

[Emanuel Berg via Emacs development discussions.]

Michael Welsh Duggan wrote:

> It appears to, indeed. All that is needed,
> then, is to integrate this as a hyperlink
> into the C-h [f,v] buffers [...]

That'd be great!

And the `C-h k' buffers! Well, perhaps that
amounts to `C-h f'...

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Some ideas with Emacs

[Emanuel Berg via Emacs development discussions.]

Clément Pit-Claudel wrote:

> I very seldom look at the ELisp manual,
> mostly because I don't think of it; one thing
> that would be great would be if there were
> links to the manual from the docstrings for
> functions that are covered in both.

Agree 100%

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Some ideas with Emacs

[Emanuel Berg via Emacs development discussions.]

Michael Albinus wrote:

> Personally, I don't like docstring to be too
> verbose. [...]

But if one puts the concise stuff topmost?
Then you can read that, and go on typing in
a heartbeat?

And those who like verbose docstrings can keep
on reading :)

Docstrings is where I look all the time.
There are rules what should be mentioned and in
what order. Those rules makes total sense.
Stick to them and have it concise first thing.

But after that, if anyone wants to write
several screens of quality documentation
exploring every aspect of the topic, do it :)

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Some ideas with Emacs

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > It might be a good idea to encourage the addition of examples either in
  > docstrings or in the Elisp manual (or both).

The general intention is to make doc strings somewhat terse, and speak
at greater length in the manual.  So the place for these examples
is the manual, not the doc strings.

-- 
Dr Richard Stallman
Founder, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Some ideas with Emacs

[Emanuel Berg via Emacs development discussions.]

Richard Stallman wrote:

>> It might be a good idea to encourage the
>> addition of examples either in docstrings or
>> in the Elisp manual (or both).
>
> The general intention is to make doc strings
> somewhat terse, and speak at greater length
> in the manual. So the place for these
> examples is the manual, not the doc strings.

But the docstrings are much more interactive
and have a faster and more natural
work-flow access!

As long as the basic info is topmost and in the
intuitive order according to the rules (with
arguments etc) why can't one have a second (and
third etc) paragraph with more elaborate info,
and yes, examples?

BTW as you know there are already examples in
many docstrings, even Elisp - do like this, not
like this.

Great stuff IMO!

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Some ideas with Emacs

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > I think if we want to have an ELisp tutorial, it should be a separate
  > manual.

GNU manuals normally try to be useful for both tutorial and reference.
Each chapter, each section, should be written so that you can read
it straight through and learn its topic.

We have a separate Intro to Emacs Lisp, so the chapters of the
reference manual that describe the basic facilities of Lisp don't need
to try hard to serve also as an introduction.  (For those topics it
is difficult to do both with the same text.)

However, most parts of the Emacs Lisp Reference Manual describe
editing facilities, and we do try to make them usable as introductions.
They have examples for that -- and we can add more when that is useful.

-- 
Dr Richard Stallman
Founder, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Some ideas with Emacs

[Stefan Monnier]

>> Second, in developing the Emacs plugins, create a virtual
>> environment, like Python virtualenv, so that we can test the plugin
>> in the virtual environment so that we do not need to affect the
>> configuration outside the virtual environment. That's can implement
>> plugin development environment and configuration isolation.
> I think what you would do is something like "emacs -Q -l myenv.el" and
> then set up the load-path, requires, and whatever else you need in
> myenv.el.

Indeed, currently the only way to do that is by using a separate
Emacs session.  Cask is a tool to automate this.  For some use cases
this is exactly what we need (e.g. testing a package on various
versions of Emacs), but in other use cases it's a pain to have to use
two separate Emacs sessions.

There's definitely room for improvement in this arena.

Juanma adds:
> With reminds me...
> Did someone hear (or attend to) Perry E. Metzger's talk in this years'
> EmacsConf?
> https://media.emacsconf.org/2019/26.html
> And if so, does anyone have any opinion about it?

I presume you're talking about the part where he discusses the future of
Emacs's extension language.  I do have some opinion about that, yes ;-)


        Stefan

Re: Some ideas with Emacs

[Robert Pluim]

>>>>> On Fri, 29 Nov 2019 10:43:19 -0500, Stefan Monnier <monnier@iro.umontreal.ca> said:
    Stefan> Juanma adds:
    >> With reminds me...
    >> Did someone hear (or attend to) Perry E. Metzger's talk in this years'
    >> EmacsConf?
    >> https://media.emacsconf.org/2019/26.html
    >> And if so, does anyone have any opinion about it?

    Stefan> I presume you're talking about the part where he discusses the future of
    Stefan> Emacs's extension language.  I do have some opinion about that, yes ;-)

Emacs already has two extension languages, three if you count
'C'. What benefits would another one offer?

Robert

Re: Some ideas with Emacs

[Emanuel Berg via Emacs development discussions.]

Stefan Kangas wrote:

> I think this is a fine idea that would make
> the manual more useful. But the elisp manual
> is also printed on paper, and is from what
> I understand already very long. Does it make
> sense to include examples in the info
> manual only?

Better start with the production of the actual
material, after that you can figure out where
it fits, be it in a file that already exists or
make it an all-new standalone document.

> We very much need to get more people hacking
> on Emacs.

... are you sure?

Isn't it better they go on to be doctors,
carpenters, dentists, mechanics etc?

Ignorance is bliss, as paleo-Cypher rightly put
it (?) [1]


[1] https://sfy.ru/transcript/matrix_ts

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Some ideas with Emacs

[VanL]

Emanuel Berg writes:

>> We very much need to get more people hacking
>> on Emacs.
>
> ... are you sure?
>
> Isn't it better they go on to be doctors,
> carpenters, dentists, mechanics etc?

What are the kinds of part-time jobs for
those people to do and put a family
sized pizza on the table for family?

-- 
LoL,
  əə0@ 一 二 三 言 語 𝔖
  'VLIW architecture?'
  G4 White 78 Black 79

Re: Some ideas with Emacs

[Stefan Monnier]

>> We very much need to get more people hacking on Emacs.
>
> ... are you sure?
>
> Isn't it better they go on to be doctors, carpenters, dentists, mechanics etc?

What he meant is that we need to get more doctors, carpenters, dentists,
mechanics etc hacking on Emacs,


        Stefan "who belongs to the 'doctor' category"

Re: Some ideas with Emacs

[Emanuel Berg via Emacs development discussions.]

Stefan Monnier wrote:

>>> We very much need to get more people
>>> hacking on Emacs.
>>
>> ... are you sure?
>>
>> Isn't it better they go on to be doctors,
>> carpenters, dentists, mechanics etc?
>
> What he meant is that we need to get more
> doctors, carpenters, dentists, mechanics etc
> hacking on Emacs,
>
>         Stefan "who belongs to the 'doctor'
>         category"

:) Yeah, that'd be something :)

In Sweden there is a joke, saying many young
men's careers have been spoiled by fishing
and bikes. But what do you need a career for if
you have fishing and bikes?

On may add Emacs to that, easily.

          Manny "who belongs to the bike and
          Emacs category. Not sure if he ever
          would have had a career tho"

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Some ideas with Emacs

[Ag Ibragimov]

Ooohweee, I've lost myself in the weeds of this discussion thread. It seems writing a book about Emacs Lisp is an arduous task (no shit), writing a comprehensive manual is not easy either.

So I thought: what if we start a repository, make a pitch through social platforms, get people interested, and start collecting various elisp recipes. Then after a while, maybe we could form a curated list. After a few, maybe several months, we gather enough material to make a book out of that?

"Emacs Lisp Cookbook" or something?

Re: Some ideas with Emacs

[Marcin Borkowski]

On 2019-12-03, at 07:07, Ag Ibragimov <agzam.ibragimov@gmail.com> wrote:

> Ooohweee, I've lost myself in the weeds of this discussion thread. It seems writing a book about Emacs Lisp is an arduous task (no shit), writing a comprehensive manual is not easy either.
>
> So I thought: what if we start a repository, make a pitch through social platforms, get people interested, and start collecting various elisp recipes. Then after a while, maybe we could form a curated list. After a few, maybe several months, we gather enough material to make a book out of that?
>
> "Emacs Lisp Cookbook" or something?

No.

You may indeed prepare a "cookbook", or a wiki this way - but not
a _book_.  A "book" (as opposed to a wiki, a _cookbook_ or a manual) is
something that _tells a story_.

Best,

--
Marcin Borkowski
http://mbork.pl

Re: Some ideas with Emacs

[Juanma Barranquero]

[-- Attachment #1: Type: text/plain, Size: 289 bytes --]

On Fri, Dec 6, 2019 at 8:07 PM Marcin Borkowski <mbork@mbork.pl> wrote:

> A "book" (as opposed to a wiki, a _cookbook_ or a manual) is
> something that _tells a story_.

I've always loved the ending of this one:

https://www.amazon.com/Million-Random-Digits-Normal-Deviates/dp/0833030477

[-- Attachment #2: Type: text/html, Size: 532 bytes --]

Re: Some ideas with Emacs

[Marcin Borkowski]

On 2019-12-06, at 20:18, Juanma Barranquero <lekktu@gmail.com> wrote:

> On Fri, Dec 6, 2019 at 8:07 PM Marcin Borkowski <mbork@mbork.pl> wrote:
>
>> A "book" (as opposed to a wiki, a _cookbook_ or a manual) is
>> something that _tells a story_.
>
> I've always loved the ending of this one:
>
> https://www.amazon.com/Million-Random-Digits-Normal-Deviates/dp/0833030477

Way too many figures for my taste.

-- 
Marcin Borkowski
http://mbork.pl

Re: Some ideas with Emacs

[Stefan Monnier]

>> A "book" (as opposed to a wiki, a _cookbook_ or a manual) is
>> something that _tells a story_.
> I've always loved the ending of this one:
> https://www.amazon.com/Million-Random-Digits-Normal-Deviates/dp/0833030477

Predictably unpredictable,


        Stefan

Re: Some ideas with Emacs

[Juanma Barranquero]

[-- Attachment #1: Type: text/plain, Size: 188 bytes --]

On Fri, Dec 6, 2019 at 10:22 PM Stefan Monnier <monnier@iro.umontreal.ca>
wrote:

> Predictably unpredictable,

For sure. *Nothing* that came before could've prepared you for that ending.

[-- Attachment #2: Type: text/html, Size: 311 bytes --]

Re: Some ideas with Emacs

[Ag Ibragimov]

On Fri 06 Dec 2019 at 10:30, Marcin Borkowski <mbork@mbork.pl> wrote:

> On 2019-12-03, at 07:07, Ag Ibragimov <agzam.ibragimov@gmail.com> wrote:
>
>> Ooohweee, I've lost myself in the weeds of this discussion thread. It seems writing a book about Emacs Lisp is an arduous task (no shit), writing a comprehensive manual is not easy either.
>>
>> So I thought: what if we start a repository, make a pitch through social platforms, get people interested, and start collecting various elisp recipes. Then after a while, maybe we could form a curated list. After a few, maybe several months, we gather enough material to make a book out of that?
>>
>> "Emacs Lisp Cookbook" or something?
>
> No.
>
> You may indeed prepare a "cookbook", or a wiki this way - but not
> a _book_.  A "book" (as opposed to a wiki, a _cookbook_ or a manual) is
> something that _tells a story_.
>
> Best,

I agree with that. However, I think "Elisp recipes" or "Elisp cookbook" is exactly what we need and what's missing.
You see, Emacs Lisp usually is not learned traditional way, you don't sit down with a book that slowly explains concepts from the elementary to more advanced topics. Also people don't do emacs-lisp "katas" or "koans". Usually one gets into emacs-lisp when the need arises for solving a problem. It's not that difficult to find help these days, people are always happy to help you, we have r/emacs, mailing lists, emacs.stackexchange, various Gitter, Slack and IRC channels, etc.
But sometimes you don't even know you had a problem, until someone shows you a solution to it. I think that kind of book, collective community effort would be awesome to have.

But your point about a book that tells a story is also very valid. It would be absolutely amazing to have a book written by a single person or small group of co-authors, something titled like "Joy of Emacs" ("Joy of GNU/Emacs" if you're so pedantic) where it also describes philosophy of the language, historical context, contemplates about the future of the language, etc.

RE: Some ideas with Emacs

[Drew Adams]

> I agree with that. However, I think "Elisp recipes" or "Elisp cookbook"
> is exactly what we need and what's missing.

There's this EmacsWiki page, which anyone can contribute to or edit:

https://www.emacswiki.org/emacs/ElispCookbook

I make no claims about how useful the content might be.  The point is that there is such a place, which anyone can use and improve.

Similarly, but more generally, there is this series of pages:

https://www.emacswiki.org/emacs/CategoryCode

Re: Some ideas with Emacs

[Marcin Borkowski]

On 2019-12-07, at 03:13, Ag Ibragimov <agzam.ibragimov@gmail.com> wrote:

> On Fri 06 Dec 2019 at 10:30, Marcin Borkowski <mbork@mbork.pl> wrote:
>
>> On 2019-12-03, at 07:07, Ag Ibragimov <agzam.ibragimov@gmail.com> wrote:
>>
>>> Ooohweee, I've lost myself in the weeds of this discussion thread. It seems writing a book about Emacs Lisp is an arduous task (no shit), writing a comprehensive manual is not easy either.
>>>
>>> So I thought: what if we start a repository, make a pitch through social platforms, get people interested, and start collecting various elisp recipes. Then after a while, maybe we could form a curated list. After a few, maybe several months, we gather enough material to make a book out of that?
>>>
>>> "Emacs Lisp Cookbook" or something?
>>
>> No.
>>
>> You may indeed prepare a "cookbook", or a wiki this way - but not
>> a _book_.  A "book" (as opposed to a wiki, a _cookbook_ or a manual) is
>> something that _tells a story_.
>>
>> Best,
>
> I agree with that. However, I think "Elisp recipes" or "Elisp cookbook" is exactly what we need and what's missing.
> You see, Emacs Lisp usually is not learned traditional way, you don't sit down with a book that slowly explains concepts from the elementary to more advanced topics. Also people don't do emacs-lisp "katas" or "koans". Usually one gets into emacs-lisp when the need arises for solving a problem. It's not that difficult to find help these days, people are always happy to help you, we have r/emacs, mailing lists, emacs.stackexchange, various Gitter, Slack and IRC channels, etc.
> But sometimes you don't even know you had a problem, until someone shows you a solution to it. I think that kind of book, collective community effort would be awesome to have.

I think that I could agree with that, though I personally like a more
structured exposition.

> But your point about a book that tells a story is also very valid. It would be absolutely amazing to have a book written by a single person or small group of co-authors, something titled like "Joy of Emacs" ("Joy of GNU/Emacs" if you're so pedantic) where it also describes philosophy of the language, historical context, contemplates about the future of the language, etc.

Now that you wrote that, I think this is really an amazing idea.  I am
a bit afraid I do not know enough about Emacs - and my plan is a bit
more humble anyway - but thanks for inspiration.

Best,

-- 
Marcin Borkowski
http://mbork.pl

Re: Some ideas with Emacs

[VanL]

> I think that I could agree with that, though I personally like a more
> structured exposition.
>
>> But your point about a book that tells a story is also very
>> valid. It would be absolutely amazing to have a book written by a
>> single person or small group of co-authors, something titled like
>> "Joy of Emacs" ("Joy of GNU/Emacs" if you're so pedantic) where it
>> also describes philosophy of the language, historical context,
>> contemplates about the future of the language, etc.
>
> Now that you wrote that, I think this is really an amazing idea.  I am
> a bit afraid I do not know enough about Emacs - and my plan is a bit
> more humble anyway - but thanks for inspiration.

Over on the GameInformer channel, in the episode celebrating the 25th
year of the Sony Playstation, at the eight minute mark, the problem
there is how to write a history of the Sony Playstation with draft notes
on interviews collected numbering more than 60-pages.  There, they say
Microsoft Word is woefully inadequate to the task of working a document
60-pages and more.  The discussants are college educated with the kind
of unconventional smart to stack discount coupons for a greater compound
discount for a very, very big 8k T.V.  I'd like to think the new
elispintro will help them at their work on that Sony Playstation hitory
project.  The initial GameInformer website was constructed by reading a
book on HTML.