Eev-wconfig.el etc etc, or: "Exercise: Learn Org!"

Eev-wconfig.el etc etc, or: "Exercise: Learn Org!"

[Eduardo Ochs]

Hi all,

I made a video that is mainly for people who are new to Emacs and who
are using M$ Windows, and it ends with an exercise that is roughly
this: "...now download a .zip file with Rainer Koenig's videos from
<http://angg.twu.net/eev-wconfig.html#learn-org>, unpack it somewhere,
and use eev to create an index of the video that you've watched, with
pointers to the parts that you will need to re-watch many times"...

The best way to watch the video is to download it and its subtitles by
doing this:

  wget http://angg.twu.net/eev-videos/2022-eev-wconfig.mp4
  wget http://angg.twu.net/eev-videos/2022-eev-wconfig.vtt

and then watch the local copy with a video player. The second best way
to watch it is to access its index, here,

  http://angg.twu.net/.emacs.videos.html#2022eevwconfig

and click on the timestamps of the parts that look interesting to play
the video on Youtube starting from that position.

The page about the video and all the ideas behind it is this one:

  http://angg.twu.net/eev-wconfig.html

All feedback welcome!
  Cheers,
    Eduardo Ochs
    http://angg.twu.net/#eev

Re: Eev-wconfig.el etc etc, or: "Exercise: Learn Org!"

[Ihor Radchenko]

Eduardo Ochs <eduardoochs@gmail.com> writes:

> I made a video that is mainly for people who are new to Emacs and who
> are using M$ Windows, and it ends with an exercise that is roughly
> this: "...now download a .zip file with Rainer Koenig's videos from
> <http://angg.twu.net/eev-wconfig.html#learn-org>, unpack it somewhere,
> and use eev to create an index of the video that you've watched, with
> pointers to the parts that you will need to re-watch many times"...

You are discussing too many things at once in one video.

What is the main point you want to explain in the video? How to
download, watch, and annotate a series of videos? If so, you only talk
about it in the last minutes of the presentation.

Also, do you expect people new to emacs understand all the
(commmand args) staff?

I still fail to understand what is the advantage of eev compared to Org
or Hyperbole (which also provides context-free actionable links).
You argue that Org is a "black box", but your code is also a black box
in a sense that one needs to read the "wconfig" files (AFAIU). How is it
different compared to Org written in Elisp following the usual
documentation conventions described in the Elisp manual?

I recommend recording a much shorted video demonstrating a singe task
you perform using eev. No need to side track explaining Elisp syntax. No
need to show troubleshooting. No need to show things users "are not
supposed to understand". No need to show initial configuration with all
possible caveats.

Best,
Ihor

Re: Eev-wconfig.el etc etc, or: "Exercise: Learn Org!"

[Eduardo Ochs]

Hi Ihor!
Thanks for your questions!

On Fri, 27 May 2022 at 11:30, Ihor Radchenko <yantar92@gmail.com> wrote:
> You are discussing too many things at once in one video.

Yes - that's why I made an index for the video:

  (find-1stclassvideoindex "2022eevwconfig")
  http://angg.twu.net/.emacs.videos.html#2022eevwconfig

> What is the main point you want to explain in the video? How to
> download, watch, and annotate a series of videos? If so, you only talk
> about it in the last minutes of the presentation.

The video has many "main points".

> Also, do you expect people new to emacs understand all the
> (commmand args) staff?

Yes, in my view of "what is Emacs" the first thing that people need to
learn is eval-last-sexp and its more convenient variants. See the page
10 of my slides for the EmacsConf2019:

  http://angg.twu.net/LATEX/2019emacsconf.pdf#page=10

> I still fail to understand what is the advantage of eev compared to Org
> or Hyperbole (which also provides context-free actionable links).

Here are my current hypotheses: 1) my brain is wired in an atypical
way; 2) about 95% of the people find Org "easy" and "fun", and eev
makes no sense to them - and about 5% of the people find Org very
hard, and they find eev much "easier" and "more fun" than Org.

I explained this in the eev-wconfig video, starting from 33:27:

  (find-2022eevwconfigvideo "33:27")
  http://www.youtube.com/watch?v=Rm29XSdGCXw#t=33m27s

That part mentions this other video,

  Title: Org for Non-Users (2021)
  MP4:   http://angg.twu.net/eev-videos/2021-org-for-non-users.mp4
  YT:    http://www.youtube.com/watch?v=Eh5Wz9Vh_XM
  Page:  http://angg.twu.net/2021-org-for-non-users.html
  Comment: On why Org and eev follow opposite principles.
  Date:    2021dec11
  Length:  10:08
  Index:   http://angg.twu.net/.emacs.videos.html#2021orgfornonusers
           (find-1stclassvideoindex "2021orgfornonusers")

