Re: eev-beginner

[Eduardo Ochs]

On Wed, 13 Apr 2022 at 17:52, Quiliro Ordóñez <quiliro@riseup.net> wrote:
> (...)

Hi Quiliro!

> Very nice instructions on all the references.  Congratulations.  They
> were very helpful for understanding eev better.

Thanks! =)

> I tried C-h f for finding the descriptions of some of your commands.
> But they seem undocumented.  Nevertheless, there is documentation in the
> source code.  Is there a reason for this?

Eev has lots of functions that are just one or two lines long, and
that are "documented" by tests in comments in the source. I
experimented with lots of styles of writing docstrings over the years,
and I found that it was usually better to keep the examples and tests
outside of the docstrings - i.e., in the comments - and always
encourage people to always look at the source.

The "source" is not always in a .el file, though. Eev has many
functions that are generated dynamically, and people need to use
`find-efunctionpp' to inspect them. See:

  (find-eev-quick-intro "9. Shorter hyperlinks")
  (find-eev-quick-intro "9.1. `code-c-d'")
  (find-elisp-intro "11. Byte-compiled functions")
  (find-eev-quick-intro "7.1. `eejump'")
  (find-eev-quick-intro "7.1. `eejump'" "meta-uppercase-j")
  (find-eev-quick-intro "7.3. Defining eejump targets")
  (find-eev-quick-intro "7.4. Commands with very short names")
  (find-eev2020video "19:03" "commands with very short names")
  (find-eev2020video "21:07" "commands with very short numbers")

> Later, I see you use this format elsewhere.  Which is the reason to use
> `M-hy' as a replacement of `M-h M-y' ?

I use that format a lot in this tutorial

  (find-saving-links-intro)

to remind people that these keys sequences are intended to be typed
with the meta key being hold down, as explained here,

  (find-eev-quick-intro "7.1. `eejump'")
  (find-eev-quick-intro "7.1. `eejump'" "hold the meta key")

and because I wanted to show the tricks that I use to make these key
sequences take little mental space: I have a way to pronounce these
key sequences in which I only say "meta" once, and I have a compact
way to write them. If people learn these tricks then they _may_ be
able to learn - I mean, without much pain - the workflows for saving
links that I describe in `(find-saving-links-intro)'... I don't know
if these ideas work well, though - AFAIK very few people have tried to
follow that tutorial.

> The video was quite explanatory and left everything clear for me.  But
> the temporary buffer generated by find-1stclassvideo-links was not so
> clear to me.  Please explain the contents.

Can you run the first test in

  (find-efunction 'find-1stclassvideo-links)

and tell me which of the links in the generated buffer don't make
sense to you?

  Cheers,
    E. =)