Proposals for purposes and usage examples

[Jean Louis]

* Eduardo Ochs <eduardoochs@gmail.com> [2023-01-02 23:39]:
> About the "and watch what is happening": I've had the opportunity to
> watch real beginners trying eev just a few times, and in most of these
> times what I saw was that their ability to not understand what was
> happening was beyond my wildest dreams... it was REALLY SCARY. So I
> prefer to think that nowadays "real beginners" will start by the
> videos.
> 
> If you try to teach eev to beginners please tell me what happens, but
> until then let's leave that introduction unchanged... =(

My personal understanding of eev's «purpose» is that it provides
system to create Emacs Lisp functions treated as Hyperlinks useful to
understand environments and contexts of other different objects.

I have understanding of how eev Hyperlinks get generated, though not
so much how they are created.  This comes from personal lack of need
to generate eev hyperlinks. 

In general my text or note shall be markup free. And if I inject
something, then I like to use preprocessing to remove it before
printing, saving, sharing, and displaying.

For that reason I would not like to tangle Emacs Lisp with notes.

In general I keep any kind of properties or Hyperlinks outside of the
note. I have Emacs Lisp type for elementary objects, that is where I
can save eev buffers. I can capture it for later inspection.

If you know the Zettelkasten method, that is automatically implemented
on my side. But I am not to see reference while viewing the note. I
can jump to references and see them, though not all at once. 

I like when viewing description to see only description, but on single
press, to see the main body of the note, and on other single press to
see available reports, or internal information. 

Another key press may show me list of related people and related other
Hyperdocuments or elementary objects. ❰USEFUL❱ 

The quicker jumping and executing visible functions with M-e is
❰USEFUL❱. Generating eev Hyperlinks by M-h M-h is useful and may
create temporary buffer which may be saved for further inspection in
future ❰USEFUL❱.

Here is proposal about headings that somewhat disturbs my
understanding when reading eev buffers.


PROPOSAL
--------

Namely, there is no space or empty line after headings in instruction
and documentation. Consider introducing that space.

I use following rules for text editing:

1. After heading there must be space.

2. Before the continuation heading, there shall be minimum two spaces,
maybe I should switch to three spaces.


That makes text easier readable, as relationships are easier
understood. One can understand what is the body of the section and
what is the next section.


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.


SOLUTION IS COMMAND TO ENCLOSE REGION AND INJECT ANCHOR
-------------------------------------------------------

(defun rcd-enclose-region (open close)
  "Embrace region with OPEN and CLOSE."
  (save-excursion 
    (goto-char (region-beginning))
    (insert open))
  (insert close))

(defun eev-anchor (&optional beg end)
  (interactive "r")
  (let ((open "«")
        (close "»"))
    (cond ((region-active-p) (rcd-enclose-region open close))
          (t (insert open (read-string "Name of anchor: ") close)))))

How to use?

1. Mark region, or not
2. Invoke M-x eev-anchor


PROBLEM IN eev INTRODUCTION
---------------------------

After review of eev-beginner, I have informed you that user may
stumble upon things. You are asking people who have Emacs to download
videos for understanding.

And first section is "Installation". That is not logical. I understand
that you have placed that section for WWW purpose. But then remove it
from eev-beginner, as it makes no sense NOT to tell user what is it
all about. 

While Internet data may be free and inexpensive, it is not so in many
parts of the world. There is certain hesitation if to download the
video or not.


PROPOSAL
--------

Installation instructions are less important in eev-beginner, consider
removing it completely, as people who invoke that function have
already installed eev. Use eev hyperlink to jump to installation
instruction instead of having it there as first heading.

Replace the installation instruction with the summary of how to use
eev and what is its purpose.

Do not assume that all people know what you are doing. 

Help people understand 2 points:
--------------------------------

1. What is the Purpose of eev? Summarize it in a single
   paragraph. Compare what I have written about 

   (to "purpose") 

   in this document. Does my purpose of eev deviate from your own
   definition?

   Send purpose to mailing list, let us read it.

2. Provide section "Why is eev useful" or with similar title. In that
   section give three examples how to start making the mentioned
   executable notes. Don't just say "executable notes" as that alone
   does not clarify what you mean with it. Clarify your workflow in
   few examples. I am not in understanding what should be the workflow
   due to instruction being generalized and explaining everything.

I am well aware that we have now three systems that are by its
abstraction and generalization less understandable, though extremely
useful, those are:

- GNU Hyperbole {M-x package-install RET hyperbole RET} ⬅️ is the
  Hyperbole hyperlink, which can be said to be similar to `eek' which
  I cannot reproduce. Read the Demonstration of Hyperbole and
  "HY-ABOUT" file. It gives summary, and well written introduction. It
  is super tool for many functions in Emacs.

- eev {M-x package-install RET eev RET} is not similar to GNU
  Hyperbole neither to RCD Notes which is my package, though can work
  for any mode.

- RCD Notes and Hyperscope is Dynamic Knowledge Repository as advised
  by Doug Engelbart, and is not easy installable.

   Reference:

   About Dynamic Knowledge Repositories (DKR):
   https://www.dougengelbart.org/content/view/190/163/

When we, three of us, start speaking about our packages, probability
is less that we will get understood, as the way of speaking may
contain abstract statements, generalizations, which do not contribute
to understanding of "Why is it useful".

That is why we have to provide simple and understandable introduction
with purposes and several useful applications.

The word is there: «application»

Myself, I like eev because I know that it brings enlightenment to you
and organizes and calms your mind and brings about understanding about
things. For me is most useful to understand concepts that other people
use, as to devise new ways how to integrate it all together.

-- 
Jean

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

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