and sort of summarizes it. Let me copy here the subtitles of that part
of the eev-wconfig video:

  So: in this video I explained why I have
  always found Org so hard to learn...
  and the thing is that many things in Org
  are implemented in ways that i
  don't understand,
  and practically every time that I try to
  learn more more features of org
  I get stuck, because I start to ask
  questions like:
  hey, how is this implemented?
  And I get stuck trying to trying to
  answer these questions, that are not
  typical user questions...
  and
  I get stuck on that instead of
  simply learning how to use the features
  of Org as a user.
  So: I find
  Org confusing because my brain is wired
  in a weird way...
  and, in the language of black boxes what
  happens
  is that when I try to learn Org...
  I try to learn a new feature, I see lots
  of black boxes,
  I try to open these black boxes, and I
  fail miserably... and I get frustrated and
  exhausted I, do not learn the feature and
  I postpone learning the feature
  to another day, and in the other day I try
  it again, I see other black boxes, I try
  to understand them again, and blah blah,
  rinse and repeat...
  and I also have exactly the same
  relationship with M-x customized, that
  the standard way in Emacs to configure
  certain things
  and to customize certain things.
  Let me show how customize works
  We can either type M-x customize or
  run this sexp here, that
  simulates what happens when we type
  M-x customize.
  Customize creates a temporary buffer
  like this one...
  it has this mysterious field here, it
  has parts that are not editable - for
  example, if I type a letter here - oops
  if I type a letter here
  it says "you can't edit this part of the
  Custom buffer"... it has buttons,
  it has different fonts, different colors,
  it has links, and so on...
  and if I follow these links in
  the right way I
  can get to places like this one
  which is a
  sub menu with sub options,
  I can
  get to a place like
  this one
  that
  offers many
  things
  that can be configured, each one with an
  explanation...
  I can execute things like this one, that
  opens this page, in which I can customize
  a
  variable...
  and things like this in which I can
  customize a face to change its color, to
  change its font... and so on -
  and for me all these things - all these
  buttons, this rectangle here, in which I
  can
  put text
  all these things are...
  magic - and they are black boxes that I
  find very hard to open.
  And over the years I have experimented
  with several alternatives to
  customize that "use less magic"...
  I've documented some of my attempts in
  this page here,
  and
  this thing that I'm presenting now -
  eev-wconfig.el - this is
  the next step: it uses all the ideas in
  this page,
  and a few other new ideas.


> I recommend recording a much shorted video demonstrating a singe task
> you perform using eev. No need to side track explaining Elisp syntax. No
> need to show troubleshooting. No need to show things users "are not
> supposed to understand". No need to show initial configuration with all
> possible caveats.

There are lots of short demos scattered through the videos... here's
one that has subtitles. If you run this

  # Index: http://angg.twu.net/.emacs.videos.html#2022pict2elua
  # Info:  (find-1stclassvideo-links "2022pict2elua")
  export    S=$HOME/snarf
  mkdir -p $S/http/angg.twu.net/eev-videos/
  cd       $S/http/angg.twu.net/eev-videos/
  wget -nc  http://angg.twu.net/eev-videos/2022-pict2e-lua.mp4
  wget -nc  http://angg.twu.net/eev-videos/2022-pict2e-lua.vtt
  mpv $S/http/angg.twu.net/eev-videos/2022-pict2e-lua.mp4

then you can use the keys [ and ] to make mpv change the playing
speed, and you can watch the full 8-minute video in just one or two
minutes. If you prefer to watch it on Youtube the link is this one:

  http://www.youtube.com/watch?v=hiHsUhGVLGM

> No need to side track explaining Elisp syntax. No
> need to show troubleshooting. No need to show things users "are not
> supposed to understand". No need to show initial configuration with all
> possible caveats.

Can you explain these "no need"s? Except for the red stars and anchors
_all_ the "markup language" of eev consists of explicit sexps...

> You argue that Org is a "black box", but your code is also a black box
> in a sense that one needs to read the "wconfig" files (AFAIU). How is it
> different compared to Org written in Elisp following the usual
> documentation conventions described in the Elisp manual?

Eev-wconfig is only needed for configuring things on Windows. On, say,
Debian, people only need to install google-chrome (obs: it's easy to
use other browsers instead), and do this:

  sudo apt-get install wget xpdf pdftotext mpv

after that all the features will work.

