summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBlendoit <blendoit@gmail.com>2020-11-10 19:09:22 -0800
committerBlendoit <blendoit@gmail.com>2020-11-10 19:09:22 -0800
commit8912aaddff932e2c12b0ac399d1df55e9dffded8 (patch)
tree49e305681abfa0869d166b29539fb77e318498e0
parent0939fec6f4360848c16e691973a139166815ff5e (diff)
Fill column is now `66'.
-rw-r--r--smart-documents.org493
1 files changed, 266 insertions, 227 deletions
diff --git a/smart-documents.org b/smart-documents.org
index 7722df6..853e637 100644
--- a/smart-documents.org
+++ b/smart-documents.org
@@ -11,42 +11,46 @@
#+LATEX_HEADER: \usepackage{lettrine}
#+LATEX: \begin{abstract}
-The idea of /Smart Documents/ came to me as I was reflecting on how to improve
-the document creation process in my workplace. The GNU Emacs editor had
-captured my imagination and I wanted to create an accessible and highly
-productive text editor to benefit my organization. In this paper, I'll lay out
-my vision for the /Smart Document/, a file containing both text destined to the
-reader, and code describing how to update, validate, and present this text;
-then, I'll weave my personal GNU Emacs customizations with a tutorial. This
-paper is a /Smart Document/ itself!
+The idea of /Smart Documents/ came to me as I was reflecting on
+how to improve the document creation process in my workplace. The
+GNU Emacs editor had captured my imagination and I wanted to
+create an accessible and highly productive text editor to benefit
+my organization. In this paper, I'll lay out my vision for the
+/Smart Document/, a file containing both text destined to the
+reader, and code describing how to update, validate, and present
+this text; then, I'll weave my personal GNU Emacs customizations
+with a tutorial. This paper is a /Smart Document/ itself!
#+LATEX: \end{abstract}
* Introduction
-GNU Emacs is most often used as a text editor. It would be unfair to say it is
-just that, because Emacs is capable of so much more. The utmost level of
-customization is afforded by enabling the user to rewrite /any/ part of the
-source code and observe the editor's modified behavior in real time. Since its
-inception in 1984, GNU Emacs has grown to be much more than a full-featured,
-high-productivity text editor---new /modes/ have been written to interact with
-hundreds of file formats, including =.txt=, =.pdf=, =.jpg=, =.csv=, and =.zip=
-just to name a few. This paper itself was written in /Org mode/, a collection
-of functions enabling the harmonious mixing of code and comments in view of
-publication: this is the endgame of /literate programming/, and the basis of my
+GNU Emacs is most often used as a text editor. It would be unfair
+to say it is just that, because Emacs is capable of so much
+more. The utmost level of customization is afforded by enabling
+the user to rewrite /any/ part of the source code and observe the
+editor's modified behavior in real time. Since its inception in
+1984, GNU Emacs has grown to be much more than a full-featured,
+high-productivity text editor---new /modes/ have been written to
+interact with hundreds of file formats, including =.txt=, =.pdf=,
+=.jpg=, =.csv=, and =.zip= just to name a few. This paper itself
+was written in /Org mode/, a collection of functions enabling the
+harmonious mixing of code and comments in view of publication:
+this is the endgame of /literate programming/, and the basis of my
vision for /Smart Documents/.
-The following sections were laid out very deliberately. When we start Emacs,
-the source code blocks contained in this document are evaluated
-sequentially---our editing environment is constructed in real time as we
-execute the blocks in order. For instance, we only begin loading packages once
-we ensured ~use-package~ is working properly.[fn::For more information on the
-detailed steps Emacs takes upon starting, refer to
+The following sections were laid out very deliberately. When we
+start Emacs, the source code blocks contained in this document are
+evaluated sequentially---our editing environment is constructed in
+real time as we execute the blocks in order. For instance, we only
+begin loading packages once we ensured ~use-package~ is working
+properly.[fn::For more information on the detailed steps Emacs
+takes upon starting, refer to
[[https://www.gnu.org/software/emacs/manual/html_node/elisp/Startup-Summary.html]].]
Customizing Emacs goes far, far beyond rewriting sections of this
-document---feel free to experiment and discover. Here are three commands that
-will help you understand all the symbols in this file, if you are browsing this
-paper within Emacs itself:
+document---feel free to experiment and discover. Here are three
+commands that will help you understand all the symbols in this
+file, if you are browsing this paper within Emacs itself:
- ~C-h f~ :: describe function
- ~C-h v~ :: describe variable
@@ -102,9 +106,9 @@ the first time.
** TODO User details
-One advantage of working with /Smart Documents/ is that they can automatically
-be populated with our details in the header, footer, or other appropriate
-element.
+One advantage of working with /Smart Documents/ is that they can
+automatically be populated with our details in the header, footer,
+or other appropriate element.
#+NAME: user-details-get
#+BEGIN_SRC emacs-lisp
@@ -151,12 +155,13 @@ https://git-scm.com/download/win]
:END:
The contents of this Section was automatically moved to
-=~/.emacs.d/init.el=.
-Use `sd-pack-section' to copy the contents back into this section.
+=~/.emacs.d/init.el=. Use `sd-pack-section' to copy the contents
+back into this section.
-This is the very first user-editable file loaded by Emacs.[fn::This feature
-became available in version 27.1.] In it, we disable GUI elements that would
-otherwise be loaded and displayed once Emacs is ready to accept user input.
+This is the very first user-editable file loaded by
+Emacs.[fn::This feature became available in version 27.1.] In it,
+we disable GUI elements that would otherwise be loaded and
+displayed once Emacs is ready to accept user input.
It can be found here: [[file:early-init.el]]
@@ -166,9 +171,9 @@ It can be found here: [[file:early-init.el]]
:END:
#+BEGIN_QUOTE
-Traditionally, file =~/.emacs= is used as the init file, although Emacs also
-looks at =~/.emacs.el=, =~/.emacs.d/init.el=, =~/.config/emacs/init.el=, or
-other locations.
+Traditionally, file =~/.emacs= is used as the init file, although
+Emacs also looks at =~/.emacs.el=, =~/.emacs.d/init.el=,
+=~/.config/emacs/init.el=, or other locations.
From the GNU
website[fn::[[https://www.gnu.org/software/emacs/manual/html_node/emacs/Init-File.html]]]
@@ -180,8 +185,9 @@ If no file is found, Emacs then loads in its purely vanilla state.
** Profiling --- start
-We start the profiler now , and will interrupt it in Section [[Profiling ---
-stop]]. We will then present profiling report in Section [[Profiling --- report]].
+We start the profiler now , and will interrupt it in Section
+[[Profiling --- stop]]. We will then present profiling report in
+Section [[Profiling --- report]].
#+NAME: profiler-start
#+BEGIN_SRC emacs-lisp :tangle yes
@@ -215,15 +221,17 @@ We begin by defining a function to open this very file.
** Meta-files
-In this section, we'll be tidying up the =.emacs.d/= directory---by default,
-many Emacs packages create files useful for themselves in our
-~user-emacs-directory~. This leads to undesirable clutter. Certain packages
-create files that log recently visited files ([[Recently visited files]]); log
-location of known projects ([[Projects' bookmarks]]); log location in recently
-visited files ([[Location in previously visited file]]) The commonality
-between all these files is that they tend to reference... other files. Thus, I
-decided to refer to them as meta-files. First, let's designate a folder to collect
-our meta-files together:
+In this section, we'll be tidying up the =.emacs.d/=
+directory---by default, many Emacs packages create files useful
+for themselves in our ~user-emacs-directory~. This leads to
+undesirable clutter. Certain packages create files that log
+recently visited files ([[Recently visited files]]); log location of
+known projects ([[Projects' bookmarks]]); log location in recently
+visited files ([[Location in previously visited file]]) The
+commonality between all these files is that they tend to
+reference... other files. Thus, I decided to refer to them as
+meta-files. First, let's designate a folder to collect our
+meta-files together:
#+BEGIN_SRC emacs-lisp :tangle yes
(setq sd-meta-files-location (concat user-emacs-directory "meta/"))
@@ -255,9 +263,9 @@ our meta-files together:
*** Custom file
-Load settings created automatically by GNU Emacs Custom. (For example, any
-clickable option/toggle is saved here.) Useful for fooling around with ~M-x
-customize-group <package>~.
+Load settings created automatically by GNU Emacs Custom. (For
+example, any clickable option/toggle is saved here.) Useful for
+fooling around with ~M-x customize-group <package>~.
#+NAME: custom-file-location
#+BEGIN_SRC emacs-lisp :tangle yes
@@ -299,8 +307,9 @@ We also set the dimensions of subsequent frames:
*** GNU/Linux
-These settings affect the first and subsequent frames spawned by Emacs in
-GNU/Linux. Frame transparency increases when focus is lost.
+These settings affect the first and subsequent frames spawned by
+Emacs in GNU/Linux. Frame transparency increases when focus is
+lost.
#+BEGIN_SRC emacs-lisp :tangle yes
(when (and (display-graphic-p) (string-equal system-type "gnu/linux"))
@@ -310,11 +319,12 @@ GNU/Linux. Frame transparency increases when focus is lost.
** Secrets
-The code contained in the =secrets.org= file is loaded by Emacs, but not
-rendered in this PDF for the sake of privacy. It contains individually
-identifying information such as names and e-mail addresses, which are used to
-populate Org templates (Section [[~org-mode~]]). You need to create this
-=secrets.org= file, as it is ignored by =git= by default.
+The code contained in the =secrets.org= file is loaded by Emacs,
+but not rendered in this PDF for the sake of privacy. It contains
+individually identifying information such as names and e-mail
+addresses, which are used to populate Org templates (Section
+[[~org-mode~]]). You need to create this =secrets.org= file, as it is
+ignored by =git= by default.
#+BEGIN_SRC emacs-lisp :tangle yes
(let ((secrets (concat user-emacs-directory "secrets.org")))
@@ -323,20 +333,22 @@ populate Org templates (Section [[~org-mode~]]). You need to create this
* Keyboard shortcuts
-The following bindings strive to further enhance CUA mode.[fn::Common User
-Access. This is a term coined by IBM which has influenced user navigation cues
-on all modern desktop OSes. From IBM's CUA, we get the =Ctrl-c= and =Ctrl-v=
-keyboard shortcuts.]
+The following bindings strive to further enhance CUA
+mode.[fn::Common User Access. This is a term coined by IBM which
+has influenced user navigation cues on all modern desktop
+OSes. From IBM's CUA, we get the =Ctrl-c= and =Ctrl-v= keyboard
+shortcuts.]
#+BEGIN_SRC emacs-lisp :tangle yes
(cua-mode)
#+END_SRC
-What follows are the most useful keybindings, as well as the keybindings to the
-functions we defined ourselves. It doesn't matter if we haven't defined the
-functions themselves yet; Emacs will accept a keybinding for any symbol and
-does not check if the symbol's function definition exists, until the keybinding
-is pressed.
+What follows are the most useful keybindings, as well as the
+keybindings to the functions we defined ourselves. It doesn't
+matter if we haven't defined the functions themselves yet; Emacs
+will accept a keybinding for any symbol and does not check if the
+symbol's function definition exists, until the keybinding is
+pressed.
** Files
@@ -466,12 +478,13 @@ It seems that starting with Emacs 27.1, Control + mousewheel works.
** Navigation
-=Alt= (=Meta=) is the privileged key for motion in a buffer. It is followed by
-an optional numerical argument, and a movement command. You may navigate in a
-buffer by keeping =Alt= pressed, optionally inputting a number from the keypad
-or number row, then pressing any of the following movement keys: =j=, =k=, =h=,
-and =l=. You will move in that direction in the amount of the numerical
-argument.
+=Alt= (=Meta=) is the privileged key for motion in a buffer. It is
+followed by an optional numerical argument, and a movement
+command. You may navigate in a buffer by keeping =Alt= pressed,
+optionally inputting a number from the keypad or number row, then
+pressing any of the following movement keys: =j=, =k=, =h=, and
+=l=. You will move in that direction in the amount of the
+numerical argument.
#+NAME: keybinding-navigation
#+CAPTION[Navigation keybindings]: Navigation keybindings.
@@ -532,13 +545,15 @@ We prevent Org mode from overriding preferred navigation keys.
** One-click workflows
-A major advantage of the Emacs document production system: arbitrarily
-complicated functions can be assigned to very simple keybindings. This means we
-can automate workflows up to a pretty absurd level.
+A major advantage of the Emacs document production system:
+arbitrarily complicated functions can be assigned to very simple
+keybindings. This means we can automate workflows up to a pretty
+absurd level.
*** Export to PDF
-PDF is probably the most prevalent file format for sharing static documents.
+PDF is probably the most prevalent file format for sharing static
+documents.
**** Document
@@ -570,7 +585,8 @@ Not only indent, but also clean up superfluous newlines.
* Packages
-Packages are collections of =.el= files providing added functionality to Emacs.
+Packages are collections of =.el= files providing added
+functionality to Emacs.
** Meta
@@ -594,7 +610,8 @@ List of package archives.
*** TODO Convenient package update
-One-function rollup of upgradeable package tagging, download and lazy install.
+One-function rollup of upgradeable package tagging, download and
+lazy install.
#+BEGIN_SRC emacs-lisp :tangle yes
@@ -602,8 +619,8 @@ One-function rollup of upgradeable package tagging, download and lazy install.
*** ~use-package~
-We ensure =use-package= is installed, as well as all packages described in this
-configuration file.
+We ensure =use-package= is installed, as well as all packages
+described in this configuration file.
#+BEGIN_SRC emacs-lisp :tangle yes
(unless (package-installed-p 'use-package)
@@ -619,9 +636,10 @@ configuration file.
Forgive me, for I have sinned.
-This is the 2^{nd} most significant customization after ~org-mode~. Enabling
-~evil-mode~ completely changes editing keys.[fn::For more information on =vi=
-keybindings, visit [[https://hea-www.harvard.edu/~fine/Tech/vi.html]].]
+This is the 2^{nd} most significant customization after
+~org-mode~. Enabling ~evil-mode~ completely changes editing
+keys.[fn::For more information on =vi= keybindings, visit
+[[https://hea-www.harvard.edu/~fine/Tech/vi.html]].]
#+BEGIN_SRC emacs-lisp :tangle yes
(use-package evil)
@@ -631,13 +649,14 @@ keybindings, visit [[https://hea-www.harvard.edu/~fine/Tech/vi.html]].]
** Spelling, completion, and snippets
-The following customizations open the doors to vastly increased typing speed
-and accuracy.
+The following customizations open the doors to vastly increased
+typing speed and accuracy.
*** Syntax checking
-We require a package to highlight syntax errors and warnings. The ~flycheck~
-package ensures we are aware of all our code's syntactical shortcomings.
+We require a package to highlight syntax errors and warnings. The
+~flycheck~ package ensures we are aware of all our code's
+syntactical shortcomings.
#+NAME: flycheck
#+BEGIN_SRC emacs-lisp :tangle yes
@@ -655,21 +674,22 @@ package ensures we are aware of all our code's syntactical shortcomings.
*** Insert template from keyword
-Thanks to ~yasnippet~, we can type certain keywords, then press =TAB=, to
-automatically insert a predefined text snippet. We can then navigate through
-the snippet by using =<tab>= (next field) and =<backtab>= (previous
-field).[fn::=<backtab>= is synonymous with pressing shift-tab.]
+Thanks to ~yasnippet~, we can type certain keywords, then press
+=TAB=, to automatically insert a predefined text snippet. We can
+then navigate through the snippet by using =<tab>= (next field)
+and =<backtab>= (previous field).[fn::=<backtab>= is synonymous
+with pressing shift-tab.]
-For instance: typing =src= then pressing =TAB= will expand the keyword to the
-following text:
+For instance: typing =src= then pressing =TAB= will expand the
+keyword to the following text:
: #+BEGIN_SRC emacs-lisp :tangle yes
:
: #+END_SRC
-We notice that emacs-lisp is highlighted---this is the first modifiable
-field. Many clever programming tricks can be performed with ~yasnippet~ to save
-us a ton of time with boilerplate text!
+We notice that emacs-lisp is highlighted---this is the first
+modifiable field. Many clever programming tricks can be performed
+with ~yasnippet~ to save us a ton of time with boilerplate text!
#+NAME: yasnippet
#+BEGIN_SRC emacs-lisp :tangle yes
@@ -696,8 +716,8 @@ us a ton of time with boilerplate text!
*** Versioning of files
-Wonderful Git porcelain for Emacs. Enables the administration of a Git
-repository in a pain-free way.
+Wonderful Git porcelain for Emacs. Enables the administration of a
+Git repository in a pain-free way.
#+BEGIN_SRC emacs-lisp :tangle yes
(use-package magit
@@ -724,9 +744,9 @@ This enables us to better manage our =.git= projects.
*** Jump to symbol's definition
-~dumb-jump~ is a reliable symbol definition finder. It uses different matching
-algorithms and heuristics to provide a very educated guess on the location of a
-symbol's definition.
+~dumb-jump~ is a reliable symbol definition finder. It uses
+different matching algorithms and heuristics to provide a very
+educated guess on the location of a symbol's definition.
#+BEGIN_SRC emacs-lisp :tangle yes
(use-package dumb-jump)
@@ -752,7 +772,9 @@ symbol's definition.
**** Smartly suggesting interactive search matches
-Wonderful counsellor!
+And he will be called Wonderful *Counselor*, Mighty God,
+Everlasting Father, Prince of Peace.
+
#+BEGIN_SRC emacs-lisp :tangle yes
(use-package counsel
@@ -798,8 +820,8 @@ Python is included by default on most Linux distributions.
*** Interacting with PDFs
-Org mode shines particularly when exporting to PDF---Org files can reliably be
-shared and exported to PDF in a reproducible fashion.
+Org mode shines particularly when exporting to PDF---Org files can
+reliably be shared and exported to PDF in a reproducible fashion.
#+BEGIN_SRC emacs-lisp :tangle yes
(use-package pdf-tools)
@@ -808,9 +830,10 @@ shared and exported to PDF in a reproducible fashion.
*** Accounting
-Ledger is a creation of John Wiegley's. It enables double-entry accounting in a
-simple plaintext format, and reliable verification of account balances through
-time.[fn::For more information, visit https://www.ledger-cli.org/.]
+Ledger is a creation of John Wiegley's. It enables double-entry
+accounting in a simple plaintext format, and reliable verification
+of account balances through time.[fn::For more information, visit
+https://www.ledger-cli.org/.]
#+BEGIN_SRC emacs-lisp :tangle yes
(use-package ledger-mode
@@ -819,8 +842,8 @@ time.[fn::For more information, visit https://www.ledger-cli.org/.]
("C-c C" . ledger-mode-clean-buffer))
#+END_SRC
-These reports can be generated within Emacs. It is quite useful to pipe their
-output to an automated ``smart document''.
+These reports can be generated within Emacs. It is quite useful to
+pipe their output to an automated ``smart document''.
#+BEGIN_SRC emacs-lisp :tangle yes
(setq ledger-reports
@@ -880,7 +903,8 @@ Get inspiration from ~ibuffer-sidebar~ and create a better sidebar.
*** Highlight ``color keywords'' in their color
-This highlights hexadecimal numbers which look like colors, in that same color.
+This highlights hexadecimal numbers which look like colors, in
+that same color.
#+BEGIN_SRC emacs-lisp :tangle yes
(use-package rainbow-mode
@@ -890,33 +914,35 @@ This highlights hexadecimal numbers which look like colors, in that same color.
*** +UTF-8 bullet points in =Org mode=+
-This section was removed, as it is more explicit to display the headline
-character for what it is: a collection of at least one asterisk.
+This section was removed, as it is more explicit to display the
+headline character for what it is: a collection of at least one
+asterisk.
* ~org-mode~
-Org mode is so significant that this section of the paper deserves its own
-introduction.
+Org mode is so significant that this section of the paper deserves
+its own introduction.
** Introduction
-Phew, after all this initialization, I can finally introduce Org mode! I am so
-*excited*.
+Phew, after all this initialization, I can finally introduce Org
+mode! I am so *excited*.
-Org mode replaces aword processor, a presentation creator, and a spreadsheet
-editor. The spreadsheet ability captures more than 80% use cases wherein one
-wishes to include a table in a text document destined for physical
-publication. (It is clear that Excel spreadsheets are /not/ destined for
-physical publication---simply attempt to print an Excel spreadsheet with the
-default settings.) In my opinion, Org mode matches all /useful/ features of
-the Microsoft Office suite 1-to-1.
+Org mode replaces aword processor, a presentation creator, and a
+spreadsheet editor. The spreadsheet ability captures more than 80%
+use cases wherein one wishes to include a table in a text document
+destined for physical publication. (It is clear that Excel
+spreadsheets are /not/ destined for physical publication---simply
+attempt to print an Excel spreadsheet with the default settings.)
+In my opinion, Org mode matches all /useful/ features of the
+Microsoft Office suite 1-to-1.
-What follows are customizations designed to make Org mode behave more like
-Microsoft Word. The end goal is, once again, to draw as many new users to Emacs
-as possible!
+What follows are customizations designed to make Org mode behave
+more like Microsoft Word. The end goal is, once again, to draw as
+many new users to Emacs as possible!
-Check out how much information Org mode keeps concerning the most recent
-header:
+Check out how much information Org mode keeps concerning the most
+recent header:
#+NAME: org-meta-info
#+BEGIN_SRC emacs-lisp :tangle no :results pp :exports both :cache yes
@@ -936,7 +962,8 @@ header:
*** Base folder
-Org base directory is in user home on GNU/Linux, or in =AppData= in MS Windows.
+Org base directory is in user home on GNU/Linux, or in =AppData=
+in MS Windows.
#+NAME: org-directory
#+BEGIN_SRC emacs-lisp :tangle yes
@@ -951,10 +978,11 @@ Org base directory is in user home on GNU/Linux, or in =AppData= in MS Windows.
** Org cosmetics
-First, we ensure the display of markup symbols for *bold*, /italic/,
-_underlined_ and +strikethrough+ text, and ensure our document appears indented
-upon loading.[fn::It /appears/ indented, but the underlying plaintext file does
-not contain tab characters!]
+First, we ensure the display of markup symbols for *bold*,
+/italic/, _underlined_ and +strikethrough+ text, and ensure our
+document appears indented upon loading.[fn::It /appears/ indented,
+but the underlying plaintext file does not contain tab
+characters!]
We then set values for many other Org-related cosmetic symbols.
@@ -968,21 +996,22 @@ We then set values for many other Org-related cosmetic symbols.
*** Dynamic numbering of headlines
-We enable the dynamic numbering of headlines in an Org buffer. We also set the
-numbering face to ~org-special-keyword~, which specifies a ~:background white~
-attribute. This is necessary because otherwise, the background of the numbering
-may be overridden by the ~TODO~ face attribute ~:background coral~.
+We enable the dynamic numbering of headlines in an Org buffer. We
+also set the numbering face to ~org-special-keyword~, which
+specifies a ~:background white~ attribute. This is necessary
+because otherwise, the background of the numbering may be
+overridden by the ~TODO~ face attribute ~:background coral~.
#+BEGIN_SRC emacs-lisp :tangle yes
(add-hook 'org-mode-hook 'org-num-mode)
(setq org-num-face 'org-special-keyword)
#+END_SRC
-By default, we hide Org document properties such as =#+TITLE=, =#+AUTHOR=, and
-=#+DATE=, because those keywords are defined when the document template is
-populated. We can nevertheless always access those properties and edit them
-manually, with a simple keyboard shortcut (cf. Section [[Open Org mode document
-properties]]).
+By default, we hide Org document properties such as =#+TITLE=,
+=#+AUTHOR=, and =#+DATE=, because those keywords are defined when
+the document template is populated. We can nevertheless always
+access those properties and edit them manually, with a simple
+keyboard shortcut (cf. Section [[Open Org mode document properties]]).
*** Document properties
@@ -1022,8 +1051,8 @@ properties]]).
*** Timestamps
-More literary timestamps are exported to LaTeX using the following custom
-format:
+More literary timestamps are exported to LaTeX using the following
+custom format:
#+BEGIN_SRC emacs-lisp :tangle yes
(setq org-time-stamp-custom-formats
@@ -1032,8 +1061,8 @@ format:
** Programming a Smart Documents
-The following languages can be used inside =SRC= blocks, in view of being
-executed by the Org Babel backend upon document export.
+The following languages can be used inside =SRC= blocks, in view
+of being executed by the Org Babel backend upon document export.
#+BEGIN_SRC emacs-lisp :tangle yes
(setq org-babel-load-languages
@@ -1054,31 +1083,33 @@ executed by the Org Babel backend upon document export.
** Agenda
-The agenda displays a chronological list of headings across all agenda files
-for which the heading or body contain a matching =org-time-stamp=.[fn::An
-=org-time-stamp= can be inserted with ~C-c .~ (period)]
+The agenda displays a chronological list of headings across all
+agenda files for which the heading or body contain a matching
+=org-time-stamp=.[fn::An =org-time-stamp= can be inserted with
+~C-c .~ (period)]
We open the agenda in a separate window.
#+BEGIN_SRC emacs-lisp :tangle yes
-(setq org-agenda-window-setup 'other-frame)
+ (setq org-agenda-window-setup 'other-frame)
#+END_SRC
** LaTeX export
-We'll be compiling our documents with LuaTeX. This will afford us some
-future-proofing, since it was designated as the successor to pdfTeX by the
-latter's creators.
+We'll be compiling our documents with LuaTeX. This will afford us
+some future-proofing, since it was designated as the successor to
+pdfTeX by the latter's creators.
-First, we define the command executed when an Org file is exported to
-LaTeX. We'll use =latexmk=, the Perl script which automagically runs binaries
-related to LaTeX in the correct order and the right amount of times.
+First, we define the command executed when an Org file is exported
+to LaTeX. We'll use =latexmk=, the Perl script which automagically
+runs binaries related to LaTeX in the correct order and the right
+amount of times.
Options and why we need them:
- ~-shell-excape~ :: required by minted to color source blocks
- ~-pdflatex=lualatex~ :: we use lualatex to generate our PDF
-- ~-interaction=nonstopmode~ :: go as far as possible without prompting user
- for input
+- ~-interaction=nonstopmode~ :: go as far as possible without
+ prompting user for input
#+BEGIN_SRC emacs-lisp :tangle yes
(setq org-latex-pdf-process
@@ -1089,9 +1120,9 @@ Options and why we need them:
*** Exporting timestamps
-We customize the format for org time stamps to make them appear monospaced in
-our exported LaTeX documents. This makes them visually distinguishable from
-body text.
+We customize the format for org time stamps to make them appear
+monospaced in our exported LaTeX documents. This makes them
+visually distinguishable from body text.
#+BEGIN_SRC emacs-lisp :tangle yes
(setq org-latex-active-timestamp-format
@@ -1102,7 +1133,8 @@ body text.
*** LaTeX packages
-The following packages are loaded for every time we export to LaTeX.
+The following packages are loaded for every time we export to
+LaTeX.
#+BEGIN_SRC emacs-lisp :tangle yes
(setq org-latex-packages-alist
@@ -1120,8 +1152,8 @@ The following packages are loaded for every time we export to LaTeX.
*** Colored source blocks in PDF export
-Little bonus for GNU/Linux users: syntax highlighting for source code blocks in
-LaTeX exports.
+Little bonus for GNU/Linux users: syntax highlighting for source
+code blocks in LaTeX exports.
#+BEGIN_SRC emacs-lisp :tangle yes
(when (string-equal system-type "gnu/linux")
@@ -1135,9 +1167,9 @@ LaTeX exports.
*** Cleaning directory after export
-Now, we set the files to be deleted when a LaTeX \rightarrow PDF compilation
-occurs. We only care about two files, in the end: the Org mode file for
-edition, and the PDF for distribution.
+Now, we set the files to be deleted when a LaTeX \rightarrow PDF
+compilation occurs. We only care about two files, in the end: the
+Org mode file for edition, and the PDF for distribution.
#+BEGIN_SRC emacs-lisp :tangle yes
(setq org-latex-logfiles-extensions
@@ -1149,16 +1181,16 @@ edition, and the PDF for distribution.
*** Chronological diary entries
-By default, Org agenda inserts diary entries as the first under the selected
-date. It is preferable to insert entries in the order that they were recorded,
-i.e. chronologically.
+By default, Org agenda inserts diary entries as the first under
+the selected date. It is preferable to insert entries in the order
+that they were recorded, i.e. chronologically.
#+BEGIN_SRC emacs-lisp :tangle yes
(setq org-agenda-insert-diary-strategy 'date-tree-last)
#+END_SRC
-What follows is an additional document class structures that can be exported in
-LaTeX.
+What follows is an additional document class structures that can
+be exported in LaTeX.
#+BEGIN_SRC emacs-lisp :tangle no
;; (add-to-list 'org-latex-classes
@@ -1172,23 +1204,25 @@ LaTeX.
*** Table of contents
-By default, body text can immediately follow the table of contents. It is
-however cleaner to separate table of contents with the rest of the work.
+By default, body text can immediately follow the table of
+contents. It is however cleaner to separate table of contents with
+the rest of the work.
#+BEGIN_SRC emacs-lisp :tangle yes
(setq org-latex-toc-command "\\tableofcontents\\clearpage")
#+END_SRC
-The following makes =TODO= items appear red and =CLOSED= items appear green in
-Org's LaTeX exports. Very stylish, much flair!
+The following makes =TODO= items appear red and =CLOSED= items
+appear green in Org's LaTeX exports. Very stylish, much flair!
** TODO Org links
-This is a mind-bending capacity of Org mode: we can assign arbitrary functions
-to be executed when a user follows an Org link. Org links appear like
-hyperlinks both in buffers and PDF exports---e.g. the following link to this
-very section, Section [[Org links]]---but their in-buffer behavior can be
-arbitrarily assigned.
+This is a mind-bending capacity of Org mode: we can assign
+arbitrary functions to be executed when a user follows an Org
+link. Org links appear like hyperlinks both in buffers and PDF
+exports---e.g. the following link to this very section, Section
+[[Org links]]---but their in-buffer behavior can be arbitrarily
+assigned.
#+BEGIN_SRC emacs-lisp :tangle no
(org-add-link-type
@@ -1204,21 +1238,23 @@ arbitrarily assigned.
* One-click workflows
-In this section, we'll implement useful one-click workflows. It comes later
-keybinding definitions for two reasons:
+In this section, we'll implement useful one-click workflows. It
+comes later keybinding definitions for two reasons:
1. To a new user, keybindings are more important than the precise
- implementation of the bound function---it is more important to know how to
- drive a car than how a car works.
-2. If the following subsections share the same name as the keybinding
- subsection (Section [[Keyboard shortcuts]]), the links will resolve to the
- earliest heading in the document, i.e. the keybinding subsection and not the
- subsection describing the `one-click workflow'.
+ implementation of the bound function---it is more important to
+ know how to drive a car than how a car works.
+2. If the following subsections share the same name as the
+ keybinding subsection (Section [[Keyboard shortcuts]]), the links
+ will resolve to the earliest heading in the document, i.e. the
+ keybinding subsection and not the subsection describing the
+ `one-click workflow'.
** TODO Export to PDF
-This reimplements the most common Org mode export: Org \rightarrow LaTeX
-\rightarrow PDF. The binding is defined in Section [[Export to PDF]].
+This reimplements the most common Org mode export: Org \rightarrow
+LaTeX \rightarrow PDF. The binding is defined in Section [[Export to
+PDF]].
#+BEGIN_SRC emacs-lisp :tangle yes
(defun sd-org-quick-export ()
@@ -1250,8 +1286,8 @@ Binding defined in Section [[Indent buffer]].
* Editing preferences
-These customizations enhance editor usability. They also encompass cosmetic
-changes not brought about a specific package.
+These customizations enhance editor usability. They also encompass
+cosmetic changes not brought about a specific package.
** Editor
@@ -1266,8 +1302,8 @@ This is just a better default. Don't @ me.
*** Recent files
-The keybinding for opening a recently visited file is described in paragraph
-[[Open a recently visited file]].
+The keybinding for opening a recently visited file is described in
+paragraph [[Open a recently visited file]].
#+BEGIN_SRC emacs-lisp :tangle yes
(recentf-mode 1)
@@ -1294,9 +1330,9 @@ The keybinding for opening a recently visited file is described in paragraph
:sd-unpack-path: sd-icons.el
:END:
-We start by defining some icons we wish to include in our user interface. Emacs
-allows the usage of GIF images---this paves the way for UI elements which may be
-animated.
+We start by defining some icons we wish to include in our user
+interface. Emacs allows the usage of GIF images---this paves the
+way for UI elements which may be animated.
#+BEGIN_SRC emacs-lisp :tangle yes
(defvar sd-icons-blue-ellipsis (create-image
@@ -1316,8 +1352,8 @@ animated.
**** TODO Header line
# Figure out how to do 'keymap cleanly
-In Org mode, the document header line will be the title of the document we are
-working on currently.
+In Org mode, the document header line will be the title of the
+document we are working on currently.
#+BEGIN_SRC emacs-lisp :tangle yes
(setq sd-header-gnu-linux
@@ -1404,8 +1440,8 @@ Save cursor location in visited buffer after closing it or Emacs.
*** Column filling
-A line of text is considered ``filled'' when it reaches 79 characters in
-length.
+A line of text is considered ``filled'' when it reaches 79
+characters in length.
#+BEGIN_SRC emacs-lisp :tangle yes
(setq-default fill-column 79)
@@ -1418,8 +1454,9 @@ length.
*** Beautiful symbols
-We want the Emacs Lisp keyword =lambda= to be rendered as \lambda within the
-editor. This is mostly for a subjective ``cool'' factor.
+We want the Emacs Lisp keyword =lambda= to be rendered as \lambda
+within the editor. This is mostly for a subjective ``cool''
+factor.
#+BEGIN_SRC emacs-lisp :tangle yes
(global-prettify-symbols-mode 1)
@@ -1427,8 +1464,8 @@ editor. This is mostly for a subjective ``cool'' factor.
*** Org mode sugar
-Let's pimp out the appearance of our text in Org mode. First, we prettify
-checkbox lists.
+Let's pimp out the appearance of our text in Org mode. First, we
+prettify checkbox lists.
#+BEGIN_SRC emacs-lisp :tangle yes
(when (string-equal system-type "gnu/linux")
@@ -1450,10 +1487,10 @@ checkbox lists.
*** Electric modes
-Electricity is a very important technology. In Emacs jargon, ``electric'' modes
-tend to automate behaviors or present some elegant simplification to a
-workflow.[fn::More information can be found at
-[[https://www.emacswiki.org/emacs/Electricity]].]
+Electricity is a very important technology. In Emacs jargon,
+``electric'' modes tend to automate behaviors or present some
+elegant simplification to a workflow.[fn::More information can be
+found at [[https://www.emacswiki.org/emacs/Electricity]].]
#+BEGIN_SRC emacs-lisp :tangle yes
(electric-pair-mode) ; Certain character pairs are automatically completed.
@@ -1476,8 +1513,9 @@ Disable minibuffer scroll bar.
* Themes
-Without a carefully designed theme, our editor would become unusable. Thus, we
-describe two themes that were developed purposefully and iteratively.
+Without a carefully designed theme, our editor would become
+unusable. Thus, we describe two themes that were developed
+purposefully and iteratively.
#+BEGIN_SRC emacs-lisp :tangle yes
(setq custom-theme-directory (concat user-emacs-directory "themes/"))
@@ -1491,11 +1529,12 @@ A highly legible, unambiguous, and classic theme.
*** Colors
-The default face is a black foreground on a white background, this matches MS
-Word. We are striving for a simple, intuitive color scheme.
+The default face is a black foreground on a white background, this
+matches MS Word. We are striving for a simple, intuitive color
+scheme.
-Most of the visual cues derived from color are identical in both light and dark
-themes (Table [[theme-color-1]]).
+Most of the visual cues derived from color are identical in both
+light and dark themes (Table [[theme-color-1]]).
#+NAME: theme-color-1
#+CAPTION[Light and dark themes' colors]: Light and dark themes' colors.
@@ -1518,9 +1557,9 @@ themes (Table [[theme-color-1]]).
*** Cursors
-In order to imitate other modern text editors, we resort to a blinking bar
-cursor. We choose red, the most captivating color, because the cursor is
-arguably the region on our screen:
+In order to imitate other modern text editors, we resort to a
+blinking bar cursor. We choose red, the most captivating color,
+because the cursor is arguably the region on our screen:
1. most often looked at;
2. most often searched when lost.
@@ -1539,8 +1578,8 @@ cursor is a more MS Word-like bar.
**** Currently used /chad fonts/
-- Hack[fn::https://sourcefoundry.org/hack/] :: ~default~ and ~fixed-pitch~,
- default code font
+- Hack[fn::https://sourcefoundry.org/hack/] :: ~default~ and
+ ~fixed-pitch~, default code font
- Legible, modern monospace font
- Strict, sharp, uncompromising
- Public Sans[fn::https://public-sans.digital.gov/] :: ~variable-pitch~,
@@ -1548,8 +1587,8 @@ cursor is a more MS Word-like bar.
- Very modern yet neutral
- Designed for the U.S. government
- Exceptional color on screen
-- Hermit[fn::https://pcaro.es/p/hermit/] :: ~org-block~, anything Org/meta in
- general
+- Hermit[fn::https://pcaro.es/p/hermit/] :: ~org-block~, anything
+ Org/meta in general
- Slightly wider than Hack
- More opinionated shapes
- Very legible parentheses, very useful for Emacs Lisp!
@@ -1615,6 +1654,6 @@ store the result of our profiling.
* Conclusion
-In this configuration file, we described a series of customization steps taken
-to make Emacs more palatable to modern IDE users.
+In this configuration file, we described a series of customization
+steps taken to make Emacs more palatable to modern IDE users.
Copyright 2019--2024 Marius PETER