summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--smart-documents.org160
1 files changed, 80 insertions, 80 deletions
diff --git a/smart-documents.org b/smart-documents.org
index a1fe829..e4c730c 100644
--- a/smart-documents.org
+++ b/smart-documents.org
@@ -18,13 +18,13 @@
#+LATEX: \begin{abstract}
The idea of {{{SDs}}} came to me as I was reflecting on how to improve
-the document creation process in my workplace. The GNU Emacs editor
+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
+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
+personal GNU Emacs customizations with a tutorial. This paper is a
{{{SD}}} itself!
#+LATEX: \end{abstract}
@@ -55,17 +55,17 @@ Put them somewhere it makes sense.
* Introduction
-The following sections were laid out very deliberately. When we start
+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
+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
+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:
@@ -162,7 +162,7 @@ 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---stop]]. We will then present profiling report in Section
[[Profiling---report]].
#+NAME: profiler-start
@@ -177,26 +177,26 @@ logic.
- File :: A collection of information recognized by a computer---to
us, a normal file appears as programs (source code or /executables/)
- or data (an image, a video, a document...). It is usually stored in
+ or data (an image, a video, a document...). It is usually stored in
a computer's memory or on a storage device (hard drive, USB
drive...)
- Path :: A description of a file's location from the user's
- perspective. A path is program searches for a file or executable
+ perspective. A path is program searches for a file or executable
program.
-- Directory :: Synonymous with /folder/. From the computer's---and
- Emacs'---perspective, a file which contains other files. These files
+- Directory :: Synonymous with /folder/. From the computer's---and
+ Emacs'---perspective, a file which contains other files. These files
may themselves be directories.
*** Meta files---files about 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
-[[help:user-emacs-directory][user-emacs-directory]]. This leads to undesirable clutter. Certain
+[[help:user-emacs-directory][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
+reference... other files. Thus, I decided to refer to them as meta
files.
A meta files should follow the following best practices:
@@ -204,7 +204,7 @@ A meta files should follow the following best practices:
- Be located at [[help:sd-path-meta][sd-path-meta]] :: This ensures a tidy
[[help:user-emacs-directory][user-emacs-directory]].
- Be explicit :: Meta filenames should not begin with a period: they
- would be hidden by default on GNU/Linux systems. Novices must see
+ would be hidden by default on GNU/Linux systems. Novices must see
all files by default.
#+BEGIN_SRC emacs-lisp :tangle yes
@@ -237,9 +237,9 @@ A meta files should follow the following best practices:
**** Org id locations
#+begin_quote
-We track IDs through files, so that links work globally. The file
+We track IDs through files, so that links work globally. The file
defined at [[help:org-id-locations-file][org-id-locations-file]] maintains a hash table for IDs and
-writes this table to disk when exiting Emacs. Because of this, it
+writes this table to disk when exiting Emacs. Because of this, it
works best if you use a single Emacs process, not many.
Paraphrased from [[help:org-id-track-globally][the Emacs help interface]].
@@ -317,7 +317,7 @@ This path, specifically, is required to be in list form.
**** Custom file
-Load settings created automatically by GNU Emacs Custom. (For example,
+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>~.
@@ -382,10 +382,10 @@ Transparency.
** 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
+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
+[[~org-mode~]]). You need to create this =secrets.org= file, as it is
ignored by =git= by default.
#+BEGIN_SRC emacs-lisp :tangle yes
@@ -405,8 +405,8 @@ function definition exists, until the keybinding is pressed.
** CUA mode
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
+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
@@ -522,11 +522,11 @@ The following bindings lead to more natural window & frame exit behaviors.
*** Remap =C-z= when using a graphical interface
-By default, =C-z= suspends the editor. This is extremely handy when
-the editor is started with the =-nw= option (no window, i.e. launched
+By default, =C-z= suspends the editor. This is extremely handy when
+the editor is started with the =-nw= option (no window, i.e. launched
in a terminal), because it returns control to the terminal command
line without quitting Emacs---it simply places the Emacs process in
-the background. The user may then use the Linux job management tools
+the background. The user may then use the Linux job management tools
to return inside the Emacs process.
However, when using a graphical display, we have no need for
@@ -556,15 +556,15 @@ It seems that starting with Emacs 27.1, Control + mousewheel works.
** TODO COMMENT Navigation
# [2021-09-13 Mon]
#
-# Kinda don't like this... This is some more text. And then some. And
+# Kinda don't like this... This is some more text. And then some. And
# then some.
-=Alt= (=Meta=) is the privileged key for motion in a buffer. It is
+=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,
+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
+=l=. You will move in that direction in the amount of the numerical
argument.
#+NAME: keybinding-navigation
@@ -630,7 +630,7 @@ 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
+complicated functions can be assigned to very simple keybindings. This
means we can automate workflows up to a pretty absurd level.
*** Export to PDF
@@ -713,7 +713,7 @@ described in this 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
+~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]].]
@@ -730,7 +730,7 @@ typing speed and accuracy.
*** Syntax checking
-We require a package to highlight syntax errors and warnings. The
+We require a package to highlight syntax errors and warnings. The
~flycheck~ package ensures we are aware of all our code's syntactical
shortcomings.
@@ -758,7 +758,7 @@ 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
+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.]
@@ -771,7 +771,7 @@ to the following text:
: #+END_SRC
We notice that emacs-lisp is highlighted---this is the first
-modifiable field. Many clever programming tricks can be performed with
+modifiable field. Many clever programming tricks can be performed with
~yasnippet~ to save us a ton of time with boilerplate text!
#+NAME: yasnippet
@@ -796,7 +796,7 @@ modifiable field. Many clever programming tricks can be performed with
*** Versioning of files
-Wonderful Git porcelain for Emacs. Enables the administration of a Git
+Wonderful Git porcelain for Emacs. Enables the administration of a Git
repository in a pain-free way.
#+BEGIN_SRC emacs-lisp :tangle yes
@@ -824,7 +824,7 @@ 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
+~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.
@@ -1046,7 +1046,7 @@ reliably be shared and exported to PDF in a reproducible fashion.
*** Accounting
-Ledger is a creation of John Wiegley's. It enables double-entry
+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/.]
@@ -1058,7 +1058,7 @@ 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
+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
@@ -1142,16 +1142,16 @@ Phew, after all this initialization, I can finally introduce Org mode!
I am so *excited*.
Org mode replaces a word processor, a presentation creator, and a
-spreadsheet editor. The spreadsheet ability captures more than 80% use
+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
+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
+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
@@ -1210,7 +1210,7 @@ We then set values for many other Org-related cosmetic symbols.
*** Pretty LaTeX symbols
We display LaTeX entities as UTF8 symbols \rArr this is a slick idea to
-further make Emacs look like the exported PDF. Using symbols in tables
+further make Emacs look like the exported PDF. Using symbols in tables
is discouraged?
#+BEGIN_SRC emacs-lisp :tangle no
@@ -1219,9 +1219,9 @@ is discouraged?
*** Dynamic numbering of headlines
-We enable the dynamic numbering of headlines in an Org buffer. We also
+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,
+~:background white~ attribute. This is necessary because otherwise,
the background of the numbering may be overridden by the ~TODO~ face
attribute ~:background coral~.
@@ -1234,7 +1234,7 @@ attribute ~:background coral~.
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
+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]]).
@@ -1276,7 +1276,7 @@ shortcut (cf. Section [[Open Org mode document properties]]).
*** Timestamps
# This is a terrible idea :-( but leaving the option to the
-# reader. Long live ISO-8601!
+# reader. Long live ISO-8601!
# https://orgmode.org/manual/Custom-time-format.html
More literary timestamps can be exported to LaTeX using the following
@@ -1388,12 +1388,12 @@ being executed by the Org Babel backend upon document export.
*** LaTeX export
-We'll be compiling our documents with LuaTeX. This will afford us some
+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
+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.
@@ -1412,7 +1412,7 @@ 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 it easy to
+monospaced in our exported LaTeX documents. This makes it easy to
distinguish time stamps from body text, and make them align nicely in
definition lists, which I prefer when logging events:
@@ -1454,7 +1454,7 @@ The following packages are loaded for every time we export to LaTeX.
**** COMMENT Colored source blocks in PDF export
-# Too distracting. Focus on fonts.
+# Too distracting. Focus on fonts.
Little bonus for GNU/Linux users: syntax highlighting for source code
blocks in LaTeX exports.
@@ -1472,7 +1472,7 @@ blocks in 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
+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
@@ -1486,8 +1486,8 @@ mode file for 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.
+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)
@@ -1528,7 +1528,7 @@ in our LaTeX distribution; it can be installed from the [[https://ctan.org/pkg/l
**** COMMENT Table of contents
# Commented out on <2021-09-21 Tue>.
-By default, body text can immediately follow the table of contents. It
+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.
@@ -1537,7 +1537,7 @@ work.
#+END_SRC
The following makes =TODO= items appear red and =CLOSED= items appear
-green in Org's LaTeX exports. Very stylish, much flair!
+green in Org's LaTeX exports. Very stylish, much flair!
**** COMMENT AUCTEX
@@ -1558,8 +1558,8 @@ 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 as hyperlinks both in buffers and PDF exports---e.g. the
+functions to be executed when a user follows an Org link. Org links
+appear as 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.
@@ -1578,7 +1578,7 @@ in-buffer behavior can be arbitrarily assigned.
* One-click workflows
-In this section, we'll implement useful one-click workflows. It comes
+In this section, we'll implement useful one-click workflows. It comes
later than the keybinding definitions for two reasons:
1. To a new user, keybindings are more relevant than the
@@ -1586,7 +1586,7 @@ later than the keybinding definitions for two reasons:
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 to that name
- will resolve to the earliest heading in the document, i.e. the
+ will resolve to the earliest heading in the document, i.e. the
keybinding subsection, and not the subsection describing the
``one-click workflow''.
@@ -1617,14 +1617,14 @@ We begin by defining a function to open this very file.
** TODO Export to PDF
This series of ~quick-export~ functions have one objective: harmonize
-the export of Emacs buffers to PDF. Org mode does this by design; we
+the export of Emacs buffers to PDF. Org mode does this by design; we
describe additional exports for other modes, most notably Nroff mode
and Ledger mode.
*** From Org mode
This reimplements the most common Org mode export: Org \rightarrow LaTeX \rightarrow
-PDF. The binding is defined in Section [[Export to PDF]].
+PDF. The binding is defined in Section [[Export to PDF]].
#+BEGIN_SRC emacs-lisp :tangle yes
(defun sd-quick-export--org ()
@@ -1772,14 +1772,14 @@ PDF. The binding is defined in Section [[Export to PDF]].
* Editing preferences
-These customizations enhance editor usability. They also encompass
+These customizations enhance editor usability. They also encompass
cosmetic changes not brought about a specific package.
** Editor
*** Coding standards
-This is just a better default. Don't @ me.
+This is just a better default. Don't @ me.
#+BEGIN_SRC emacs-lisp :tangle yes
(setq c-default-style "linux"
@@ -1816,7 +1816,7 @@ paragraph [[Open a recently visited file]].
: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
+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
@@ -1840,7 +1840,7 @@ for UI elements which may be animated.
**** Header line
In Org mode, the document header line will be the title of the
-document we are working on currently. We start by defining keybindings
+document we are working on currently. We start by defining keybindings
for our header line buttons for navigating through open windows.
#+BEGIN_SRC emacs-lisp :tangle yes
@@ -1955,7 +1955,7 @@ Save cursor location in visited buffer after closing it or Emacs.
*** Column filling
We leave the default ~fill-column~ unchanged, so as to minimally
-disrupt a user's existing documents. We automatically break lines
+disrupt a user's existing documents. We automatically break lines
longer than =fill-column=.
#+BEGIN_SRC emacs-lisp :tangle yes
@@ -1968,7 +1968,7 @@ longer than =fill-column=.
*** 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.
+within the editor. This is mostly for a subjective ``cool'' factor.
#+BEGIN_SRC emacs-lisp :tangle yes
(global-prettify-symbols-mode 1)
@@ -1976,7 +1976,7 @@ within the 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
+Let's pimp out the appearance of our text in Org mode. First, we
prettify checkbox lists when viewed on GNU/Linux systems.
#+BEGIN_SRC emacs-lisp :tangle yes
@@ -2003,7 +2003,7 @@ prettify checkbox lists when viewed on GNU/Linux systems.
*** Electric modes
-Electricity is a very important technology. In Emacs jargon,
+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]].]
@@ -2033,7 +2033,7 @@ Disable minibuffer scroll bar.
# This is just another comment.
Without a carefully designed theme, our editor would become
-unusable. Thus, we /describe/ two themes that were developed
+unusable. Thus, we /describe/ two themes that were developed
*purposefully* and iteratively.
#+BEGIN_SRC emacs-lisp :tangle no
@@ -2063,7 +2063,7 @@ 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.
+matches MS Word. We are striving for a simple, intuitive color scheme.
Most of the [[https://www.interaction-design.org/literature/topics/affordances][affordance]] cues derived from color are identical in
both light and dark themes (Table [[theme-color-1]]).
@@ -2095,14 +2095,14 @@ both light and dark themes (Table [[theme-color-1]]).
**** Purple
-Purple is Emacs' main logo color. Since we use Emacs for coding a lot,
-code syntax highlighting to could be in the pink/purple shades. This
+Purple is Emacs' main logo color. Since we use Emacs for coding a lot,
+code syntax highlighting to could be in the pink/purple shades. This
is also a nod to Spacemacs' dark theme.2 hour
*** TODO 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
+bar cursor. We choose red, the most captivating color, because the
cursor is arguably the region on our screen:
1. most often looked at;
@@ -2188,14 +2188,14 @@ is greater than 1920\times1080.
** TODO /Wealthy/ document theme
#+NAME: claude-garamont
-#+CAPTION[Claude Garamont, an icon of font design]: Claude Garamont, an icon of font design. World-renowned for his elegant typefaces, which inspired many generations of typographers.
+#+CAPTION[Claude Garamont, an icon of font design]: Claude Garamont, an icon of font design. World-renowned for his elegant typefaces, which inspired many generations of typographers.
#+ATTR_LATEX: :width 0.4\textwidth
[[~/.emacs.d/resources/images/smart-documents/ClaudeGaramond.jpeg]]
#+LATEX: \garamond
\lettrine{G}{ood} golly, nobody wishes for a /pedestrian/ theme! Let
your entourage know that you're rocking an editor fit for a king with
-this finely crafted `wealthy' theme. Selecting it shall enable the
+this finely crafted `wealthy' theme. Selecting it shall enable the
following fancitudes:
1. The default font shall be sublimed in the form of /EB Garamond/
@@ -2205,14 +2205,14 @@ following fancitudes:
#+BEGIN_QUOTE
\lettrine{C}{laude} Garamont (c. 1510--1561), known commonly as
*Claude Garamond*, was a French type designer, publisher and
-punch-cutter based in Paris. Garamond worked as an engraver of
+punch-cutter based in Paris. Garamond worked as an engraver of
punches, the masters used to stamp matrices, the moulds used to cast
-metal type. He worked in the tradition now called old-style serif
+metal type. He worked in the tradition now called old-style serif
design, which produced letters with a relatively organic structure
resembling handwriting with a pen but with a slightly more structured
-and upright design. Considered one of the leading type designers of
+and upright design. Considered one of the leading type designers of
all time, he is recognised to this day for the elegance of his
-typefaces. Many old-style serif typefaces are collectively known as
+typefaces. Many old-style serif typefaces are collectively known as
Garamond, named after the designer.
From [[https://en.wikipedia.org/wiki/Claude_Garamond]]
@@ -2235,7 +2235,7 @@ From [[https://en.wikipedia.org/wiki/Claude_Garamond]]
* Late setup
-At this point, our editor is almost ready to run. Phew! All that's
+At this point, our editor is almost ready to run. Phew! All that's
left to do is to interrupt our profiling activities, and smartly store
the result of our profiling.
Copyright 2019--2024 Marius PETER