[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/eev 082a9f4 42/64: Changes in parts of `find-eev-intro'
From: |
Stefan Monnier |
Subject: |
[elpa] externals/eev 082a9f4 42/64: Changes in parts of `find-eev-intro' and `find-escripts-intro'. |
Date: |
Sun, 7 Apr 2019 16:59:10 -0400 (EDT) |
branch: externals/eev
commit 082a9f400641e15c865904379d298f4947924ae8
Author: Eduardo Ochs <address@hidden>
Commit: Eduardo Ochs <address@hidden>
Changes in parts of `find-eev-intro' and `find-escripts-intro'.
---
ChangeLog | 6 ++
VERSION | 4 +-
eev-intro.el | 237 +++++++++++++++++++++++++++++++++++++++--------------------
3 files changed, 166 insertions(+), 81 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 78679bb..040079d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2019-02-26 Eduardo Ochs <address@hidden>
+
+ * eev-intro.el (find-eev-quick-intro, find-eev-intro)
+ (find-prepared-intro, find-escripts-intro, find-rcirc-intro):
+ small changes.
+
2019-02-25 Eduardo Ochs <address@hidden>
* eev-intro.el (find-eev-install-intro): small changes.
diff --git a/VERSION b/VERSION
index b889248..d360ec3 100644
--- a/VERSION
+++ b/VERSION
@@ -1,2 +1,2 @@
-Tue Feb 26 00:21:15 GMT 2019
-Mon Feb 25 21:21:15 -03 2019
+Tue Feb 26 16:50:11 GMT 2019
+Tue Feb 26 13:50:11 -03 2019
diff --git a/eev-intro.el b/eev-intro.el
index 454190b..9a3ae02 100644
--- a/eev-intro.el
+++ b/eev-intro.el
@@ -20,7 +20,7 @@
;;
;; Author: Eduardo Ochs <address@hidden>
;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version: 2019feb25
+;; Version: 2019feb26
;; Keywords: e-scripts
;;
;; Latest version: <http://angg.twu.net/eev-current/eev-intro.el>
@@ -267,6 +267,8 @@ Actually go to: (find-eev \"eev-intro.el\"
\"find-foo-intro\" (ee-last-kill))."
Source code: (find-efunction 'find-eev-quick-intro)
More intros: (find-emacs-keys-intro)
(find-eev-intro)
+ (find-links-conv-intro)
+ (find-escripts-intro)
(find-eval-intro)
(find-links-intro)
(find-eepitch-intro)
@@ -1813,33 +1815,45 @@ Is is meant as both a tutorial and a sandbox.
Here is a list of all the available sandbox-y tutorials that
explain parts and concepts of eev, listed in (a kind of)
-recommended reading order:
+recommended reading order. These are the basic ones:
0. (find-eev-quick-intro)
1. (find-emacs-keys-intro)
- 2. (find-eev-install-intro)
- 3. (find-eev-intro)
- 4. (find-eval-intro)
- 5. (find-links-intro)
- 6. (find-links-conv-intro)
- 7. (find-eepitch-intro)
- 8. (find-wrap-intro)
- 9. (find-eejump-intro)
- 10. (find-anchors-intro)
- 11. (find-code-c-d-intro)
- 12. (find-pdf-like-intro)
- 13. (find-brxxx-intro)
- 14. (find-psne-intro)
-
- 15. (find-audiovideo-intro)
+ 2. (find-eev-intro)
+ 3. (find-eev-install-intro)
+
+These ones explain ideas, conventions, and usage patterns:
+
+ 4. (find-escripts-intro)
+ 5. (find-links-conv-intro)
+
+These are older and more technical versions of sections of the
+eev-quick-intro:
+
+ 6. (find-eval-intro)
+ 7. (find-links-intro)
+ 8. (find-brxxx-intro)
+ 9. (find-eepitch-intro)
+ 10. (find-wrap-intro)
+ 11. (find-eejump-intro)
+ 12. (find-anchors-intro)
+ 13. (find-code-c-d-intro)
+ 14. (find-pdf-like-intro)
+ 15. (find-psne-intro)
+
+These are etcs:
+
16. (find-multiwindow-intro)
- 17. (find-rcirc-intro)
- 18. (find-templates-intro)
- 19. (find-prepared-intro)
- 20. (find-bounded-intro)
- 21. (find-channels-intro)
- 22. (find-videos-intro)
- 23. (find-escripts-intro)
+ 17. (find-audiovideo-intro)
+ 18. (find-rcirc-intro)
+ 19. (find-templates-intro)
+ 20. (find-videos-intro)
+
+These ones explain advanced features that require extra setup:
+
+ 21. (find-prepared-intro)
+ 22. (find-bounded-intro)
+ 23. (find-channels-intro)
Items 0, 3, 4, 5, 6, 9, 10, 11 should give you a good grasp of the
main ideas - namely, that _elisp hyperlinks and interactive scripts
@@ -2768,7 +2782,7 @@ Ideally it should _complement_ the material in:
-5. Functions for templated text
+1. Functions for templated text
===============================
The function that is used to generate templated text from a
string is called `ee-template0'. The function that generates a
@@ -2793,7 +2807,7 @@ is explained in detail here:
-8. `find-here-links'
+2. `find-here-links'
====================
The most important of the commands that generates buffers with elisp
hyperlinks - \"M-h commands\", in the terminology explained above - is
@@ -2882,7 +2896,7 @@ can compare the different cases using just <up>, <down>,
and M-e.
-9. `find-here-links': usage patterns
+3. `find-here-links': usage patterns
====================================
Typically what happens is this. We are putting our notes - eepitch
blocks, hyperlinks, etc - in a certain file; let's refer to it as the
@@ -2935,7 +2949,7 @@ and step (3) sometimes gives several sexps for us to
choose from]
-11. ee-hyperlink-prefix
+4. ee-hyperlink-prefix
=======================
`ee-hyperlink-prefix' is both a variable and a function that
helps us set that variable; it started to an experiment on how to
@@ -2974,7 +2988,7 @@ Try this, with `M-2 M-e' on each line:
-12. The first line regenerates the buffer
+5. The first line regenerates the buffer
=========================================
\[To do: explain this convention with examples; explain the
conventions for the \"variants of the first line\"\]
@@ -2988,7 +3002,7 @@ conventions for the \"variants of the first line\"\]
-13. Pointing to where we are now
+6. Pointing to where we are now
================================
Several of the `M-h' commands are mainly meant to help us
generate hyperlinks to \"where we are now\": to the current file,
@@ -3031,7 +3045,7 @@ buffer, and so on. They don't try to be very smart -
-14. The rest of the buffer
+7. The rest of the buffer
==========================
Several elisp hyperlinks buffers are composed of two parts: a
series of links at the top, and then a template-generated text
@@ -5838,8 +5852,8 @@ support for Rcirc (and no support for ERC).
-The server buffer and the channel buffers
-=========================================
+1. The server buffer and the channel buffers
+============================================
If you type `M-6 M-6 M-j' - or `M-e' on the line below - then eev
runs this,
@@ -5879,8 +5893,8 @@ when we want to check the status of our connection to
Freenode.
-Messages and commands
-=====================
+2. Messages and commands
+========================
IRC is a command-line-ish protocol, in which lines starting with
\"/\" are treated as commands and other lines as messages. A
message typed at the #eev channel buffer is broadcast to all
@@ -5897,7 +5911,7 @@ in #eev than when in #emacs. See:
-Other channels
+3. Other channels
==============
where `find-freenode-3a' is based on `find-3a', described here:
@@ -5906,8 +5920,10 @@ where `find-freenode-3a' is based on `find-3a',
described here:
(find-eev \"eev-rcirc.el\")
-If you are new to IRC
-=====================
+
+
+4. If you are new to IRC
+========================
Most of the discussions between Free Software developers still
happen in IRC channels, and mostly at Freenode. The best way to
understand what IRC is - for modern people, I mean - is probably
@@ -5940,7 +5956,7 @@ For more information see:
(find-node \"(rcirc)Top\")
(find-node \"(rcirc)Internet Relay Chat\")
(find-node \"(rcirc)rcirc commands\")
- http://www.emacswiki.org/emacs/RcIrc
+ httpa://www.emacswiki.org/emacs/RcIrc
http://www.irchelp.org/
(find-node \"(erc)Top\")
@@ -6106,8 +6122,9 @@ This buffer is _temporary_ and _editable_.
Is is meant as both a tutorial and a sandbox.
-Prepared shells
-===============
+
+1. Prepared shells
+==================
Long before eepitch had been created, eev had another way -
technically much simpler, but clumsier from the user's point of
view - to send commands to external shells (and other shell-like
@@ -6152,8 +6169,8 @@ function ee () { set -v; . ~/.eev/ee.sh; set +v; }
-`ee'
-====
+2. `ee'
+=======
\[Explain how several interpreters can be programmed to accept
an `ee' command to execute temporary scripts\]
@@ -6166,8 +6183,8 @@ an `ee' command to execute temporary scripts\]
-An `ee' for Python
-==================
+3. An `ee' for Python
+=====================
Here is a simple way to make Python execute commands saved in a
temporary script when the user types `ee()' (note that it is not
just `ee' - the `()' is needed). We will show first an example in
@@ -6209,8 +6226,8 @@ print(foo(6))
-`eepy'
-======
+4. `eepy'
+=========
The function `eev' receives three parameters, called `s', `e', and
`altfile'; `e' and `altfile' are optional, and `s' should be either a
string or a number. When `s' is a string, then the commands to be
@@ -6262,8 +6279,8 @@ print(foo(6))
-`M-x eepy' and `M-x eev'
-========================
+5. `M-x eepy' and `M-x eev'
+===========================
Now let's define a more realistic `eepy' - one that can also be
called interactively. We want `M-x eepy' to save the current
_region_ into the temporary script; `eepy' has to be a _command_,
@@ -7622,22 +7639,20 @@ what you do, in a format that is reasonably readable
and that is
easy to \"play back\" later, step by step and in any order. We
call these executable logs \"e-scripts\".
-This tutorial is an introduction to some of the most usual
-formats for e-scripts:
-
- 1) files with e-script blocks,
- 2) files with elisp hyperlinks,
- 3) source files with eepitch blocks in multi-line comments.
+We will start this intro by explaining how eev and e-scripts
+appeared. Then we will discuss some of the most usual formats of
+e-scripts, that are, in order or complexity:
+ 1) a file with elisp hyperlinks,
+ 2) a file with e-script blocks and an index,
+ 3) several files with elisp hyperlinks and e-script blocks,
+ 4) source files with eepitch blocks in multi-line comments,
+ 5) temporary buffers like the ones generated by
+ `find-latex-links' and `find-lua-links'.
-We start with a section on how to \"read\" existing e-scripts,
-and then we give some hints to help you start \"writing\" your
-own e-scripts, first in a single file and then on several files.
+We will see first how to \"read\" (and \"play back\"!) them, then
+how to create e-scripts in those formats.
-A typical e-script - like the ones in http://angg.twu.net/e/ - is
-made of an index followed by a series of \"e-script blocks\".
-Here is a miniature example, with an index with two entries
-followed by two e-script blocks (...)
@@ -7683,8 +7698,7 @@ document my code so that it could be included in Emacs.
Eev is not yet an official part of Emacs (long story!) and
eepitch practically replaced `M-x eev' as a way to execute shell
-commands. See: (find-prepared-intro)
-
+commands. For more on `M-x eev', see: (find-prepared-intro)
@@ -7723,26 +7737,91 @@ something that I was trying to understand, or trying to
do.
3. Sharing
==========
+One of my first public texts about eev was the \"Eev Manifesto\":
+
+ http://angg.twu.net/eev-manifesto.html
+
+Here are its main parts.
+
+ Everybody is fluent in only a small fraction of all Unix
+ commands. If you could \"listen\" to how the Unix gurus
+ \"speak\" to their machines you would learn which \"words\" are
+ related to solving a particular task, and learn how they fit in
+ \"sentences\". By checking the \"dictionary entries\" for
+ them (i.e., manpages, info pages, READMEs, source code, etc)
+ you could learn the real meaning of them. But then you'd be
+ learning Unix by immersion, from real use, instead of having to
+ rely only on \"textbooks\", \"dictionaries\" and sometimes
+ \"Rosetta stones\", \"graffitis on toilet walls\" and \"old
+ newspapers\".
+
+ The fact is that you can make a record of how you \"speak\"
+ Unix, and more, you can become a lot more productive if you do
+ so. Many tasks consist on short fixed sequences of commands:
+ connecting to your ISP via modem, unpacking a source package
+ and recompiling it, printing a text file in two-column mode,
+ and so on. The trick is that with some functions defined in
+ eev.el you can write these sequences of commands in a plain
+ text file, then mark a block of this file with your
+ editor (which must be Emacs for this to work), then tell a
+ shell to execute only the commands in that block; in this way
+ you can easily execute only portions of what would otherwise
+ have to be a monolythic script; this is great for when you're
+ not sure if everything works, or if you just want to do some
+ steps. Also, it would be easy to change bits of the \"script\"
+ before execution, as you'll be doing things from inside an
+ editor.
+
+ (...)
+
+ I have placed essentially all my \"scripts\" written in this
+ way (I call them \"e-scripts\") in a public place. They contain
+ almost everything I know about Unix.
+
+ If you like this idea, please get in touch, send comments, ask
+ questions -- about e-scripts or questions whose answer could
+ become an e-script chunk -- or send me your e-scripts when you
+ have some, or even ask for help on setting up your own e-script
+ collection or e-script public site... anything! By asking good
+ questions you can help me make the documentation get better.
+
+ I really want to make this e-scripts idea spread. Learning Unix
+ -- or simply more Unix -- could be made easier for everybody...
+ please help! E-scripts are more fun to use, and easier to
+ write, than texts that tell everything in terms of \"press
+ this, do that\". A lot of effort and money are being invested
+ now on these kinds of text, and they're often very depressing.
+ Let's try to save the world from them, at least a bit, and
+ maybe this money will be directed to better things. And
+ teaching people Unix tricks will be both easier and more fun.
+
+The Manifesto said that
+
+ 1) *NIX can be compared to an oral language,
+ 2) we can \"write\" the commands that we \"speak\",
+ 3) we learn mostly by \"listening\", or \"reading\", others,
+ 4) we have good reasons to write:
+
+ a) executable logs make us more productive,
+ b) our notes/logs can, and should, be shared.
+
+What it *did not* say explicitly was:
+
+ 5) that *not sharing* should be *immoral*,
+ 6) one of my main objectives with eev was REVENGE.
+
+I spent (what felt like) hundreds of hours in the university
+trying to learn things with the *NIX users and gurus there - to
+practically no avail. They answered very few of my questions,
+they only very rarely showed me their code or notes, and I can
+remember only a handful of cases in which we sat side-by-side on
+a terminal.
+These people should be stripped of their hacker status.
-mark these commands and
-execute them with M-x eev; and if we have the habit of using eev
-and we are writing code in, say, C or Lua we will often put elisp
-hyperlinks inside comment blocks in our code. These two specific
-languages (and a few others) have a feature that is quite
-convenient for eev: they have syntactical constructs that allow
-comment blocks spanning several lines --- for example, in Lua,
-where these comment blocks are delimited by --(( and
---))s, we can have a block like
-See: (find-eev \"eev.el\")
- http://angg.twu.net/eev.html
- http://angg.twu.net/eev-article.html
- http://angg.twu.net/emacs.html#what-is-eev
- https://www.gnu.org/brave-gnu-world/issue-13.html
- http://angg.twu.net/eev-manifesto.html
- [elpa] externals/eev 244f47a 34/64: Made eev-intro.el require info.el., (continued)
- [elpa] externals/eev 244f47a 34/64: Made eev-intro.el require info.el., Stefan Monnier, 2019/04/07
- [elpa] externals/eev 95052ba 55/64: Added several fields to eev-pkg.el., Stefan Monnier, 2019/04/07
- [elpa] externals/eev 3950e1e 16/64: First commit in two years; `find-eev-quick-intro', `to-latin1', and lots more, Stefan Monnier, 2019/04/07
- [elpa] externals/eev eee817f 56/64: Added a README (for the ELPA package)., Stefan Monnier, 2019/04/07
- [elpa] externals/eev e0d1bf1 44/64: Added some sections to `find-escripts-intro'., Stefan Monnier, 2019/04/07
- [elpa] externals/eev d671913 61/64: Rewrote `ee-code-c-d-rest'., Stefan Monnier, 2019/04/07
- [elpa] externals/eev 3baac40 43/64: Added some sections to `find-escripts-intro'., Stefan Monnier, 2019/04/07
- [elpa] externals/eev 2dadb94 52/64: Added `find-pdftools-page'., Stefan Monnier, 2019/04/07
- [elpa] externals/eev de74bf9 35/64: Added lots of comments., Stefan Monnier, 2019/04/07
- [elpa] externals/eev bfd11b4 47/64: Added some sections to `find-escripts-intro', Stefan Monnier, 2019/04/07
- [elpa] externals/eev 082a9f4 42/64: Changes in parts of `find-eev-intro' and `find-escripts-intro'.,
Stefan Monnier <=
- [elpa] externals/eev e4d30ff 39/64: Rewrote parts of `find-escripts-intro' and `find-links-intro'., Stefan Monnier, 2019/04/07
- [elpa] externals/eev f974ef7 37/64: Added lots of comments to eev-plinks.el., Stefan Monnier, 2019/04/07
- [elpa] externals/eev 41323e0 58/64: Moved the function `ee-template0' to the file eev-template0.el., Stefan Monnier, 2019/04/07
- [elpa] externals/eev 3325b83 41/64: Some clean-ups in the code for `find-eintro-links' and `find-einfo-links'., Stefan Monnier, 2019/04/07
- [elpa] externals/eev 8afeb43 45/64: Cleaned up eev-mode.el and other files., Stefan Monnier, 2019/04/07
- [elpa] externals/eev 8179ff8 19/64: Make `find-eev-quick-intro\' and `find-emacs-keys-intro\' more important, Stefan Monnier, 2019/04/07
- [elpa] externals/eev 4e07159 57/64: Added some comments to eepitch.el., Stefan Monnier, 2019/04/07
- [elpa] externals/eev f6fd28a 62/64: Cleaned up the comments about `ee-code-c-d-filter-2'., Stefan Monnier, 2019/04/07
- [elpa] externals/eev fc52991 32/64: Fontify the `find-xxx-intro' buffers., Stefan Monnier, 2019/04/07
- [elpa] externals/eev ca3dd97 53/64: Added sections to `find-channels-intro'., Stefan Monnier, 2019/04/07