-
Notifications
You must be signed in to change notification settings - Fork 3
/
eev-intro.el
20292 lines (14298 loc) · 634 KB
/
eev-intro.el
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
;;; eev-intro.el --- sandboxed tutorials for eev, like (find-eev-quick-intro) -*- lexical-binding: nil; -*-
;; Copyright (C) 2013-2024 Free Software Foundation, Inc.
;;
;; This file is part of GNU eev.
;;
;; GNU eev is free software: you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
;;
;; GNU eev is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;;
;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
;;
;; Author: Eduardo Ochs <[email protected]>
;; Maintainer: Eduardo Ochs <[email protected]>
;; Version: 20241127
;; Keywords: e-scripts
;;
;; Latest version: <http://anggtwu.net/eev-current/eev-intro.el>
;; htmlized: <http://anggtwu.net/eev-current/eev-intro.el.html>
;; See also: <http://anggtwu.net/eev-current/eev-beginner.el.html>
;; <http://anggtwu.net/eev-intros/find-eev-intro.html>
;; (find-eev-intro)
;;; Commentary:
;;
;; Sometime around 2015 I realized that I could make a sandboxed
;; tutorial - (find-eev-quick-intro) - that would be THE starting
;; point of eev. It would be:
;;
;; 1) an interactive tutorial for beginners,
;; 2) the thing that emacs shows when it starts,
;; 3) a tutorial for advanced users,
;; 4) an index to the other sandboxed tutorials, that were mostly
;; quite technical (and incomplete),
;; 5) a guide to the source files.
;;
;; In 2019 the work to make (find-eev-quick-intro) central was
;; completed. The only autoloaded function of eev is `eev-beginner',
;; that loads all the main modules of eev, turns eev-mode on, and runs
;; (find-eev-quick-intro). See:
;;
;; (find-eevfile "eev-beginner.el" "defun eev-beginner ")
;; To use this, simply execute any of the sexps below:
;; (find-eev-quick-intro)
;; (find-eev-intro)
;; Quick index:
;; «.find-intro-dual» (to "find-intro-dual")
;; «.find-eintro» (to "find-eintro")
;; «.skip-invisible» (to "skip-invisible")
;;
;; «.find-eev-quick-intro» (to "find-eev-quick-intro")
;; «.find-emacs-keys-intro» (to "find-emacs-keys-intro")
;; «.find-eev-install-intro» (to "find-eev-install-intro")
;; «.find-eev-levels-intro» (to "find-eev-levels-intro")
;; «.find-eev-intro» (to "find-eev-intro")
;; «.find-here-links-intro» (to "find-here-links-intro")
;; «.find-refining-intro» (to "find-refining-intro")
;; «.find-saving-links-intro» (to "find-saving-links-intro")
;;
;; «.find-eval-intro» (to "find-eval-intro")
;; «.find-links-conv-intro» (to "find-links-conv-intro")
;; «.find-links-intro» (to "find-links-intro")
;; «.find-eepitch-intro» (to "find-eepitch-intro")
;; «.find-wrap-intro» (to "find-wrap-intro")
;; «.find-eejump-intro» (to "find-eejump-intro")
;; «.find-anchors-intro» (to "find-anchors-intro")
;; «.find-code-c-d-intro» (to "find-code-c-d-intro")
;; «.find-pdf-like-intro» (to "find-pdf-like-intro")
;; «.find-brxxx-intro» (to "find-brxxx-intro")
;; «.find-psne-intro» (to "find-psne-intro")
;;
;; «.find-audiovideo-intro» (to "find-audiovideo-intro")
;; «.find-multiwindow-intro» (to "find-multiwindow-intro")
;; «.find-rcirc-intro» (to "find-rcirc-intro")
;; «.find-templates-intro» (to "find-templates-intro")
;; «.find-prepared-intro» (to "find-prepared-intro")
;; «.find-bounded-intro» (to "find-bounded-intro")
;; «.find-channels-intro» (to "find-channels-intro")
;; «.find-videos-intro» (to "find-videos-intro")
;; «.find-video-links-intro» (to "find-video-links-intro")
;; «.find-defun-intro» (to "find-defun-intro")
;; «.find-emacs-intro» (to "find-emacs-intro")
;; «.find-org-intro» (to "find-org-intro")
;; «.find-escripts-intro» (to "find-escripts-intro")
;; «.find-git-intro» (to "find-git-intro")
;; «.find-windows-beginner-intro» (to "find-windows-beginner-intro")
;; «.find-eev-exercises-intro» (to "find-eev-exercises-intro")
;; «.find-kla-intro» (to "find-kla-intro")
;; «.find-kl-here-intro» (to "find-kl-here-intro")
;; «.find-edit-index-intro» (to "find-edit-index-intro")
;; «.find-rstdoc-intro» (to "find-rstdoc-intro")
;; «.find-show2-intro» (to "find-show2-intro")
;; «.find-lua-tutorial-intro» (to "find-lua-tutorial-intro")
;; «.find-dot-emacs-intro» (to "find-dot-emacs-intro")
;; «.find-debootstrap-intro» (to "find-debootstrap-intro")
;; «.find-lean4-intro» (to "find-lean4-intro")
;; «.find-try-sly-intro» (to "find-try-sly-intro")
;; Videos:
;; «.find-three-main-keys-intro» (to "find-three-main-keys-intro")
;;
;; «.find-elisp-intro» (to "find-elisp-intro")
;; «.find-lexical-intro» (to "find-lexical-intro")
;; «.find-strange-functions-intro» (to "find-strange-functions-intro")
;; See: (find-anchors-intro)
;; For: (find-efile "info.el" "defface info-title-1")
(require 'info)
;; «find-intro-dual» (to ".find-intro-dual")
;; Below is a hack that I (edrx) use to edit these intros.
;; Note that it is sort of commented out.
;;
;; If we're editing the defun for `find-foo-intro' at a line that
;; contains "<a certain string>" then running `M-x fd' there creates a
;; window setup like this,
;;
;; _______________________________________
;; | | |
;; | source: | intro: |
;; | eev-intro.el | *(find-foo-intro)* |
;; |________________|______________________|
;;
;; with both windows centered on the lines with "<a certain string>".
;; If we're editing the buffer "*(find-foo-intro)*" and we're on a
;; line containing "<a certain string>" then running `M-x fd' also
;; creates the same window setup, with the source at the left and the
;; intro buffer at the right.
(defun find-intro-dual-define ()
"Define `find-intro-dual' and `fd', that are hacks for editing `find-xxx-intro's."
(interactive)
;; The hackish functions begin here and end at the line with a single ")".
;; ;; Test: (ee-sexp-at "2)")
;; ;; (+ 1 2)
;; (defun ee-sexp-at (re)
;; (save-excursion (re-search-forward re) (ee-last-sexp)))
;;
;; (setq ee-intro-sexp-end-re "\\(rest\\|pos-spec-list\\))))")
;; (defun ee-intro-sexp-here ()
;; "Go to the end of the defun around point and `read' it.
;; Only works for \"(defun find-xxx-intro ...)s\".
;; Returns a list like this: (defun find-xxx-intro ...)."
;; (read (ee-sexp-at ee-intro-sexp-end-re)))
(defun ee-bad-line (str) (string-match "[\\\"]" str))
(defun ee-this-line ()
(let ((line (ee-kl-line)))
(if (ee-bad-line line)
(error "Current line contains evil characters")
line)))
(defun ee-intro-sourcep ()
(equal (buffer-name) "eev-intro.el"))
(defun find-intro-intro ()
"If we're in the defun for `find-foo-intro' run (find-foo-intro (ee-this-line))."
(interactive)
(funcall (eval-defun nil) (ee-this-line)))
(defun find-intro-source ()
"If we're in a buffer \"*(find-foo-intro)*\" go to the source for `find-foo-intro'.
Actually go to: (find-eev \"eev-intro.el\" \"find-foo-intro\" (ee-last-kill))."
(interactive)
(find-eev "eev-intro.el" (format "find-%s-intro" (ee-intro-bufferp))
(ee-this-line)))
;; (defun find-2a (a b) (find-wset "13_o_o" a b))
;; (defun find-2b (a b) (find-wset "13_o_" a b))
(defun find-c2a (a b) (find-wset "13_co_co" a b))
(defun find-c2b (a b) (find-wset "13_co_c" a b))
(defun find-intro-dual ()
(interactive)
(if (ee-intro-sourcep)
(progn (eval-defun nil)
(find-c2b nil '(find-intro-intro)))
(find-c2a '(find-intro-source) nil)))
(defalias 'fs 'find-intro-source)
(defalias 'fi 'find-intro-intro)
(defalias 'fd 'find-intro-dual)
(message "`find-intro-dual' and `fd' are now defined.")
;; end of `find-intro-dual-define'
)
;;; __ _ _ __
;;; / _| ___ _ __ | |_(_)/ _|_ _
;;; | |_ / _ \| '_ \| __| | |_| | | |
;;; | _| (_) | | | | |_| | _| |_| |
;;; |_| \___/|_| |_|\__|_|_| \__, |
;;; |___/
;;
;; «find-eintro» (to ".find-eintro")
;; 2019feb03: experimental. This is like `find-estring' but it runs
;; `ee-intro-fontify-maybe' to optionally fontify the titles;
;; `ee-intro-fontify-maybe' is similar to `Info-fontify-node'.
;; Compare:
;; (find-fline "/usr/share/info/emacs-24/elisp.info.gz" "****")
;; (find-elnode "Top" "Emacs Lisp\n**********")
;; This is practically a copy of:
;; (find-efile "info.el" "defun Info-fontify-node" ";; Fontify titles")
(defun ee-intro-fontify ()
(interactive)
(save-excursion
(goto-char (point-min))
(while (and (re-search-forward
"\n\\([^ \t\n].+\\)\n\\(\\*\\*+\\|==+\\|--+\\|\\.\\.+\\)$"
nil t)
;; Only consider it as an underlined title if the ASCII
;; underline has the same size as the text. A typical
;; counter example is when a continuation "..." is alone
;; on a line.
(= (string-width (match-string 1))
(string-width (match-string 2))))
(let* ((c (preceding-char))
(face (ee-intro-face c)))
(put-text-property (match-beginning 1) (match-end 1)
'face face))
;; This is a serious problem for trying to handle multiple
;; frame types at once. We want this text to be invisible
;; on frames that can display the font above.
(when (memq (framep (selected-frame)) '(x pc w32 ns))
(add-text-properties
(1- (match-beginning 2)) (match-end 2)
'(invisible t front-sticky nil rear-nonsticky t))))))
;; (find-elnode "Overlay Properties" "list of faces")
;; (find-efaces "info-title-1")
;; (find-efaces "underline")
(defun ee-intro-face (c)
(cond ((= c ?*) '(info-title-1 underline))
((= c ?=) '(info-title-2 underline))
((= c ?-) '(info-title-3 underline))
(t 'info-title-3)))
(defun ee-intro-fontify-maybe ())
(defun ee-intro-fontify-maybe () (ee-intro-fontify))
(defun find-eintro (bigstr &rest pos-spec-list)
"Like `find-estring', but runs `ee-intro-fontify-maybe'."
(find-estring bigstr)
(ee-intro-fontify-maybe)
(apply 'ee-goto-position pos-spec-list))
(defun find-eintro-latin1 (bigstr &rest pos-spec-list)
"Like `find-eintro', but handles some strange chars in BIGSTR."
(apply `find-eintro (ee-tolatin1 bigstr) pos-spec-list))
;;; _ _ _ _ _ _ _
;;; ___| | _(_)_ __ (_)_ ____ _(_)___(_) |__ | | ___
;;; / __| |/ / | '_ \ _____| | '_ \ \ / / / __| | '_ \| |/ _ \
;;; \__ \ <| | |_) |_____| | | | \ V /| \__ \ | |_) | | __/
;;; |___/_|\_\_| .__/ |_|_| |_|\_/ |_|___/_|_.__/|_|\___|
;;; |_|
;;
;; In buffers generated by `find-eintro' this sexp
;; (buffer-substring (ee-bol) (ee-eol))
;; sometimes returns something like this,
;; "1. Introduction\n==============="
;; with text properties indicating that the last part is invisible.
;; The variants of `ee-bol' and `ee-eol' below fix this (but in a
;; fragile way).
;;
;; «skip-invisible» (to ".skip-invisible")
(defun ee-bol-skip-invisible ()
(save-excursion (move-beginning-of-line 1) (point)))
(defun ee-eol-skip-invisible ()
(save-excursion (move-beginning-of-line 1) (ee-eol)))
;;; _ _ _ _
;;; ___ _____ __ __ _ _ _(_) ___| | __ (_)_ __ | |_ _ __ ___
;;; / _ \/ _ \ \ / /____ / _` | | | | |/ __| |/ /____| | '_ \| __| '__/ _ \
;;; | __/ __/\ V /_____| (_| | |_| | | (__| <_____| | | | | |_| | | (_) |
;;; \___|\___| \_/ \__, |\__,_|_|\___|_|\_\ |_|_| |_|\__|_| \___/
;;; |_|
;;
;; «find-eev-quick-intro» (to ".find-eev-quick-intro")
;; Skel: (find-intro-links "eev-quick")
(defun find-eev-quick-intro (&rest pos-spec-list) (interactive)
(let ((ee-buffer-name "*(find-eev-quick-intro)*"))
(apply 'find-eintro-latin1 "\
\(Re)generate: (find-eev-quick-intro)
Source code: (find-efunction 'find-eev-quick-intro)
More intros: (find-emacs-keys-intro)
(find-eev-intro)
(find-here-links-intro)
(find-refining-intro)
(find-eepitch-intro)
(find-pdf-like-intro)
This buffer is _temporary_ and _editable_.
It is meant as both a tutorial and a sandbox.
The quickest way to open or recreate this is with `M-5 M-j'.
This is a tutorial for real beginners.
It supposes that you have Emacs installed.
For more material on eev, see:
http://anggtwu.net/#eev
1. Installing eev
=================
If you already use Emacs then the easiest way to install eev is
with the \"single-sexp `try-it's\", that are explained in this page:
http://anggtwu.net/2024-find-tryit-links.html
If you are not yet familiar with Emacs then the easiest way is with
`M-x list-packages', as explained in this video:
http://anggtwu.net/2020-list-packages-eev-nav.html
http://anggtwu.net/2020-list-packages-eev-nav.html#00:01
http://www.youtube.com/watch?v=kxBjiUo88_U
The three \"video\" links in the \"Video links:\" block below
[Video links:]
(find-eevnavhsubs \"00:30\" \"0.1. M-x package-initialize\")
(find-eevnavvideo \"00:30\" \"0.1. M-x package-initialize\")
(find-eevnavhsubs \"00:39\" \"0.2. M-x list-packages\")
(find-eevnavvideo \"00:39\" \"0.2. M-x list-packages\")
(find-eevnavhsubs \"02:33\" \"0.3. M-x eev-beginner\")
(find-eevnavvideo \"02:33\" \"0.3. M-x eev-beginner\")
point to positions in that video, and the \"hsubs\" links point to its
subtitles. To learn how to use links like those, visit this URL:
http://anggtwu.net/eev-intros/find-video-links-intro.html
(find-video-links-intro)
Installing eev does NOT activate eev-mode. To activate eev-mode
and open this tutorial, run `M-x eev-beginner'.
\"Installing\" eev doesn't \"load\" eev. The difference between
installing and loading is explained here:
(find-eev-levels-intro)
TIP FOR BEGINNERS: if you are a real beginner with, say, less
than 10 minutes of experience using Emacs, then you will probably
be in a stage in which you often get stuck in the middle of
something that you don't know how to leave - for example, you may
be in the middle of a \"complex command\", and Emacs may be
waiting for the keys that would complete the command. The easiest
way to handle that is to leave Emacs and then start it again, and
after starting it again you will need to type `M-x eev-beginner'
to activate eev again. For an explanation of this in video, see:
[Video links:]
(find-eevnavhsubs \"03:46\" \"0.4. for the beginners: quitting and restarting\")
(find-eevnavvideo \"03:46\" \"0.4. for the beginners: quitting and restarting\")
(find-eevnavhsubs \"04:05\" \"the part of the sequence of keys\")
(find-eevnavvideo \"04:05\" \"the part of the sequence of keys\")
(find-eevnavhsubs \"04:23\" \"go to the file menu, click quit\")
(find-eevnavvideo \"04:23\" \"go to the file menu, click quit\")
(find-eevnavhsubs \"04:41\" \"enter emacs again, type M-x eev-beginner\")
(find-eevnavvideo \"04:41\" \"enter emacs again, type M-x eev-beginner\")
Eventually you will learn how to get out of everything and how to undo
almost anything, _BUT THAT WILL NOT HAPPEN IN THE FIRST TEN MINUTES_.
This tutorial is intended to make you learn the most essential things
in the first ten minutes - including how to navigate in Emacs's
manuals.
2. Evaluating Lisp
==================
The most important idea in Emacs is that Lisp code can appear
anywhere, and you can evaluate a Lisp expression (a \"sexp\") by
placing the cursor (the \"point\") just after it and typing `C-x
C-e'; the result is then displayed in the echo area.
Note: `C-e' means control-E, `M-e' means alt-e, `M-E' means
alt-shift-e. If you have Caps Lock on then Emacs will receive an `M-E'
if you type alt-e, and `M-e' if you type alt-shift-e. Hint: avoid Caps
Lock!
You can try `C-x C-e' in the line below, with the point in the three
different indicated positions - you should get different results...
(+ (* 2 3) (* 4 5))
^ ^^
| | \\
6 20 26
...but `C-x C-e' is not beginner-friendly, and it even enters a
debugger that is hard to leave if it finds errors, so let's see
something better.
When you type `M-e' emacs moves the point to the end of the
current line, then runs a variant of `C-x C-e'. Try this on each
line of the block below:
(+ (* 2 3)
(* 4 5)
)
`M-e' accepts several different numeric prefixes that alter its
behavior. We are only interested in one of them now - `M-0 M-e'
highlights the sexp for a fraction of a second instead of executing it.
Try it above.
In some rare occasions we might want to run something like `M-e'
but without moving to the end of the line first. Eev-mode
implements a key binding for that: `M-E' (meta-shift-e). As an
exercise, try to use `M-0 M-E' at several positions below, to
highlight the subsexps `(* 2 3)', `(* 4 5)', and `4'.
(+ (* 2 3) (* 4 5))
3. Elisp hyperlinks
===================
Each one of the sexps below makes Emacs \"go somewhere\" if you execute
it with `M-e'. Executing sexps like those - we will call them \"elisp
hyperlinks\" - is like following a hyperlink in a browser.
In a browser you can \"go back\" after following a hyperlink because the
previous page is kept in the memory somehow. In Emacs+eev the easiest
way to \"go back\" is with `M-k', which runs a function called
`ee-kill-this-buffer'. If you follow one of the links below with
`M-e', it creates a new buffer and displays it. If you then type `M-k'
this new buffer is killed, and Emacs displays the buffer that was just
below it, which is this tutorial... try it! Here are some nice elisp
hyperlinks:
(find-fline \"~/\")
(find-efunctiondescr 'find-file)
(find-eval-intro \"5. Going back\")
(find-fline \"/tmp/\")
(find-man \"date\")
(find-sh \"date\")
(find-sh \"date; sleep 1; date\")
Not all elisp hyperlinks \"go somewhere\"; some are like buttons that
perform an action, like the one below, that acts as if the user had
pressed a series of keys,
(eek \"<down> C-a H E L L O ! <up> C-e\")
and some display their output in the echo area:
(find-sh0 \"date\")
The following elisp hyperlinks may or may not work - try them too, but
be aware that they may show errors instead of opening a new buffer.
The first two of them open a page - actually a section, whose short
title is \"Lisp Eval\" - from the main Emacs manual. The third one
opens the file with the source code (in Lisp) for the function
`find-file'. The fourth one opens a directory that contains a part of
the source code of Emacs.
(find-node \"(emacs)Lisp Eval\")
(find-enode \"Lisp Eval\")
(find-efunction 'find-file)
(find-efile \"\")
If they don't work that means that you don't have the Emacs manuals,
or the elisp source files, installed. The names for the packages which
have those things vary from one GNU/Linux distro to another. On Debian
something like
sudo apt-get install emacs-el
sudo apt-get install emacs-common-non-dfsg
may work - but for \"...-non-dfsg\" packages may need you to
enable access to the \"non-free\" repository... ask for help if
you need!
An important difference between elisp hyperlinks and browser
hyperlinks is discussed here:
(find-links-conv-intro \"1. Security vs. transparency\")
3.1. Non-elisp hyperlinks
-------------------------
Emacs has ways to follow URLs, but the keys for that are totally
different from the ones for elisp hyperlinks. You can follow the URL
below by putting the point on it and typing `M-x browse-url':
http://www.lua.org/start.html
This will make emacs invoke the default browser on that URL. See:
(find-enode \"Browse-URL\")
Eev defines several functions similar to `browse-url'. These elisp
hyperlinks
(find-firefox \"http://www.lua.org/start.html\")
(find-googlechrome \"http://www.lua.org/start.html\")
invoke \"firefox\" and \"google-chrome\" respectively on the given URL;
note that the \"firefox\" in a Debian-based system is usually a free
derivative of Firefox, and that \"google-chrome\" does not come
installed by default because it is \"gratis\" but not free. Also,
M-x brff -- runs `find-firefox' on the URL at point,
M-x brg -- runs `find-googlechrome' on the URL at point.
For more on the \"brxxx functions\" of eev, see:
(find-brxxx-intro)
4. Creating Elisp Hyperlinks
============================
You can write elisp hyperlinks by hand, but that is hard. It is better
to generate hyperlinks automatically and then use cut and paste.
Eev has several functions that generate \"elisp hyperlinks\" buffers.
For example,
(find-efunction-links 'find-file)
creates this buffer, and switches to it:
____________________________________________________________________
|# (find-efunction-links 'find-file) |
|# (eek \"M-h M-f find-file\") |
|# (find-eev-quick-intro \"4.2. `find-ekey-links' and friends\") |
| |
|# (find-efunctiondescr 'find-file) |
|# (find-efunction 'find-file) |
|# (find-efunctionpp 'find-file) |
|# (find-efunctiond 'find-file) |
| |
|# (Info-goto-emacs-command-node 'find-file) |
|# (find-enode \"Command Index\" \"* find-file:\") |
|# (find-elnode \"Index\" \"* find-file:\") |
| |
|# (where-is 'find-file) |
|# (symbol-file 'find-file 'defun) |
|# (find-fline (symbol-file 'find-file 'defun)) |
|# (find-estring (documentation 'find-file)) |
|# (find-estring (documentation 'find-file t)) |
|# (describe-function 'find-file) |
| |
| |
| -:**- *Elisp hyperlinks* All L1 (Fundamental eev) ----------|
|____________________________________________________________________|
[Video links:]
(find-eev2020hsubs \"29:38\" \"2. A tale of two `describe-key's\")
(find-eev2020video \"29:38\" \"2. A tale of two `describe-key's\")
(find-eev2020hsubs \"31:31\" \"the problem with the standard `describe-key'\")
(find-eev2020video \"31:31\" \"the problem with the standard `describe-key'\")
(find-eev2020hsubs \"35:07\" \"My variant: `find-ekey-links'\")
(find-eev2020video \"35:07\" \"My variant: `find-ekey-links'\")
(find-eev2020hsubs \"37:00\" \"how `find-ekey-links' generates its links\")
(find-eev2020video \"37:00\" \"how `find-ekey-links' generates its links\")
(find-eev2020hsubs \"37:14\" \"hacker-friendly in the way that I wanted\")
(find-eev2020video \"37:14\" \"hacker-friendly in the way that I wanted\")
4.1. `find-here-links'
----------------------
One standard way of using eev is:
a) we keep our current notes in a a file - for example, \"~/TODO\"
b) these notes are an \"executable log\" of what we did, including:
c) hyperlinks to things we saw or visited
d) commands issued to shells or shell-like programs (see sec. 6)
The quickest way of generating hyperlinks for (c) is with `M-h M-h'
\(`find-here-links'). When we type `M-h M-h' eev tries to generate an
elisp hyperlinks buffer containing some hyperlinks to \"here\" - and how
it does that depends on the major mode and on the name of the current
buffer. For example, typing `M-h M-h' here generates:
___________________________________________________________________
|# See: |
|# (find-eev-quick-intro \"4.1. `find-here-links'\") |
|# (find-emacs-keys-intro \"1. Basic keys (eev)\" \"M-h M-h\") |
|# (find-here-links-intro \"4. `find-here-links-3'\") |
| |
|# http://anggtwu.net/eev-intros/find-eev-quick-intro.html |
|# (find-eev-quick-intro) |
| |
| |
| -:**- *Elisp hyperlinks* All L1 (Fundamental eev) --------|
|___________________________________________________________________|
The elisp hyperlink
# (find-eev-quick-intro)
at the end opens this tutorial.
The best way to learn how to create very quickly these
\"hyperlinks to things we saw or visited\" and to copy them to
our notes is explained in a separate tutorial:
(find-here-links-intro)
(find-here-links-intro \"3. `find-here-links'\")
(find-here-links-intro \"3. `find-here-links'\" \"beginners\")
Cutting and pasting is explained briefly in section 5.2, below.
A way to go quickly to \"~/TODO\" is explained in section 7.1.
A way to \"refine\" hyperlinks to make them more precise is
explained here:
(find-refining-intro \"2. Refining hyperlinks\")
UPDATE
See this:
(find-kl-here-intro)
for a way of generating \"hyperlinks to here\" that is usually
much more practical than `find-here-links'. NOTE: it was
implemented in dec/2023 and is still experimental!
4.2. `find-ekey-links' and friends
----------------------------------
Emacs is huge and you will probably want to save in your notes
many links about keys and functions that look interesting - using
`M-2 M-j' from time to time to visit
(find-emacs-keys-intro)
and learning the keys listed there will not be enough.
Try the eek links below:
(eek \"M-h M-k C-x 4 0\")
(eek \"M-h M-k C-x 4 0 ;; kill-buffer-and-window\")
(eek \"M-h M-k C-s\")
(eek \"M-h M-k C-s ;; isearch-forward\")
(eek \"M-h M-f isearch-forward\")
(eek \"M-h M-k M-h M-k ;; find-ekey-links\")
(eek \"M-h M-k M-h M-f ;; find-efunction-links\")
You will notice that:
1. they create temporary buffers with lots of elisp hyperlinks,
2. you can \"go back\" from these buffers with `M-k',
3. the function name after the \";;\" is a comment and is
ignored by Emacs (but is useful for humans),
4. you can copy these hyperlinks to your \"~/TODO\",
5. the \"M-h M-k\" and \"M-h M-f\" in the beginning are
reminders that we can use `M-h M-k <key-sequence>' and `M-h
M-f <function-name>' to create help buffers about other keys
and functions,
6. some of the hyperlinks use low-level representations for key
sequences - you don't need to understand them. An example:
(find-ekey-links \"\\^X40\")
7. for _some_ keys and functions, but not all, the hyperlinks
like
(Info-goto-emacs-key-command-node \"\\C-s\")
(Info-goto-emacs-command-node 'isearch-forward)
(find-enode \"Command Index\" \"* isearch-forward:\")
(find-elnode \"Index\" \"* defun:\")
that appear near the middle of the elisp hyperlinks buffers,
point to relevant points in the Emacs manuals - see the next
section.
8. `M-h M-k' can also handle some sequences of input events
that are not key sequences. For example, if you click
on \"Help\" in the menu bar and then click on \"Search
Documentation\" and then on \"Emacs Terminology\" in the
submenus this will open this page of the Emacs manual:
(find-enode \"Glossary\")
If you do `M-h M-k' and then click on Help -> Search
Documentation -> Emacs Terminology in the menu bar then `M-h
M-k' will generate a buffer in which one of the first lines
will be:
(eek \"M-h M-k <menu-bar> <help-menu> <search-documentation> <emacs-terminology>\")
For more information on that see:
(find-enode \"Menu Bar\")
(find-enode \"Glossary\" \"\\nInput Event\")
(find-elnode \"Input Events\")
(find-elnode \"Key Sequence Input\" \"menu-bar\")
5. Links to Emacs documentation
===============================
Try these links (some of them need the Emacs manuals installed):
(find-emacs-keys-intro \"Cutting & pasting\")
(find-node \"(emacs)Screen\")
(find-efunctiondescr 'find-file)
(find-efunction-links 'find-file)
This part of the eev tutorials has links to almost all the keys that
I've learned by heart after using Emacs for 20 years:
(find-emacs-keys-intro \"2. Key sequences\")
They are not very many, because I use this a lot,
(find-node \"(emacs)M-x\")
and I use elisp hyperlinks to create quick reminders for the keys that
I only need to remember when I am performing specific tasks.
Moral: when you want a quick reference of the main Emacs and eev keys,
type `M-2 M-j'.
5.1. Navigating the Emacs manuals
---------------------------------
The Emacs manuals are in \"info\" format, which means:
a) they are divided into \"nodes\" - a top node, and chapters,
sections, subsections, etc,
b) the nodes in each manual in info format are organized as a tree,
and they're all numbered except for the top node, the indexes and
the appendixes. For example:
top --.-- 1 --.-- 1.1
| `-- 1.2
|-- 2
|-- 3 ----- 3.1 --.-- 3.1.1
| |-- 3.1.2
| `-- 3.1.3
|-- Appendix A
`-- Index
c) each node has both a short name and a long name (its title),
and they may be different. For example, the hyperlinks below
(find-node \"(emacs)Intro\")
(find-node \"(emacs)Screen\")
point to nodes whose titles are \"Introduction\" and \"The
Organization of the Screen\",
d) each manual also has a short name, also called its
_filename_, and several kinds of long names and titles. The
`find-node' links use the filename in parenthesis followed
by the short node name. For example:
Manual title elisp hyperlink
----------------------------------------------------------
GNU Emacs Manual (find-node \"(emacs)Top\")
Emacs Lisp / GNU Emacs Lisp
Reference Manual (find-node \"(elisp)Top\")
An Introduction to
Programming in Emacs Lisp (find-node \"(eintr)Top\")
e) The \"Info directory\" lists all the installed info manuals.
You can access it with:
(find-node \"(dir)Top\")
The main Emacs manuals appear grouped together there. Try:
(find-node \"(dir)Top\" \"extensible self-documenting\")
You will see something like this:
Emacs
* Emacs: The extensible self-documenting text editor.
* Emacs FAQ: Frequently Asked Questions about Emacs.
* Elisp: The Emacs Lisp Reference Manual.
* Emacs Lisp Intro: A simple introduction to Emacs Lisp
programming.
f) Emacs uses \"Info mode\" when displaying nodes of manuals in
info format. In Info mode the tool bar displays icons
meaning \"back\", \"forward\", \"previous\", \"next\",
\"home\", etc, and you can click on these icons to navigate
from the current node to other nodes. The main keys of Info
mode are worth learning, though - the full list of keys can
be found here,
(find-efunctiondescr 'Info-mode)
and the main ones are:
q exit (go back to some other buffer)
(arrows) move point
RET follow link at point
TAB move to next link
BACKTAB move to prev link
u move \"up\" from this node
n move to the \"next\" node of this node
p move to the \"previous\" node of this node
[ go backward one node, considering all nodes as
forming one sequence
] go forward one node, considering all nodes as
forming one sequence
d go to the Info directory node.
l move back in history to the last node you were at.
r move forward in history to the node you returned from
after using `l'
L go to menu of visited nodes
T go to table of contents of the current Info file
Try the keys above now - if you execute the `eek' sexp below
it will split the window, keep these instructions in the left
window and open and Info buffer at the right.
(eek \"<down> M-3 M-e ;; open the hyperlink below in the right window\")
(find-node \"(emacs)Basic\")
(find-node \"(emacs)Major Modes\")
5.2. Cutting and pasting
------------------------
You can do cut, copy and paste in a \"user-friendly\" way by using
a) the rightmost icons in the toolbar, or
b) the \"Edit\" menu in the menu-bar,
but the keys are very much worth learning:
C-SPC -- set-mark-command (find-enode \"Setting Mark\")
C-x C-x -- exchange-point-and-mark (find-enode \"Setting Mark\" \"C-x C-x\")
C-w -- kill-region (cut) (find-enode \"Other Kill Commands\")
M-w -- kill-ring-save (copy) (find-enode \"Kill Ring\")
C-y -- yank (paste) (find-enode \"Kill Ring\")
The \"region\" where cut & paste operate is always what is between
the \"point\" and the \"mark\". See:
(find-enode \"Point\")
(find-enode \"Mark\")
Exercise: understand how the `eek' sexp below switches the two
lines just after it.
(eek \"<down> C-a C-SPC <down> C-w <down> C-y 3*<up>\")
First
Second
6. Controlling shell-like programs
==================================
This is the second main feature of eev. The hyperlinks thing used the
keys `M-e', `M-k', and `M-h M-h', plus standard Emacs keys for cutting
and pasting. The module of eev that controls shell-like programs - it
is called \"eepitch\" - uses `<F8>' and `M-T'. Note that it is
`alt-shift-t', to not interfere with Emacs's `M-t'.
For more details see:
(find-eepitch-intro)
(find-wrap-intro \"2. <M-T>: produce an eepitch block\")
[Video links:]
(find-eevnavhsubs \"10:36\" \"if I type <f8> six times here\")
(find-eevnavvideo \"10:36\" \"if I type <f8> six times here\")
(find-eevnavhsubs \"10:49\" \"a shell running inside Emacs\")
(find-eevnavvideo \"10:49\" \"a shell running inside Emacs\")
(find-eev2021hsubs \"00:14\" \"and if we type f8 several times here\")
(find-eev2021video \"00:14\" \"and if we type f8 several times here\")
(find-eev2019hsubs \"15:13\" \"the alternative to `M-x eev'\")
(find-eev2019video \"15:13\" \"the alternative to `M-x eev'\")
(find-eev2019hsubs \"15:48\" \"Demo: eepitch on non-red star lines\")
(find-eev2019video \"15:48\" \"Demo: eepitch on non-red star lines\")
(find-eev2019hsubs \"15:58\" \"Demo: eepitch in action\")
(find-eev2019video \"15:58\" \"Demo: eepitch in action\")
6.1. The main key: <F8>
-----------------------
Emacs can run a shell in a buffer, and it can split its frame
into windows, like this:
___________________
| | |
| our | a |
| notes | shell |
| | buffer |
|_________|_________|
The usual way to use a shell buffer is to move the cursor there
and type commands into its prompt; the eepitch-y way is to leave
the cursor at the \"notes\" buffer, write the commands for the
shell there, and send these commands to the shell with <F8>.
Here's what <F8> does:
When we type <F8> on a line that starts with a red
star (\"\"), it executes the rest of the line as Lisp, and
moves down; when we type <F8> on a line that does not start
with a \"\", it makes sure that the \"target buffer\" is being
displayed (the \"target\" is usually the buffer called
\"*shell*\"), it \"send\"s the current line to the target
buffer, and moves down.
\"Sending the current line to the target buffer\" means copying
the contents of the current line to the target - as if the user
had typed that line there by hand -, then \"typing\" a <RET> at
the target buffet.
Please try that in the example after this paragraph, by typing
<F8> six times starting at the first line that says
\" (eepitch-shell)\". The three red star lines at the top will
create a target buffer, destroy it, and create it again; the
other three lines will send commands to the target shell.
(eepitch-shell)
(eepitch-kill)
(eepitch-shell)
echo \"We are at: $PWD\"
cd /tmp/
echo \"We changed to: $(pwd)\"
6.2. Other targets
------------------
Just like `(eepitch-shell)' creates a shell buffer and sets the
eepitch target to it, `(eepitch-python)' creates a buffer with a
Python interpreter and uses it as the eepitch target. Try:
(eepitch-python)
(eepitch-kill)
(eepitch-python)
def square (x):
return x*x
print(square(5))
We can use several targets at the time, alternating between them.
For example:
(eepitch-shell)