* Eduardo Ochs <eduardoo...@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/