[Emacs Lisp] Personal ~/.emacs.d/ configuration folder.
Fill column is now `66'.
smart-documents.org
@@ -11,42 +11,46 @@
11
11
#+LATEX_HEADER: \usepackage{lettrine}
12
12
13
13
#+LATEX: \begin{abstract}
14
Removed:
The idea of /Smart Documents/ came to me as I was reflecting on how to improve
15
Removed:
the document creation process in my workplace. The GNU Emacs editor had
16
Removed:
captured my imagination and I wanted to create an accessible and highly
17
Removed:
productive text editor to benefit my organization. In this paper, I'll lay out
18
Removed:
my vision for the /Smart Document/, a file containing both text destined to the
19
Removed:
reader, and code describing how to update, validate, and present this text;
20
Removed:
then, I'll weave my personal GNU Emacs customizations with a tutorial. This
21
Removed:
paper is a /Smart Document/ itself!
14
Added:
The idea of /Smart Documents/ came to me as I was reflecting on
15
Added:
how to improve the document creation process in my workplace. The
16
Added:
GNU Emacs editor had captured my imagination and I wanted to
17
Added:
create an accessible and highly productive text editor to benefit
18
Added:
my organization. In this paper, I'll lay out my vision for the
19
Added:
/Smart Document/, a file containing both text destined to the
20
Added:
reader, and code describing how to update, validate, and present
21
Added:
this text; then, I'll weave my personal GNU Emacs customizations
22
Added:
with a tutorial. This paper is a /Smart Document/ itself!
22
23
#+LATEX: \end{abstract}
23
24
24
25
* Introduction
25
26
26
Removed:
GNU Emacs is most often used as a text editor. It would be unfair to say it is
27
Removed:
just that, because Emacs is capable of so much more. The utmost level of
28
Removed:
customization is afforded by enabling the user to rewrite /any/ part of the
29
Removed:
source code and observe the editor's modified behavior in real time. Since its
30
Removed:
inception in 1984, GNU Emacs has grown to be much more than a full-featured,
31
Removed:
high-productivity text editor---new /modes/ have been written to interact with
32
Removed:
hundreds of file formats, including =.txt=, =.pdf=, =.jpg=, =.csv=, and =.zip=
33
Removed:
just to name a few. This paper itself was written in /Org mode/, a collection
34
Removed:
of functions enabling the harmonious mixing of code and comments in view of
35
Removed:
publication: this is the endgame of /literate programming/, and the basis of my
27
Added:
GNU Emacs is most often used as a text editor. It would be unfair
28
Added:
to say it is just that, because Emacs is capable of so much
29
Added:
more. The utmost level of customization is afforded by enabling
30
Added:
the user to rewrite /any/ part of the source code and observe the
31
Added:
editor's modified behavior in real time. Since its inception in
32
Added:
1984, GNU Emacs has grown to be much more than a full-featured,
33
Added:
high-productivity text editor---new /modes/ have been written to
34
Added:
interact with hundreds of file formats, including =.txt=, =.pdf=,
35
Added:
=.jpg=, =.csv=, and =.zip= just to name a few. This paper itself
36
Added:
was written in /Org mode/, a collection of functions enabling the
37
Added:
harmonious mixing of code and comments in view of publication:
38
Added:
this is the endgame of /literate programming/, and the basis of my
36
39
vision for /Smart Documents/.
37
40
38
Removed:
The following sections were laid out very deliberately. When we start Emacs,
39
Removed:
the source code blocks contained in this document are evaluated
40
Removed:
sequentially---our editing environment is constructed in real time as we
41
Removed:
execute the blocks in order. For instance, we only begin loading packages once
42
Removed:
we ensured ~use-package~ is working properly.[fn::For more information on the
43
Removed:
detailed steps Emacs takes upon starting, refer to
41
Added:
The following sections were laid out very deliberately. When we
42
Added:
start Emacs, the source code blocks contained in this document are
43
Added:
evaluated sequentially---our editing environment is constructed in
44
Added:
real time as we execute the blocks in order. For instance, we only
45
Added:
begin loading packages once we ensured ~use-package~ is working
46
Added:
properly.[fn::For more information on the detailed steps Emacs
47
Added:
takes upon starting, refer to
44
48
[[https://www.gnu.org/software/emacs/manual/html_node/elisp/Startup-Summary.html]].]
45
49
46
50
Customizing Emacs goes far, far beyond rewriting sections of this
47
Removed:
document---feel free to experiment and discover. Here are three commands that
48
Removed:
will help you understand all the symbols in this file, if you are browsing this
49
Removed:
paper within Emacs itself:
51
Added:
document---feel free to experiment and discover. Here are three
52
Added:
commands that will help you understand all the symbols in this
53
Added:
file, if you are browsing this paper within Emacs itself:
50
54
51
55
- ~C-h f~ :: describe function
52
56
- ~C-h v~ :: describe variable
@@ -102,9 +106,9 @@
102
106
103
107
** TODO User details
104
108
105
Removed:
One advantage of working with /Smart Documents/ is that they can automatically
106
Removed:
be populated with our details in the header, footer, or other appropriate
107
Removed:
element.
109
Added:
One advantage of working with /Smart Documents/ is that they can
110
Added:
automatically be populated with our details in the header, footer,
111
Added:
or other appropriate element.
108
112
109
113
#+NAME: user-details-get
110
114
#+BEGIN_SRC emacs-lisp
@@ -151,12 +155,13 @@
151
155
:END:
152
156
153
157
The contents of this Section was automatically moved to
154
Removed:
=~/.emacs.d/init.el=.
155
Removed:
Use `sd-pack-section' to copy the contents back into this section.
158
Added:
=~/.emacs.d/init.el=. Use `sd-pack-section' to copy the contents
159
Added:
back into this section.
156
160
157
Removed:
This is the very first user-editable file loaded by Emacs.[fn::This feature
158
Removed:
became available in version 27.1.] In it, we disable GUI elements that would
159
Removed:
otherwise be loaded and displayed once Emacs is ready to accept user input.
161
Added:
This is the very first user-editable file loaded by
162
Added:
Emacs.[fn::This feature became available in version 27.1.] In it,
163
Added:
we disable GUI elements that would otherwise be loaded and
164
Added:
displayed once Emacs is ready to accept user input.
160
165
161
166
It can be found here: [[file:early-init.el]]
162
167
@@ -166,9 +171,9 @@
166
171
:END:
167
172
168
173
#+BEGIN_QUOTE
169
Removed:
Traditionally, file =~/.emacs= is used as the init file, although Emacs also
170
Removed:
looks at =~/.emacs.el=, =~/.emacs.d/init.el=, =~/.config/emacs/init.el=, or
171
Removed:
other locations.
174
Added:
Traditionally, file =~/.emacs= is used as the init file, although
175
Added:
Emacs also looks at =~/.emacs.el=, =~/.emacs.d/init.el=,
176
Added:
=~/.config/emacs/init.el=, or other locations.
172
177
173
178
From the GNU
174
179
website[fn::[[https://www.gnu.org/software/emacs/manual/html_node/emacs/Init-File.html]]]
@@ -180,8 +185,9 @@
180
185
181
186
** Profiling --- start
182
187
183
Removed:
We start the profiler now , and will interrupt it in Section [[Profiling ---
184
Removed:
stop]]. We will then present profiling report in Section [[Profiling --- report]].
188
Added:
We start the profiler now , and will interrupt it in Section
189
Added:
[[Profiling --- stop]]. We will then present profiling report in
190
Added:
Section [[Profiling --- report]].
185
191
186
192
#+NAME: profiler-start
187
193
#+BEGIN_SRC emacs-lisp :tangle yes
@@ -215,15 +221,17 @@
215
221
216
222
** Meta-files
217
223
218
Removed:
In this section, we'll be tidying up the =.emacs.d/= directory---by default,
219
Removed:
many Emacs packages create files useful for themselves in our
220
Removed:
~user-emacs-directory~. This leads to undesirable clutter. Certain packages
221
Removed:
create files that log recently visited files ([[Recently visited files]]); log
222
Removed:
location of known projects ([[Projects' bookmarks]]); log location in recently
223
Removed:
visited files ([[Location in previously visited file]]) The commonality
224
Removed:
between all these files is that they tend to reference... other files. Thus, I
225
Removed:
decided to refer to them as meta-files. First, let's designate a folder to collect
226
Removed:
our meta-files together:
224
Added:
In this section, we'll be tidying up the =.emacs.d/=
225
Added:
directory---by default, many Emacs packages create files useful
226
Added:
for themselves in our ~user-emacs-directory~. This leads to
227
Added:
undesirable clutter. Certain packages create files that log
228
Added:
recently visited files ([[Recently visited files]]); log location of
229
Added:
known projects ([[Projects' bookmarks]]); log location in recently
230
Added:
visited files ([[Location in previously visited file]]) The
231
Added:
commonality between all these files is that they tend to
232
Added:
reference... other files. Thus, I decided to refer to them as
233
Added:
meta-files. First, let's designate a folder to collect our
234
Added:
meta-files together:
227
235
228
236
#+BEGIN_SRC emacs-lisp :tangle yes
229
237
(setq sd-meta-files-location (concat user-emacs-directory "meta/"))
@@ -255,9 +263,9 @@
255
263
256
264
*** Custom file
257
265
258
Removed:
Load settings created automatically by GNU Emacs Custom. (For example, any
259
Removed:
clickable option/toggle is saved here.) Useful for fooling around with ~M-x
260
Removed:
customize-group <package>~.
266
Added:
Load settings created automatically by GNU Emacs Custom. (For
267
Added:
example, any clickable option/toggle is saved here.) Useful for
268
Added:
fooling around with ~M-x customize-group <package>~.
261
269
262
270
#+NAME: custom-file-location
263
271
#+BEGIN_SRC emacs-lisp :tangle yes
@@ -299,8 +307,9 @@
299
307
300
308
*** GNU/Linux
301
309
302
Removed:
These settings affect the first and subsequent frames spawned by Emacs in
303
Removed:
GNU/Linux. Frame transparency increases when focus is lost.
310
Added:
These settings affect the first and subsequent frames spawned by
311
Added:
Emacs in GNU/Linux. Frame transparency increases when focus is
312
Added:
lost.
304
313
305
314
#+BEGIN_SRC emacs-lisp :tangle yes
306
315
(when (and (display-graphic-p) (string-equal system-type "gnu/linux"))
@@ -310,11 +319,12 @@
310
319
311
320
** Secrets
312
321
313
Removed:
The code contained in the =secrets.org= file is loaded by Emacs, but not
314
Removed:
rendered in this PDF for the sake of privacy. It contains individually
315
Removed:
identifying information such as names and e-mail addresses, which are used to
316
Removed:
populate Org templates (Section [[~org-mode~]]). You need to create this
317
Removed:
=secrets.org= file, as it is ignored by =git= by default.
322
Added:
The code contained in the =secrets.org= file is loaded by Emacs,
323
Added:
but not rendered in this PDF for the sake of privacy. It contains
324
Added:
individually identifying information such as names and e-mail
325
Added:
addresses, which are used to populate Org templates (Section
326
Added:
[[~org-mode~]]). You need to create this =secrets.org= file, as it is
327
Added:
ignored by =git= by default.
318
328
319
329
#+BEGIN_SRC emacs-lisp :tangle yes
320
330
(let ((secrets (concat user-emacs-directory "secrets.org")))
@@ -323,20 +333,22 @@
323
333
324
334
* Keyboard shortcuts
325
335
326
Removed:
The following bindings strive to further enhance CUA mode.[fn::Common User
327
Removed:
Access. This is a term coined by IBM which has influenced user navigation cues
328
Removed:
on all modern desktop OSes. From IBM's CUA, we get the =Ctrl-c= and =Ctrl-v=
329
Removed:
keyboard shortcuts.]
336
Added:
The following bindings strive to further enhance CUA
337
Added:
mode.[fn::Common User Access. This is a term coined by IBM which
338
Added:
has influenced user navigation cues on all modern desktop
339
Added:
OSes. From IBM's CUA, we get the =Ctrl-c= and =Ctrl-v= keyboard
340
Added:
shortcuts.]
330
341
331
342
#+BEGIN_SRC emacs-lisp :tangle yes
332
343
(cua-mode)
333
344
#+END_SRC
334
345
335
Removed:
What follows are the most useful keybindings, as well as the keybindings to the
336
Removed:
functions we defined ourselves. It doesn't matter if we haven't defined the
337
Removed:
functions themselves yet; Emacs will accept a keybinding for any symbol and
338
Removed:
does not check if the symbol's function definition exists, until the keybinding
339
Removed:
is pressed.
346
Added:
What follows are the most useful keybindings, as well as the
347
Added:
keybindings to the functions we defined ourselves. It doesn't
348
Added:
matter if we haven't defined the functions themselves yet; Emacs
349
Added:
will accept a keybinding for any symbol and does not check if the
350
Added:
symbol's function definition exists, until the keybinding is
351
Added:
pressed.
340
352
341
353
** Files
342
354
@@ -466,12 +478,13 @@
466
478
467
479
** Navigation
468
480
469
Removed:
=Alt= (=Meta=) is the privileged key for motion in a buffer. It is followed by
470
Removed:
an optional numerical argument, and a movement command. You may navigate in a
471
Removed:
buffer by keeping =Alt= pressed, optionally inputting a number from the keypad
472
Removed:
or number row, then pressing any of the following movement keys: =j=, =k=, =h=,
473
Removed:
and =l=. You will move in that direction in the amount of the numerical
474
Removed:
argument.
481
Added:
=Alt= (=Meta=) is the privileged key for motion in a buffer. It is
482
Added:
followed by an optional numerical argument, and a movement
483
Added:
command. You may navigate in a buffer by keeping =Alt= pressed,
484
Added:
optionally inputting a number from the keypad or number row, then
485
Added:
pressing any of the following movement keys: =j=, =k=, =h=, and
486
Added:
=l=. You will move in that direction in the amount of the
487
Added:
numerical argument.
475
488
476
489
#+NAME: keybinding-navigation
477
490
#+CAPTION[Navigation keybindings]: Navigation keybindings.
@@ -532,13 +545,15 @@
532
545
533
546
** One-click workflows
534
547
535
Removed:
A major advantage of the Emacs document production system: arbitrarily
536
Removed:
complicated functions can be assigned to very simple keybindings. This means we
537
Removed:
can automate workflows up to a pretty absurd level.
548
Added:
A major advantage of the Emacs document production system:
549
Added:
arbitrarily complicated functions can be assigned to very simple
550
Added:
keybindings. This means we can automate workflows up to a pretty
551
Added:
absurd level.
538
552
539
553
*** Export to PDF
540
554
541
Removed:
PDF is probably the most prevalent file format for sharing static documents.
555
Added:
PDF is probably the most prevalent file format for sharing static
556
Added:
documents.
542
557
543
558
**** Document
544
559
@@ -570,7 +585,8 @@
570
585
571
586
* Packages
572
587
573
Removed:
Packages are collections of =.el= files providing added functionality to Emacs.
588
Added:
Packages are collections of =.el= files providing added
589
Added:
functionality to Emacs.
574
590
575
591
** Meta
576
592
@@ -594,7 +610,8 @@
594
610
595
611
*** TODO Convenient package update
596
612
597
Removed:
One-function rollup of upgradeable package tagging, download and lazy install.
613
Added:
One-function rollup of upgradeable package tagging, download and
614
Added:
lazy install.
598
615
599
616
#+BEGIN_SRC emacs-lisp :tangle yes
600
617
@@ -602,8 +619,8 @@
602
619
603
620
*** ~use-package~
604
621
605
Removed:
We ensure =use-package= is installed, as well as all packages described in this
606
Removed:
configuration file.
622
Added:
We ensure =use-package= is installed, as well as all packages
623
Added:
described in this configuration file.
607
624
608
625
#+BEGIN_SRC emacs-lisp :tangle yes
609
626
(unless (package-installed-p 'use-package)
@@ -619,9 +636,10 @@
619
636
620
637
Forgive me, for I have sinned.
621
638
622
Removed:
This is the 2^{nd} most significant customization after ~org-mode~. Enabling
623
Removed:
~evil-mode~ completely changes editing keys.[fn::For more information on =vi=
624
Removed:
keybindings, visit [[https://hea-www.harvard.edu/~fine/Tech/vi.html]].]
639
Added:
This is the 2^{nd} most significant customization after
640
Added:
~org-mode~. Enabling ~evil-mode~ completely changes editing
641
Added:
keys.[fn::For more information on =vi= keybindings, visit
642
Added:
[[https://hea-www.harvard.edu/~fine/Tech/vi.html]].]
625
643
626
644
#+BEGIN_SRC emacs-lisp :tangle yes
627
645
(use-package evil)
@@ -631,13 +649,14 @@
631
649
632
650
** Spelling, completion, and snippets
633
651
634
Removed:
The following customizations open the doors to vastly increased typing speed
635
Removed:
and accuracy.
652
Added:
The following customizations open the doors to vastly increased
653
Added:
typing speed and accuracy.
636
654
637
655
*** Syntax checking
638
656
639
Removed:
We require a package to highlight syntax errors and warnings. The ~flycheck~
640
Removed:
package ensures we are aware of all our code's syntactical shortcomings.
657
Added:
We require a package to highlight syntax errors and warnings. The
658
Added:
~flycheck~ package ensures we are aware of all our code's
659
Added:
syntactical shortcomings.
641
660
642
661
#+NAME: flycheck
643
662
#+BEGIN_SRC emacs-lisp :tangle yes
@@ -655,21 +674,22 @@
655
674
656
675
*** Insert template from keyword
657
676
658
Removed:
Thanks to ~yasnippet~, we can type certain keywords, then press =TAB=, to
659
Removed:
automatically insert a predefined text snippet. We can then navigate through
660
Removed:
the snippet by using =<tab>= (next field) and =<backtab>= (previous
661
Removed:
field).[fn::=<backtab>= is synonymous with pressing shift-tab.]
677
Added:
Thanks to ~yasnippet~, we can type certain keywords, then press
678
Added:
=TAB=, to automatically insert a predefined text snippet. We can
679
Added:
then navigate through the snippet by using =<tab>= (next field)
680
Added:
and =<backtab>= (previous field).[fn::=<backtab>= is synonymous
681
Added:
with pressing shift-tab.]
662
682
663
Removed:
For instance: typing =src= then pressing =TAB= will expand the keyword to the
664
Removed:
following text:
683
Added:
For instance: typing =src= then pressing =TAB= will expand the
684
Added:
keyword to the following text:
665
685
666
686
: #+BEGIN_SRC emacs-lisp :tangle yes
667
687
:
668
688
: #+END_SRC
669
689
670
Removed:
We notice that emacs-lisp is highlighted---this is the first modifiable
671
Removed:
field. Many clever programming tricks can be performed with ~yasnippet~ to save
672
Removed:
us a ton of time with boilerplate text!
690
Added:
We notice that emacs-lisp is highlighted---this is the first
691
Added:
modifiable field. Many clever programming tricks can be performed
692
Added:
with ~yasnippet~ to save us a ton of time with boilerplate text!
673
693
674
694
#+NAME: yasnippet
675
695
#+BEGIN_SRC emacs-lisp :tangle yes
@@ -696,8 +716,8 @@
696
716
697
717
*** Versioning of files
698
718
699
Removed:
Wonderful Git porcelain for Emacs. Enables the administration of a Git
700
Removed:
repository in a pain-free way.
719
Added:
Wonderful Git porcelain for Emacs. Enables the administration of a
720
Added:
Git repository in a pain-free way.
701
721
702
722
#+BEGIN_SRC emacs-lisp :tangle yes
703
723
(use-package magit
@@ -724,9 +744,9 @@
724
744
725
745
*** Jump to symbol's definition
726
746
727
Removed:
~dumb-jump~ is a reliable symbol definition finder. It uses different matching
728
Removed:
algorithms and heuristics to provide a very educated guess on the location of a
729
Removed:
symbol's definition.
747
Added:
~dumb-jump~ is a reliable symbol definition finder. It uses
748
Added:
different matching algorithms and heuristics to provide a very
749
Added:
educated guess on the location of a symbol's definition.
730
750
731
751
#+BEGIN_SRC emacs-lisp :tangle yes
732
752
(use-package dumb-jump)
@@ -752,8 +772,10 @@
752
772
753
773
**** Smartly suggesting interactive search matches
754
774
755
Removed:
Wonderful counsellor!
775
Added:
And he will be called Wonderful *Counselor*, Mighty God,
776
Added:
Everlasting Father, Prince of Peace.
756
777
778
Added:
757
779
#+BEGIN_SRC emacs-lisp :tangle yes
758
780
(use-package counsel
759
781
:bind ("M-x" . counsel-M-x)
@@ -798,8 +820,8 @@
798
820
799
821
*** Interacting with PDFs
800
822
801
Removed:
Org mode shines particularly when exporting to PDF---Org files can reliably be
802
Removed:
shared and exported to PDF in a reproducible fashion.
823
Added:
Org mode shines particularly when exporting to PDF---Org files can
824
Added:
reliably be shared and exported to PDF in a reproducible fashion.
803
825
804
826
#+BEGIN_SRC emacs-lisp :tangle yes
805
827
(use-package pdf-tools)
@@ -808,9 +830,10 @@
808
830
809
831
*** Accounting
810
832
811
Removed:
Ledger is a creation of John Wiegley's. It enables double-entry accounting in a
812
Removed:
simple plaintext format, and reliable verification of account balances through
813
Removed:
time.[fn::For more information, visit https://www.ledger-cli.org/.]
833
Added:
Ledger is a creation of John Wiegley's. It enables double-entry
834
Added:
accounting in a simple plaintext format, and reliable verification
835
Added:
of account balances through time.[fn::For more information, visit
836
Added:
https://www.ledger-cli.org/.]
814
837
815
838
#+BEGIN_SRC emacs-lisp :tangle yes
816
839
(use-package ledger-mode
@@ -819,8 +842,8 @@
819
842
("C-c C" . ledger-mode-clean-buffer))
820
843
#+END_SRC
821
844
822
Removed:
These reports can be generated within Emacs. It is quite useful to pipe their
823
Removed:
output to an automated ``smart document''.
845
Added:
These reports can be generated within Emacs. It is quite useful to
846
Added:
pipe their output to an automated ``smart document''.
824
847
825
848
#+BEGIN_SRC emacs-lisp :tangle yes
826
849
(setq ledger-reports
@@ -880,7 +903,8 @@
880
903
881
904
*** Highlight ``color keywords'' in their color
882
905
883
Removed:
This highlights hexadecimal numbers which look like colors, in that same color.
906
Added:
This highlights hexadecimal numbers which look like colors, in
907
Added:
that same color.
884
908
885
909
#+BEGIN_SRC emacs-lisp :tangle yes
886
910
(use-package rainbow-mode
@@ -890,33 +914,35 @@
890
914
891
915
*** +UTF-8 bullet points in =Org mode=+
892
916
893
Removed:
This section was removed, as it is more explicit to display the headline
894
Removed:
character for what it is: a collection of at least one asterisk.
917
Added:
This section was removed, as it is more explicit to display the
918
Added:
headline character for what it is: a collection of at least one
919
Added:
asterisk.
895
920
896
921
* ~org-mode~
897
922
898
Removed:
Org mode is so significant that this section of the paper deserves its own
899
Removed:
introduction.
923
Added:
Org mode is so significant that this section of the paper deserves
924
Added:
its own introduction.
900
925
901
926
** Introduction
902
927
903
Removed:
Phew, after all this initialization, I can finally introduce Org mode! I am so
904
Removed:
*excited*.
928
Added:
Phew, after all this initialization, I can finally introduce Org
929
Added:
mode! I am so *excited*.
905
930
906
Removed:
Org mode replaces aword processor, a presentation creator, and a spreadsheet
907
Removed:
editor. The spreadsheet ability captures more than 80% use cases wherein one
908
Removed:
wishes to include a table in a text document destined for physical
909
Removed:
publication. (It is clear that Excel spreadsheets are /not/ destined for
910
Removed:
physical publication---simply attempt to print an Excel spreadsheet with the
911
Removed:
default settings.) In my opinion, Org mode matches all /useful/ features of
912
Removed:
the Microsoft Office suite 1-to-1.
931
Added:
Org mode replaces aword processor, a presentation creator, and a
932
Added:
spreadsheet editor. The spreadsheet ability captures more than 80%
933
Added:
use cases wherein one wishes to include a table in a text document
934
Added:
destined for physical publication. (It is clear that Excel
935
Added:
spreadsheets are /not/ destined for physical publication---simply
936
Added:
attempt to print an Excel spreadsheet with the default settings.)
937
Added:
In my opinion, Org mode matches all /useful/ features of the
938
Added:
Microsoft Office suite 1-to-1.
913
939
914
Removed:
What follows are customizations designed to make Org mode behave more like
915
Removed:
Microsoft Word. The end goal is, once again, to draw as many new users to Emacs
916
Removed:
as possible!
940
Added:
What follows are customizations designed to make Org mode behave
941
Added:
more like Microsoft Word. The end goal is, once again, to draw as
942
Added:
many new users to Emacs as possible!
917
943
918
Removed:
Check out how much information Org mode keeps concerning the most recent
919
Removed:
header:
944
Added:
Check out how much information Org mode keeps concerning the most
945
Added:
recent header:
920
946
921
947
#+NAME: org-meta-info
922
948
#+BEGIN_SRC emacs-lisp :tangle no :results pp :exports both :cache yes
@@ -936,7 +962,8 @@
936
962
937
963
*** Base folder
938
964
939
Removed:
Org base directory is in user home on GNU/Linux, or in =AppData= in MS Windows.
965
Added:
Org base directory is in user home on GNU/Linux, or in =AppData=
966
Added:
in MS Windows.
940
967
941
968
#+NAME: org-directory
942
969
#+BEGIN_SRC emacs-lisp :tangle yes
@@ -951,10 +978,11 @@
951
978
952
979
** Org cosmetics
953
980
954
Removed:
First, we ensure the display of markup symbols for *bold*, /italic/,
955
Removed:
_underlined_ and +strikethrough+ text, and ensure our document appears indented
956
Removed:
upon loading.[fn::It /appears/ indented, but the underlying plaintext file does
957
Removed:
not contain tab characters!]
981
Added:
First, we ensure the display of markup symbols for *bold*,
982
Added:
/italic/, _underlined_ and +strikethrough+ text, and ensure our
983
Added:
document appears indented upon loading.[fn::It /appears/ indented,
984
Added:
but the underlying plaintext file does not contain tab
985
Added:
characters!]
958
986
959
987
We then set values for many other Org-related cosmetic symbols.
960
988
@@ -968,21 +996,22 @@
968
996
969
997
*** Dynamic numbering of headlines
970
998
971
Removed:
We enable the dynamic numbering of headlines in an Org buffer. We also set the
972
Removed:
numbering face to ~org-special-keyword~, which specifies a ~:background white~
973
Removed:
attribute. This is necessary because otherwise, the background of the numbering
974
Removed:
may be overridden by the ~TODO~ face attribute ~:background coral~.
999
Added:
We enable the dynamic numbering of headlines in an Org buffer. We
1000
Added:
also set the numbering face to ~org-special-keyword~, which
1001
Added:
specifies a ~:background white~ attribute. This is necessary
1002
Added:
because otherwise, the background of the numbering may be
1003
Added:
overridden by the ~TODO~ face attribute ~:background coral~.
975
1004
976
1005
#+BEGIN_SRC emacs-lisp :tangle yes
977
1006
(add-hook 'org-mode-hook 'org-num-mode)
978
1007
(setq org-num-face 'org-special-keyword)
979
1008
#+END_SRC
980
1009
981
Removed:
By default, we hide Org document properties such as =#+TITLE=, =#+AUTHOR=, and
982
Removed:
=#+DATE=, because those keywords are defined when the document template is
983
Removed:
populated. We can nevertheless always access those properties and edit them
984
Removed:
manually, with a simple keyboard shortcut (cf. Section [[Open Org mode document
985
Removed:
properties]]).
1010
Added:
By default, we hide Org document properties such as =#+TITLE=,
1011
Added:
=#+AUTHOR=, and =#+DATE=, because those keywords are defined when
1012
Added:
the document template is populated. We can nevertheless always
1013
Added:
access those properties and edit them manually, with a simple
1014
Added:
keyboard shortcut (cf. Section [[Open Org mode document properties]]).
986
1015
987
1016
*** Document properties
988
1017
@@ -1022,8 +1051,8 @@
1022
1051
1023
1052
*** Timestamps
1024
1053
1025
Removed:
More literary timestamps are exported to LaTeX using the following custom
1026
Removed:
format:
1054
Added:
More literary timestamps are exported to LaTeX using the following
1055
Added:
custom format:
1027
1056
1028
1057
#+BEGIN_SRC emacs-lisp :tangle yes
1029
1058
(setq org-time-stamp-custom-formats
@@ -1032,8 +1061,8 @@
1032
1061
1033
1062
** Programming a Smart Documents
1034
1063
1035
Removed:
The following languages can be used inside =SRC= blocks, in view of being
1036
Removed:
executed by the Org Babel backend upon document export.
1064
Added:
The following languages can be used inside =SRC= blocks, in view
1065
Added:
of being executed by the Org Babel backend upon document export.
1037
1066
1038
1067
#+BEGIN_SRC emacs-lisp :tangle yes
1039
1068
(setq org-babel-load-languages
@@ -1054,31 +1083,33 @@
1054
1083
1055
1084
** Agenda
1056
1085
1057
Removed:
The agenda displays a chronological list of headings across all agenda files
1058
Removed:
for which the heading or body contain a matching =org-time-stamp=.[fn::An
1059
Removed:
=org-time-stamp= can be inserted with ~C-c .~ (period)]
1086
Added:
The agenda displays a chronological list of headings across all
1087
Added:
agenda files for which the heading or body contain a matching
1088
Added:
=org-time-stamp=.[fn::An =org-time-stamp= can be inserted with
1089
Added:
~C-c .~ (period)]
1060
1090
1061
1091
We open the agenda in a separate window.
1062
1092
1063
1093
#+BEGIN_SRC emacs-lisp :tangle yes
1064
Removed:
(setq org-agenda-window-setup 'other-frame)
1094
Added:
(setq org-agenda-window-setup 'other-frame)
1065
1095
#+END_SRC
1066
1096
1067
1097
** LaTeX export
1068
1098
1069
Removed:
We'll be compiling our documents with LuaTeX. This will afford us some
1070
Removed:
future-proofing, since it was designated as the successor to pdfTeX by the
1071
Removed:
latter's creators.
1099
Added:
We'll be compiling our documents with LuaTeX. This will afford us
1100
Added:
some future-proofing, since it was designated as the successor to
1101
Added:
pdfTeX by the latter's creators.
1072
1102
1073
Removed:
First, we define the command executed when an Org file is exported to
1074
Removed:
LaTeX. We'll use =latexmk=, the Perl script which automagically runs binaries
1075
Removed:
related to LaTeX in the correct order and the right amount of times.
1103
Added:
First, we define the command executed when an Org file is exported
1104
Added:
to LaTeX. We'll use =latexmk=, the Perl script which automagically
1105
Added:
runs binaries related to LaTeX in the correct order and the right
1106
Added:
amount of times.
1076
1107
1077
1108
Options and why we need them:
1078
1109
- ~-shell-excape~ :: required by minted to color source blocks
1079
1110
- ~-pdflatex=lualatex~ :: we use lualatex to generate our PDF
1080
Removed:
- ~-interaction=nonstopmode~ :: go as far as possible without prompting user
1081
Removed:
for input
1111
Added:
- ~-interaction=nonstopmode~ :: go as far as possible without
1112
Added:
prompting user for input
1082
1113
1083
1114
#+BEGIN_SRC emacs-lisp :tangle yes
1084
1115
(setq org-latex-pdf-process
@@ -1089,9 +1120,9 @@
1089
1120
1090
1121
*** Exporting timestamps
1091
1122
1092
Removed:
We customize the format for org time stamps to make them appear monospaced in
1093
Removed:
our exported LaTeX documents. This makes them visually distinguishable from
1094
Removed:
body text.
1123
Added:
We customize the format for org time stamps to make them appear
1124
Added:
monospaced in our exported LaTeX documents. This makes them
1125
Added:
visually distinguishable from body text.
1095
1126
1096
1127
#+BEGIN_SRC emacs-lisp :tangle yes
1097
1128
(setq org-latex-active-timestamp-format
@@ -1102,7 +1133,8 @@
1102
1133
1103
1134
*** LaTeX packages
1104
1135
1105
Removed:
The following packages are loaded for every time we export to LaTeX.
1136
Added:
The following packages are loaded for every time we export to
1137
Added:
LaTeX.
1106
1138
1107
1139
#+BEGIN_SRC emacs-lisp :tangle yes
1108
1140
(setq org-latex-packages-alist
@@ -1120,8 +1152,8 @@
1120
1152
1121
1153
*** Colored source blocks in PDF export
1122
1154
1123
Removed:
Little bonus for GNU/Linux users: syntax highlighting for source code blocks in
1124
Removed:
LaTeX exports.
1155
Added:
Little bonus for GNU/Linux users: syntax highlighting for source
1156
Added:
code blocks in LaTeX exports.
1125
1157
1126
1158
#+BEGIN_SRC emacs-lisp :tangle yes
1127
1159
(when (string-equal system-type "gnu/linux")
@@ -1135,9 +1167,9 @@
1135
1167
1136
1168
*** Cleaning directory after export
1137
1169
1138
Removed:
Now, we set the files to be deleted when a LaTeX \rightarrow PDF compilation
1139
Removed:
occurs. We only care about two files, in the end: the Org mode file for
1140
Removed:
edition, and the PDF for distribution.
1170
Added:
Now, we set the files to be deleted when a LaTeX \rightarrow PDF
1171
Added:
compilation occurs. We only care about two files, in the end: the
1172
Added:
Org mode file for edition, and the PDF for distribution.
1141
1173
1142
1174
#+BEGIN_SRC emacs-lisp :tangle yes
1143
1175
(setq org-latex-logfiles-extensions
@@ -1149,16 +1181,16 @@
1149
1181
1150
1182
*** Chronological diary entries
1151
1183
1152
Removed:
By default, Org agenda inserts diary entries as the first under the selected
1153
Removed:
date. It is preferable to insert entries in the order that they were recorded,
1154
Removed:
i.e. chronologically.
1184
Added:
By default, Org agenda inserts diary entries as the first under
1185
Added:
the selected date. It is preferable to insert entries in the order
1186
Added:
that they were recorded, i.e. chronologically.
1155
1187
1156
1188
#+BEGIN_SRC emacs-lisp :tangle yes
1157
1189
(setq org-agenda-insert-diary-strategy 'date-tree-last)
1158
1190
#+END_SRC
1159
1191
1160
Removed:
What follows is an additional document class structures that can be exported in
1161
Removed:
LaTeX.
1192
Added:
What follows is an additional document class structures that can
1193
Added:
be exported in LaTeX.
1162
1194
1163
1195
#+BEGIN_SRC emacs-lisp :tangle no
1164
1196
;; (add-to-list 'org-latex-classes
@@ -1172,23 +1204,25 @@
1172
1204
1173
1205
*** Table of contents
1174
1206
1175
Removed:
By default, body text can immediately follow the table of contents. It is
1176
Removed:
however cleaner to separate table of contents with the rest of the work.
1207
Added:
By default, body text can immediately follow the table of
1208
Added:
contents. It is however cleaner to separate table of contents with
1209
Added:
the rest of the work.
1177
1210
1178
1211
#+BEGIN_SRC emacs-lisp :tangle yes
1179
1212
(setq org-latex-toc-command "\\tableofcontents\\clearpage")
1180
1213
#+END_SRC
1181
1214
1182
Removed:
The following makes =TODO= items appear red and =CLOSED= items appear green in
1183
Removed:
Org's LaTeX exports. Very stylish, much flair!
1215
Added:
The following makes =TODO= items appear red and =CLOSED= items
1216
Added:
appear green in Org's LaTeX exports. Very stylish, much flair!
1184
1217
1185
1218
** TODO Org links
1186
1219
1187
Removed:
This is a mind-bending capacity of Org mode: we can assign arbitrary functions
1188
Removed:
to be executed when a user follows an Org link. Org links appear like
1189
Removed:
hyperlinks both in buffers and PDF exports---e.g. the following link to this
1190
Removed:
very section, Section [[Org links]]---but their in-buffer behavior can be
1191
Removed:
arbitrarily assigned.
1220
Added:
This is a mind-bending capacity of Org mode: we can assign
1221
Added:
arbitrary functions to be executed when a user follows an Org
1222
Added:
link. Org links appear like hyperlinks both in buffers and PDF
1223
Added:
exports---e.g. the following link to this very section, Section
1224
Added:
[[Org links]]---but their in-buffer behavior can be arbitrarily
1225
Added:
assigned.
1192
1226
1193
1227
#+BEGIN_SRC emacs-lisp :tangle no
1194
1228
(org-add-link-type
@@ -1204,21 +1238,23 @@
1204
1238
1205
1239
* One-click workflows
1206
1240
1207
Removed:
In this section, we'll implement useful one-click workflows. It comes later
1208
Removed:
keybinding definitions for two reasons:
1241
Added:
In this section, we'll implement useful one-click workflows. It
1242
Added:
comes later keybinding definitions for two reasons:
1209
1243
1210
1244
1. To a new user, keybindings are more important than the precise
1211
Removed:
implementation of the bound function---it is more important to know how to
1212
Removed:
drive a car than how a car works.
1213
Removed:
2. If the following subsections share the same name as the keybinding
1214
Removed:
subsection (Section [[Keyboard shortcuts]]), the links will resolve to the
1215
Removed:
earliest heading in the document, i.e. the keybinding subsection and not the
1216
Removed:
subsection describing the `one-click workflow'.
1245
Added:
implementation of the bound function---it is more important to
1246
Added:
know how to drive a car than how a car works.
1247
Added:
2. If the following subsections share the same name as the
1248
Added:
keybinding subsection (Section [[Keyboard shortcuts]]), the links
1249
Added:
will resolve to the earliest heading in the document, i.e. the
1250
Added:
keybinding subsection and not the subsection describing the
1251
Added:
`one-click workflow'.
1217
1252
1218
1253
** TODO Export to PDF
1219
1254
1220
Removed:
This reimplements the most common Org mode export: Org \rightarrow LaTeX
1221
Removed:
\rightarrow PDF. The binding is defined in Section [[Export to PDF]].
1255
Added:
This reimplements the most common Org mode export: Org \rightarrow
1256
Added:
LaTeX \rightarrow PDF. The binding is defined in Section [[Export to
1257
Added:
PDF]].
1222
1258
1223
1259
#+BEGIN_SRC emacs-lisp :tangle yes
1224
1260
(defun sd-org-quick-export ()
@@ -1250,8 +1286,8 @@
1250
1286
1251
1287
* Editing preferences
1252
1288
1253
Removed:
These customizations enhance editor usability. They also encompass cosmetic
1254
Removed:
changes not brought about a specific package.
1289
Added:
These customizations enhance editor usability. They also encompass
1290
Added:
cosmetic changes not brought about a specific package.
1255
1291
1256
1292
** Editor
1257
1293
@@ -1266,8 +1302,8 @@
1266
1302
1267
1303
*** Recent files
1268
1304
1269
Removed:
The keybinding for opening a recently visited file is described in paragraph
1270
Removed:
[[Open a recently visited file]].
1305
Added:
The keybinding for opening a recently visited file is described in
1306
Added:
paragraph [[Open a recently visited file]].
1271
1307
1272
1308
#+BEGIN_SRC emacs-lisp :tangle yes
1273
1309
(recentf-mode 1)
@@ -1294,9 +1330,9 @@
1294
1330
:sd-unpack-path: sd-icons.el
1295
1331
:END:
1296
1332
1297
Removed:
We start by defining some icons we wish to include in our user interface. Emacs
1298
Removed:
allows the usage of GIF images---this paves the way for UI elements which may be
1299
Removed:
animated.
1333
Added:
We start by defining some icons we wish to include in our user
1334
Added:
interface. Emacs allows the usage of GIF images---this paves the
1335
Added:
way for UI elements which may be animated.
1300
1336
1301
1337
#+BEGIN_SRC emacs-lisp :tangle yes
1302
1338
(defvar sd-icons-blue-ellipsis (create-image
@@ -1316,8 +1352,8 @@
1316
1352
**** TODO Header line
1317
1353
# Figure out how to do 'keymap cleanly
1318
1354
1319
Removed:
In Org mode, the document header line will be the title of the document we are
1320
Removed:
working on currently.
1355
Added:
In Org mode, the document header line will be the title of the
1356
Added:
document we are working on currently.
1321
1357
1322
1358
#+BEGIN_SRC emacs-lisp :tangle yes
1323
1359
(setq sd-header-gnu-linux
@@ -1404,8 +1440,8 @@
1404
1440
1405
1441
*** Column filling
1406
1442
1407
Removed:
A line of text is considered ``filled'' when it reaches 79 characters in
1408
Removed:
length.
1443
Added:
A line of text is considered ``filled'' when it reaches 79
1444
Added:
characters in length.
1409
1445
1410
1446
#+BEGIN_SRC emacs-lisp :tangle yes
1411
1447
(setq-default fill-column 79)
@@ -1418,8 +1454,9 @@
1418
1454
1419
1455
*** Beautiful symbols
1420
1456
1421
Removed:
We want the Emacs Lisp keyword =lambda= to be rendered as \lambda within the
1422
Removed:
editor. This is mostly for a subjective ``cool'' factor.
1457
Added:
We want the Emacs Lisp keyword =lambda= to be rendered as \lambda
1458
Added:
within the editor. This is mostly for a subjective ``cool''
1459
Added:
factor.
1423
1460
1424
1461
#+BEGIN_SRC emacs-lisp :tangle yes
1425
1462
(global-prettify-symbols-mode 1)
@@ -1427,8 +1464,8 @@
1427
1464
1428
1465
*** Org mode sugar
1429
1466
1430
Removed:
Let's pimp out the appearance of our text in Org mode. First, we prettify
1431
Removed:
checkbox lists.
1467
Added:
Let's pimp out the appearance of our text in Org mode. First, we
1468
Added:
prettify checkbox lists.
1432
1469
1433
1470
#+BEGIN_SRC emacs-lisp :tangle yes
1434
1471
(when (string-equal system-type "gnu/linux")
@@ -1450,10 +1487,10 @@
1450
1487
1451
1488
*** Electric modes
1452
1489
1453
Removed:
Electricity is a very important technology. In Emacs jargon, ``electric'' modes
1454
Removed:
tend to automate behaviors or present some elegant simplification to a
1455
Removed:
workflow.[fn::More information can be found at
1456
Removed:
[[https://www.emacswiki.org/emacs/Electricity]].]
1490
Added:
Electricity is a very important technology. In Emacs jargon,
1491
Added:
``electric'' modes tend to automate behaviors or present some
1492
Added:
elegant simplification to a workflow.[fn::More information can be
1493
Added:
found at [[https://www.emacswiki.org/emacs/Electricity]].]
1457
1494
1458
1495
#+BEGIN_SRC emacs-lisp :tangle yes
1459
1496
(electric-pair-mode) ; Certain character pairs are automatically completed.
@@ -1476,8 +1513,9 @@
1476
1513
1477
1514
* Themes
1478
1515
1479
Removed:
Without a carefully designed theme, our editor would become unusable. Thus, we
1480
Removed:
describe two themes that were developed purposefully and iteratively.
1516
Added:
Without a carefully designed theme, our editor would become
1517
Added:
unusable. Thus, we describe two themes that were developed
1518
Added:
purposefully and iteratively.
1481
1519
1482
1520
#+BEGIN_SRC emacs-lisp :tangle yes
1483
1521
(setq custom-theme-directory (concat user-emacs-directory "themes/"))
@@ -1491,11 +1529,12 @@
1491
1529
1492
1530
*** Colors
1493
1531
1494
Removed:
The default face is a black foreground on a white background, this matches MS
1495
Removed:
Word. We are striving for a simple, intuitive color scheme.
1532
Added:
The default face is a black foreground on a white background, this
1533
Added:
matches MS Word. We are striving for a simple, intuitive color
1534
Added:
scheme.
1496
1535
1497
Removed:
Most of the visual cues derived from color are identical in both light and dark
1498
Removed:
themes (Table [[theme-color-1]]).
1536
Added:
Most of the visual cues derived from color are identical in both
1537
Added:
light and dark themes (Table [[theme-color-1]]).
1499
1538
1500
1539
#+NAME: theme-color-1
1501
1540
#+CAPTION[Light and dark themes' colors]: Light and dark themes' colors.
@@ -1518,9 +1557,9 @@
1518
1557
1519
1558
*** Cursors
1520
1559
1521
Removed:
In order to imitate other modern text editors, we resort to a blinking bar
1522
Removed:
cursor. We choose red, the most captivating color, because the cursor is
1523
Removed:
arguably the region on our screen:
1560
Added:
In order to imitate other modern text editors, we resort to a
1561
Added:
blinking bar cursor. We choose red, the most captivating color,
1562
Added:
because the cursor is arguably the region on our screen:
1524
1563
1525
1564
1. most often looked at;
1526
1565
2. most often searched when lost.
@@ -1539,8 +1578,8 @@
1539
1578
1540
1579
**** Currently used /chad fonts/
1541
1580
1542
Removed:
- Hack[fn::https://sourcefoundry.org/hack/] :: ~default~ and ~fixed-pitch~,
1543
Removed:
default code font
1581
Added:
- Hack[fn::https://sourcefoundry.org/hack/] :: ~default~ and
1582
Added:
~fixed-pitch~, default code font
1544
1583
- Legible, modern monospace font
1545
1584
- Strict, sharp, uncompromising
1546
1585
- Public Sans[fn::https://public-sans.digital.gov/] :: ~variable-pitch~,
@@ -1548,8 +1587,8 @@
1548
1587
- Very modern yet neutral
1549
1588
- Designed for the U.S. government
1550
1589
- Exceptional color on screen
1551
Removed:
- Hermit[fn::https://pcaro.es/p/hermit/] :: ~org-block~, anything Org/meta in
1552
Removed:
general
1590
Added:
- Hermit[fn::https://pcaro.es/p/hermit/] :: ~org-block~, anything
1591
Added:
Org/meta in general
1553
1592
- Slightly wider than Hack
1554
1593
- More opinionated shapes
1555
1594
- Very legible parentheses, very useful for Emacs Lisp!
@@ -1615,6 +1654,6 @@
1615
1654
1616
1655
* Conclusion
1617
1656
1618
Removed:
In this configuration file, we described a series of customization steps taken
1619
Removed:
to make Emacs more palatable to modern IDE users.
1657
Added:
In this configuration file, we described a series of customization
1658
Added:
steps taken to make Emacs more palatable to modern IDE users.
1620
1659