Here are two examples of cases in which I stumbled on black boxes that
I never managed to open properly, one in Org and one in Hyperbole:

  https://lists.gnu.org/archive/html/emacs-orgmode/2021-12/msg00674.html
  https://lists.gnu.org/archive/html/emacs-orgmode/2022-02/threads.html#00098
  https://lists.gnu.org/archive/html/hyperbole-users/2020-09/msg00012.html

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

Re: Eev-wconfig.el etc etc, or: "Exercise: Learn Org!"

[Ihor Radchenko]

Eduardo Ochs <eduardoochs@gmail.com> writes:

> On Fri, 27 May 2022 at 11:30, Ihor Radchenko <yantar92@gmail.com> wrote:
>> You are discussing too many things at once in one video.
>
> Yes - that's why I made an index for the video:
>
>   (find-1stclassvideoindex "2022eevwconfig")
>   http://angg.twu.net/.emacs.videos.html#2022eevwconfig

Honestly, I cannot navigate that index even after watching the whole
video. Before watching, it had no sense whatsoever.

In short, the video is too hard to understand. The available index does
not help.

Imagine that you don't watch the video and look at the below items:

;; (find-2022eevwconfigvideo   "15:50"   "6.1, 6.2, 6.3, 6.4")
;; (find-2022eevwconfigvideo   "16:03"   "these steps can be replaced")
;; (find-2022eevwconfigvideo   "16:12"   "by these two sexps here")
;; (find-2022eevwconfigvideo   "16:15"   "(require 'eev-wconfig)")
;; (find-2022eevwconfigvideo   "16:23"   "(find-wconfig-links)")
;; (find-2022eevwconfigvideo   "16:37"   "use this to configure eev")
;; (find-2022eevwconfigvideo   "16:40"   "on Windows \"without magic\"")
;; (find-2022eevwconfigvideo   "16:52"   "wconfig means \"Windows config\"")
;; (find-2022eevwconfigvideo   "17:02"   "this is the \"main wconfig\"")
;; (find-2022eevwconfigvideo   "17:15"   "five sub-wconfigs")

What is 6.1..6.4??

"these steps can be replaces" has no context

"by these two sexp here" does not make any sense as a standalone TOC
Item.

"on Windows \"without magic\"" is referring to the term you introduce in
the video itself and does not make sense without watching. (Honestly,
after watching, "without magic" feel like there was a lot of magic going
on).

etc...

>> What is the main point you want to explain in the video? How to
>> download, watch, and annotate a series of videos? If so, you only talk
>> about it in the last minutes of the presentation.
>
> The video has many "main points".

Then, it is not a good idea. Videos/books with many main points not
connected by an easy-to-follow general logic are hard to understand.
They are just a "thought salad".

Note that it would not be a so much of a problem if you recorded this
video as future reference to yourself. But it is unacceptable for
general audience. Public presentations often follow more or less fixed
structure:

(credit: Prof. Evan Ma)
1. what is significant? (aka background)
2. what is the trouble? (why what you tell is important)
3. what is your approach? (explaining the new thing you want to introduce)
4. does it work well? (e.g. real-life demo)
5. can it be employed in other systems? (how other people with different systems can use it)

>> Also, do you expect people new to emacs understand all the
>> (commmand args) staff?
>
> Yes, in my view of "what is Emacs" the first thing that people need to
> learn is eval-last-sexp and its more convenient variants. See the page
> 10 of my slides for the EmacsConf2019:
>
>   http://angg.twu.net/LATEX/2019emacsconf.pdf#page=10

Then, your target audience should be the people who are already a bit
familiar to Elisp and you need to state it at the beginning of the
video. Explaining how setq works is not enough to make complete
beginners understand sexps. You should either stop at the beginning and
introduce _all_ the required Elisp concepts or ask people to read Elisp
manual first.

>> I still fail to understand what is the advantage of eev compared to Org
>> or Hyperbole (which also provides context-free actionable links).
>
> Here are my current hypotheses: 1) my brain is wired in an atypical
> way; 2) about 95% of the people find Org "easy" and "fun", and eev
> makes no sense to them - and about 5% of the people find Org very
> hard, and they find eev much "easier" and "more fun" than Org.

This is Org mailing list. I doubt that people here do not find Org
"fun". Yet, you asked feedback to the video. So, I assumed that you
cover us as target audience as well. If not, my feedback may not be too
useful for you. Though I'd say that your presentation is hard to
understand even from general perspective of giving public presentations
(according to my teaching and conference experience).

>> I still fail to understand what is the advantage of eev compared to Org
>> or Hyperbole (which also provides context-free actionable links).

