diff options
| -rw-r--r-- | smart-documents.org | 160 |
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. |