Re: Proposals for purposes and usage examples

[Jean Louis]

* Eduardo Ochs <eduardoochs@gmail.com> [2023-01-06 16:57]:
> > PROPOSAL
> > --------
> >
> > Namely, there is no space or empty line after headings in instruction
> > and documentation. Consider introducing that space.

> You mean in the "intro"s?

I mean it, yes, and I mean it in any kind of file, document, be it eev
or other documents.

Space above & below | Butterick’s Practical Typography:
https://practicaltypography.com/space-above-and-below.html

How much space to add is a judgment call. Semantically, headings
relate to the text that follows, not the text before. Thus you’ll
probably want the space below to be smaller than the space above so
the heading is visually closer to the text it introduces.

> > PROPOSAL
> > --------
> >
> > Create helper functions to generate anchors. Same should apply for other
> > hyperlinks.
> >
> >
> > 8.2. Creating anchors by hand
> > -----------------------------
> > One way to type the chars `«' and `»' is with `C-x 8 <' and
> > `C-x 8 >'. Try:
> >
> >   (eek "RET C-x 8 < t a g C-x 8 >")
> >
> >
> > I find that difficult.
> 
> Me too. That's why I created the methods in these two sections:
> 
>   (find-eev-quick-intro "8.3. Creating index/section anchor pairs")
>   (find-eev-quick-intro "8.4. Creating e-script blocks")
> 
> 
> > SOLUTION IS COMMAND TO ENCLOSE REGION AND INJECT ANCHOR
> > -------------------------------------------------------
> 
> Can you try the methods in the sections 8.3 and 8.4 above? I tried
> many ways of generating index/anchor pairs and I really liked that
> ones...

> The command `eewrap-anchor' (bound to `M-A') is similar to those
> above, but it parses the current line in a more complex way -
> everything between "<>" is the "anchor" and everything before
> the "<" is the "comment prefix" - and it converts the current
> line into two lines with `to's, each one pointing to the other
> one. For example, `M-A' in the line below

>   # «.first-test»     (to "first-test")
>   # «first-test»  (to ".first-test")

I have tried it, it is not same application, not in same context. My
function is for region, or for inserting word with anchor, and your
function is for line. Two different things the are.

I understand your reasoning for downloads, but that does not make it
easier or more convenient. Internet is almost free in Europe, and
difficult to access in the majority of planet Earth.

I would say to always first use text, images, and then video.

But never video without text first.

> > 1. What is the Purpose of eev? Summarize it in a single
> >    paragraph.
> 
> I've tried that many times, and that sort of can't be done - at least
> it can't be done _in text_. I have many summaries available, and most
> people hate either all of them or all but one or two. Try this one:
> 
>   http://angg.twu.net/eev-for-longtime-emacs-users.html

I was the test person, I read that introduction and is not enough.  I
can't gain understanding. 

> The purpose of eev _for me_ is to let me "automate almost everything"
> by recording executable notes like that and playing them back like
> that.

I understand it is for you. Though it is too general. Automating
everything is good in general, but does not tell what eev does. 

Recently Drew Adams said he does not understand my expressions like in
the context of `thingatpt.el', we talked, and then:

> > The concept of elementary things basically teach
> > computer to recognize where is the point.

> I don't follow you there.

And he is expert in `thing-at-point' extensions. That means my
statement was not enough expressive, not enough specific, and he told
me three times to be more specific.

That is the cognitive barrier that often takes place when we have to
talk in abstractions. 

Back to introduction of eev. It is abstract and not clear.

Let's go line by line:

> favorite short explanation for what eev is is this one (from here):

> I used to call eev a "tool for automating almost everything"

I understand that is how you use the tool, though for introduction is
good to be more specific.

I am developing RCD Notes package, of course I want to automate almost
everything. GNU Hyperbole automates almost everything. Emacs Lisp
automates almost everything. Those statements do not lead to
understanding. 

Provide examples what is automated.

Example statements about GNU Hyperbole, I am making them now:
-------------------------------------------------------------

- M-RET is smart key, it helps user to jump to referenced information
  based on context such as Hyperlinks, file names, and programming
  functions. (I did not say everything, but I have tried being specific.)

- HyRolo is name of the computer program to insert, edit, search for
  contacts and addresses of people and organizations. (This one shall
  be understandable)

> project to save the world with Free Software".

Alright, though as personal opinion it is less helpful to understand
what is eev.

> In more concrete terms, eev is a library for Emacs that lets us
> create executable logs of what we do in a format that is reasonably
> easy to read and to modify, and that lets us "play back" those logs
> step by step in any order - for example, like in this video. We can
> even edit our executable logs in the middle of playing them back, as
> shown in this demo of test blocks.

Sounds useful, it is similar to debugging, though I do not get full
understanding.

Executable log -- I do not understand as there is no clear example.

If it is log, there must be preceding action. Action example is not
explained. 

I hope you don't mind with this attempt to make clarification for
people.


Question
--------

Is it right that action must precede the creation of log?


Exercise
--------

1. Provide me three actions that you do

2. Show how is executable log created for those actions

3. Show how to execute the log and replay the actions


When I think now of the explanation on that first page, then I also
think of RCD Notes and Hyperscope packages I am developing, here is
example:

1. There are elementary objects, like notes, videos, etc.

2. Each elementary object has its tags, properties, ID, UUID

3. I do "execute" playing of a video, there is Emacs Lisp and
   functions being executed, though they are automatic, normally on
   the key `l' as in `vi' editor major cursor keys are "h", "j", "k"
   and "l" as they are close to each other, and "l" stands for
   direction to right, though also arrow right can be used to execute
   playing of a video. It also looks like play button on many video
   player.s

4. There is log called "ring" which records each activated elementary
   object ID, date, time when it was activated (executed).

5. I can then go back in time, and see:

   "Which videos did I play?" -- I can see list of videos, mark them
   to generate the list of played videos, and create a new elementary
   object named "Play List" which when activated plays all the videos
   at once that have been previously activated one by one. 

   And it is possible to do it also one by one, including it is
   possible to modify what I am executing one by one.

Above workflow is very fast, and easy. It is just few keys like "m",
arrow down and "m", "m" to mark elementary objects and then some key
to create new elementary object "Play List". Explanation is much
longer than practical action.

I have just described the below statement by looking in functionality
that I already use in my notes. 

> In more concrete terms, eev is a library for Emacs that lets us
> create executable logs of what we do in a format that is reasonably
> easy to read and to modify, and that lets us "play back" those logs
> step by step in any order

I wish to say that it is not enough specific. 

There is `xref' package which allows to jump from Emacs function to
Emacs function.

There is edebug, which also create executable logs and let me play
back what was executed one by one, including allow me to read and
modify those logs.

As you see, there are several examples that more or less fit into the
same description.

Summary of this email is that eev IMHO needs more specific
introduction with examples which will help readers and users to get
understanding of what the package does.

-- 
Jean

Take action in Free Software Foundation campaigns:
https://www.fsf.org/campaigns

In support of Richard M. Stallman
https://stallmansupport.org/