> I explained this in the eev-wconfig video, starting from 33:27:
>
> and sort of summarizes it. Let me copy here the subtitles of that part
> of the eev-wconfig video:
>
>   So: in this video I explained why I have
>   always found Org so hard to learn...
>   and the thing is that many things in Org
>   are implemented in ways that i
>   don't understand,
>   and practically every time that I try to
>   learn more more features of org
>   I get stuck, because I start to ask
>   questions like:
>   hey, how is this implemented?
>   And I get stuck trying to trying to
>   answer these questions, that are not
>   typical user questions...

I still do not see where is the _advantage_ of eev. Is it easier to
understand compared to Org? In what way? How can I understand eev
features?

>> I recommend recording a much shorted video demonstrating a singe task
>> you perform using eev. No need to side track explaining Elisp syntax. No
>> need to show troubleshooting. No need to show things users "are not
>> supposed to understand". No need to show initial configuration with all
>> possible caveats.
>
> There are lots of short demos scattered through the videos... here's
> one that has subtitles. If you run this
>
>   # Index: http://angg.twu.net/.emacs.videos.html#2022pict2elua
>   # Info:  (find-1stclassvideo-links "2022pict2elua")
>   wget -nc  http://angg.twu.net/eev-videos/2022-pict2e-lua.mp4
>   wget -nc  http://angg.twu.net/eev-videos/2022-pict2e-lua.vtt

This video is somewhat better, though it still mixes eev and
demonstrating the library. Is the video describing a eev feature to
support Lua repl? Or is it also a testing library for Lua?

>> No need to side track explaining Elisp syntax. No
>> need to show troubleshooting. No need to show things users "are not
>> supposed to understand". No need to show initial configuration with all
>> possible caveats.
>
> Can you explain these "no need"s? Except for the red stars and anchors
> _all_ the "markup language" of eev consists of explicit sexps...

In short, if the purpose of the video is to introduce eev to new users,
you need to demonstrate (by example) how eev can be used _normally_. By
normally, I mean after you already install it and when everything works
as expected. There is no need to explain extra information that is not
strictly required to understand the video.

What is strictly required depends on the purpose of the video. What
exactly do you want the users to learn from the video? It should be no
more than a handful of concepts.

>> You argue that Org is a "black box", but your code is also a black box
>> in a sense that one needs to read the "wconfig" files (AFAIU). How is it
>> different compared to Org written in Elisp following the usual
>> documentation conventions described in the Elisp manual?
>
> Eev-wconfig is only needed for configuring things on Windows. On, say,
> Debian, people only need to install google-chrome (obs: it's easy to
> use other browsers instead), and do this:
>
>   sudo apt-get install wget xpdf pdftotext mpv
>
> after that all the features will work.

Sure, but it does not challenge my point. How can I understand the eev
internals? Why is it easier compared to Org?

> Here are two examples of cases in which I stumbled on black boxes that
> I never managed to open properly, one in Org and one in Hyperbole:
>
>   https://lists.gnu.org/archive/html/emacs-orgmode/2021-12/msg00674.html
>   https://lists.gnu.org/archive/html/emacs-orgmode/2022-02/threads.html#00098

As I mentioned in that thread, I am not sure what you mean by black box
there. The source code of org-export-dispatch is available to you.

>   https://lists.gnu.org/archive/html/hyperbole-users/2020-09/msg00012.html

Judging from this email, you find eev easier because you understand the
underlying logic. This is of course true, especially since you are the
author :) Also, eev only implements a subset of what Org mode of
Hyperbole does. It also makes things simpler to understand.

If I understand correctly, you expect the end functions to be exposed
directly as text without any intermediate dispatchers. Unfortunately,
larger projects like Org do not have this luxury.

Org has so many features that nobody can easily remember them all.
Hence, some "automatic" behavior is inevitable and one needs to follow
all the intermediate handlers to reach the actual function that does the
work.

