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

[Ihor Radchenko <yantar92@gmail.com>]

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