You can still understand the inner workings by examining the Elisp code
and making use of Emacs help system (F1-k F1-f F1-v) to jump around
functions and bindings. It is not as easy as in smaller projects, but
not impossible. (That's how I learned Org myself).

Best,
Ihor

Re: Eev-wconfig.el etc etc, or: "Exercise: Learn Org!"

[Eduardo Ochs]

On Sat, 28 May 2022 at 01:52, Ihor Radchenko <yantar92@gmail.com> wrote:
> (...)

Hi Ihor,

I think that you are underestimating how alien eev is for most people.
Let me suppose that what you mean by your comments is this:

  "I've spent N minutes watching this video - for N big - and I feel
   that I've learned very little! What is the best way to learn a lot
   of eev in M minutes, for M very small?"

then the answer is: follow the main tutorial, that is here:

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

Let me just stress some points that are not obvious at all.

  0) You can turn eev-mode on and off with M-x eev-mode. The technical
     details are here:

       http://angg.twu.net/eev-intros/find-eev-intro.html#1
       (find-eev-intro "1. `eev-mode'")

  1) Following a link to a video for which we have a local copy
     usually takes about three seconds. _For me_ this means that I can
     use links to videos as links to _images_. You complained that
     this entry in an index makes no sense:

       (find-2022eevwconfigvideo "15:50" "6.1, 6.2, 6.3, 6.4")

     When I execute it with `M-e' it shows - in just three seconds - a
     page of text with lots of things, and the comment "6.1, 6.2, 6.3,
     6.4" in the sexp hyperlink indicates that the most important
     things in that page of text are the items 6.1 to 6.4.

  2) The main principle of eev is "take executable notes of everything
     that you do". The easiest part of "take executable notes" is
     "copy to your notes all the links that you find interesting". So,
     if you stumble on a link to a position in a video that looks
     slightly interesting, copy it to your notes; if you find a link
     in, say, this tutorial,

       (find-emacs-keys-intro)
       (eek "M-2 M-j")

     that looks interesting, copy it to your notes.

  3) There are ways to create index to videos in Org, but few people
     use them. Years ago I tried to learn this, but I gave up after a
     while:

     https://lists.gnu.org/archive/html/emacs-orgmode/2020-01/msg00007.html

     Also, the organizers of the last EmacsConf were using some tools
     - that i also didn't learn - the create indexes and transcripts
     for the videos of the conference.

Anyway, tomorrow I will meet with a group of three or four students
that are interested in learning Emacs and eev. They use Windows and
they have never used Emacs before, so we probably won't be able to do
much of this exercise:

  http://angg.twu.net/eev-wconfig.html#learn-org

...which means: sorry for the off-topic-ish e-mails that were about
eev and not about Org, but I hope that we will reach the part in which
they'll start to index Rainer Koenig's videos in a few days...

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

Re: Eev-wconfig.el etc etc, or: "Exercise: Learn Org!"

[Ihor Radchenko]

Eduardo Ochs <eduardoochs@gmail.com> writes:

> I think that you are underestimating how alien eev is for most people.
> Let me suppose that what you mean by your comments is this:
>
>   "I've spent N minutes watching this video - for N big - and I feel
>    that I've learned very little! What is the best way to learn a lot
>    of eev in M minutes, for M very small?"
>
> then the answer is: follow the main tutorial, that is here:
>
>    http://angg.twu.net/eev-intros/find-eev-quick-intro.html

To clarify, I did not expect to learn evv from the video you provided.
However, I did expect to learn things proportionally to the video
length. That way, the video efficiency is pretty low. The video itself
can certainly be improved - the problem is not with eev itself, but
rather with the way you present things.

Note that eev is not actually very alien. Knowing the concept of Org
links, eev is pretty trivial. At least the basics concepts are not hard
to grasp.

> Anyway, tomorrow I will meet with a group of three or four students
> that are interested in learning Emacs and eev. They use Windows and
> they have never used Emacs before, so we probably won't be able to do
> much of this exercise:
>
>   http://angg.twu.net/eev-wconfig.html#learn-org

It would be interesting to hear about the outcome and the student
feedback.

Best,
Ihor

Re: Eev-wconfig.el etc etc, or: "Exercise: Learn Org!"

[Eduardo Ochs]

On Mon, 30 May 2022 at 00:20, Ihor Radchenko <yantar92@gmail.com> wrote:
> It would be interesting to hear about the outcome and the student
> feedback.
>
> Best,
> Ihor

The workshop was by chat (Telegram), and only one student came. He
installed Emacs, Mpv, downloaded a copy with subtitles of the
eev-wconfig video, and then followed the first sections of these two
tutorials,

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

and this video until 48:30,

  http://angg.twu.net/.emacs.videos.html#2022eevwconfig

doing practically all the exercises. He told me that two of the five
tests of `find-wget' didn't work as a described in the video... I need
to debug that - my guess is that I need to add a line to the configs
to make the output of wget.exe be interpreted as UTF-8 by default -
and at one point he called an external program from Emacs and Emacs
crashed. He started Emacs again and recovered some backup files, but
then he had to leave. He asked me if we could continue on Wednesday.
We haven't yet reached the part in which he learns how to index local
videos, but we will probably do that on Wednesday.

I think that that was quite good for three hours. =)

  Cheers, E.