[Transitioning... rewriting...]

# types of plain text

Concise descriptions of various plain text document formats.

using HTML for organizing files

In essence, an HTML document is a customizable view of the other documents and images on the computer. That either supplements or replaces the Finder on macOS or the File Explorer on MS Windows OS, because they don't give much if any options for writing descriptions for a file, nor for grouping files as easily as typing text.

An HTML document is a cleaner and simpler approach to organizing files rather than creating lots of folders and moving files around, or even creating so-called symlinks or aliases to files. No need to move anything or rename anything, just link to it within an HTML document and describe it as easily as writing a simple note. Start as basic and simple as a list with links, then add paragraphs as desired.

In this way, the reason for having each document or image can be reviewed at any time without opening each and every document with many different applications every time. An HTML document can have links to the other documents and images within the directory, even showing all images within the HTML document without having to open each of those individually. Documents without descriptions, reasons, or relations to other documents become prime candidates for removal in order to reduce clutter.

An HTML document can be viewed in any web browser on the computer without need for a webserver or even an internet connection. HTML documents are perfect for providing information about documents and images in any directory (a.k.a. a folder) that is copied to external storage to be shared with others because HTML is cross-platform compatible. No matter what operating system, even from before the turn of the century, every computer comes with an HTML viewer (a.k.a. web browser) and a simple text editor for editing plain text.

No special programs necessary, no extra cost, and HTML is as plain as the keys on a keyboard.

using HTML for making PDFs

(more later)

# resources

emacs intro
ImageMagick links
file transfer, find, and grep
ssh key generation and use

# emacs (Editing MACroS)

Use emacs (from its website) for editing text, and when it's helpful occasionally record sequences of typing and commands as macros to repeat with a single keystroke. No computer programming necessary. Hence, "editing macros" means macros for use with editing text, and in emacs everything is text (though it can show an image as an image, too).

Everything can be done with the keyboard in emacs. That is especially helpful for people too lazy to precisely move a computer mouse or a trackpad. The keyboard can remain sitting still and most of its keys are actually labeled. With repeatability there is no worry about repetitive stress, no need for ergonomics.

Remember: it's a computer, not a typewriter. There is no need to keep hands positioned over the "home" keys of asdf and jkl; at all times. Just relax, occasionally press a few keys in whatever comfortable manner, and let the computer do the work.

The following description is mostly an overview of the interface and the exceptional experience of emacs, a supplement but not a replacement for its classic tutorial.

# what?  how?  the command prompt

A single blank line known as the "minibuffer" is at the very bottom where short messages are revealed after evoking a command, or a prompt is shown waiting for an answer. This is how to know what has just happened, or what is needed in order for something to happen.

A command can be executed by typing the two characters ESC x, t.i. the ESC (escape) key and then the x key, and then typing the command's full name and the RET (return) key. The use of the ESC key causes these typed characters to be shown in the minibuffer while typing them, not in the document being edited. After typing RET the command will be executed.

Sometimes there will be a message about the results of the command evoked, depending on the command. For example, typing ESC x forward-paragraph RET will move the text cursor to the beginning of the next paragraph, and there will be no message about the result.

Tab completion is usually available whenever there is a prompt in the minibuffer, such as text followed by a colon ": ", when typing a command name or other values in the minibuffer. At such a prompt either type the TAB key, or type the beginning of something and then type the TAB key. Either the only possible value is filled in, or all possibilities are shown in a temporary view. Not much need to remember how to spell anything or whether it exists.

Type Controlg to give up and go back to editing text instead of finishing typing a command in the minibuffer.

# shortcuts

Sometimes a command name is bound to a shorter sequence of keystrokes (a keybinding or shortcut), which is a nickname of sorts. A shortcut is often one modifier key combined with one other character, or the ESC character followed by another character.

Modifier keys tend to be at the bottom corners of the keyboard, on either side of the space key. The SHIFT key is a modifier key, and so is the CONTROL key, the ALT key, the OPTION key, the COMMAND key, and even the FN key. They all work in same way, so knowing how to use the SHIFT key means knowing how to use any modifier key, but of course each does a different modification. For example, Shifta inserts a capital "a", t.i. "A".

On the other hand, the ESC (escape) key, the TAB key, the SPACE (space) key, and the RET (return) key are regular keys and therefore produce characters (though typically without symbols) just like the letter keys, number keys, and punctuation keys.

A shortcut can also have multiple modifier keys used with a character. Typically, shortcuts are kept simple and the complex ones are for rarely used commands. Of course, they can be personally customized if desired, and more than one shortcut for the same command is allowed.

The helpful shortcut Controlh w will reveal which shortcuts a command has by prompting for the command name in the minibuffer. For example, type Controlh w, then at the prompt type the command name forward-paragraph (or use tab completion) and then the RET (return) key. The minibuffer will reveal its shortcut, which is by default the two characters ESC }.

Similarly, Controlh f will also prompt for a command name to find, but it reveals the documentation for the command name which will also include the shortcuts for it. The documentation will be shown in a view rather than shown in the minibuffer.

Contrarily, the shortcut Controlh c will reveal the command name for a shortcut, if there is one. For example, type Controlh c and then at the prompt type the two-character shortcut ESC {. The command name for that shortcut will be immediately revealed as backward-paragraph in the minibuffer. Or, query about either Shifta or just a, and then the minibuffer will reveal the command self-insert-command.

Similarly, Controlh k will also prompt for a shortcut, but it reveals the command name and its documentation, and in a view rather than in the minibuffer.

Sometimes a modifer key and character is a prefix for a longer shortcut name, for example Controlx (a very common prefix for executing shortcuts). In that case, the minibuffer will show an abbreviated form of the characters typed (f.e. C-x- for Controlx) after a short pause, meaning it's waiting for more. There's no need to wait for the prompt when the complete shortcut is already known, and when typed fast enough it won't show in the minibuffer at all. Either finish typing the shortcut sequence to evoke the command, or type Controlh for help and then a listing of known shortcuts beginning with that prefix will be revealed in another view. On the other hand, using Controlg with a prefix will typically cancel it because the resulting shortcut is typically not defined.

# repeat commands without repeating commands

Commands can be repeated a specific number of times by using the CONTROL key with a number (or with just the first digit of the number) before evoking a command. For example, to move the text cursor forward three paragraphs type Control3 ESC x forward-paragraph RET.

Or, use repeatibility with its shortcut by typing Control1 Control2 ESC } to move the text cursor 12 paragraphs forward, or perhaps more conveniently with only Control1 2 ESC }.

Sometimes it makes sense to use a negative value with a command. Type a hyphen first to indicate a negative value, such as Control- 27 for -27. Also, using only Control- is a convenient equivalent to Control- 1.

Of course, this can be used with typing. For example, type Control8 0 - to produce 80 hyphens. Or, use it with the DEL (delete) key to remove a specific number of characters, forwards when with a positive value and backwards with a negative value. Or, use it to select text, such as a specific number of words or paragraphs, either forwards or backwards.

# type anything, start highlighting, select everything

The prefix Controlx 8 is for inserting any Unicode character. Just type Controlx 8 Controlh for a helpful list of all possibilities revealed in a new buffer (and likely in a new view).

The prefix ESC s h is for specially highlighting patterns of text, f.e. the same word or phrase throughout a document. As usual, following the prefix with Controlh will reveal the various possibilities. For example, ESC s h p will prompt for a phrase to highlight, and then color that text throughout the document. (Using ESC s h r asks for a "regular expression", which is a pattern for text.) The default is yellow the first time, and then a different color for each successive call for new phrases, but any color can be chosen.

Search with Controls or in reverse with Controlr. All matches will be highlighted, and can be traversed forwards or backwards by repeating those shortcuts. While searching, use the higlighting command ESC s h r to choose a color for the matches, which then ends the search. Or while searching, use the shortcut ESC % to specify a replacement and begin getting asked for each match.

Use CONTROL and the SPACE (space) key, t.i. ControlSPACE, to set the mark for selecting text. Then maneuver the text cursor as normal and the text will be selected. For example, use ESC } to move to the beginning of the next paragraph thereby selecting everything in between. Or, use ControlSPACE ControlSPACE (t.i. twice) to deactivate the mark, which cancels selecting text.

Similarly, using the SHIFT modifier key with the movement shortcuts will also select a region. For example, the tutorial reveals ESC e moves to the end of the sentence (or the next one if at the end already), so ESC Shifte would select to the end of the sentence. The content of the whole buffer can be selected with the simpler Controlx h, no matter where the cursor is currently located.

While selecting text, use search to extend the selected region. The selection will extend to the next or previous match, and each thereafter for each repeat of the search shortcut. End the search and then do whatever with the region, such as search/replace within it and only it.

Once a region is selected, then use Controlx n n to narrow the contents to only that selected region. In other words, everything else in the buffer is hidden. Select another region and narrow it again, if desired. Show everything once again by widening with Controlx n w. (Obviously, Controlx n is a shortcut prefix, so Controlx n Controlh will show help in another view with other shortcuts beginning with it.)

# documents

Editing a document is always on a copy of it from its file, and in emacs this is explicitly acknowledged by referring to the copy as a "buffer", a temporary place for editing.

Already existing documents can be viewed with the "directory edit" mode using the command ESC x dired RET (shortcut: Controlx d). The prompt in the minibuffer shows the name of the default directory (folder) that will be listed in the current view, otherwise type the name of the desired directory before typing RET.

When viewing a listing of files in dired mode, help for the mode can be shown with Controlh m (as that shortcut does for any mode). Note that many of dired's shortcuts are simply a single key or use the SHIFT modifier key, such as for copying (Shiftc), renaming (Shiftr), or toggle sorting the listing by name or date (s). Just move the text cursor to the name of the file and type RET to reveal its contents for editing.

Compress or uncompress a file in a dired listing with Shiftz (which also adds or removes ".gz" from end of name). If gnupg is installed with emacs (perhaps for use with email authentication), then a file in dired can be encrypted with : e (which also adds or removes ".gpg" from end of name).

No need to uncompress a file before editing it. In emacs, the uncompressed contents are shown for editing, and then automatically recompressed when saved again. Same thing for encrypted files (".gpg") (automatically asking for passphrase), or even encrypted compressed files (".gz.gpg", or the potentially smaller ".gpg.gz").
(But tricky: Will work when a document is saved with both extensions, in either order. However, compressing an encrypted file within dired results in viewing only encrypted data. To fix: Open file; use Controlx h to select contents of whole buffer; use ESC x epa-decrypt-region, and agree to replace text; then save document.)

A new document (file) can be initiated with Controlx Controlf and then typing a name for it in the prompt in the minibuffer. However, it will be only a buffer (a temporary place for editing), and the file will not actually exist until the buffer is saved.

Save the changes of a document done within a buffer to its associated file with Controlx Controls. Saving a buffer overwrites the document's file (if already existing), though a backup of the original is automatically made the first time (with same name plus "~"). Write a document to a new file name with Controlx Controlw. Add ".gz" to the name of the file to have it compressed when saved, or ".gpg" to have it encrypted when saved (assuming that has already been set up), or add both.

# buffers, views, and frames

A simple listing of all buffers is available with the command ESC x list-buffers (shortcut: Controlx Controlb). Or, use ESC x ibuffer for ibuffer mode with more features for sorting, filtering, marking, and general organizing of a long list of buffers. (Again, Controlh m shows help for the mode in a view.)

More than one view of the same document is possible, such as when desiring to view different parts of the document simultaneously instead of scrolling back and forth. Simply show the buffer listing in a view and choose the buffer with the same document already shown in another view. Or, use ESC x switch-to-buffer (shorcut: Controlx b) to switch to it by typing its name at the prompt in the minibuffer at the bottom (and with tab completion). In other words, it's possible to have more buffers than views, or more views than buffers.

It's worth keeping in mind emacs has tiled-view management rather than the typical overlapping-view management. (A view is sometimes referred to as a "window" in operating systems (OSes) like macOS or MS Windows, or other OSes might have a "window manager".) A tiled layout means all views are always visible from edge to edge, never obscuring each other, and no wasted space.

There's no need for micromanaging widths and heights of views (though it is possible). Simply use the whole screen for emacs and then split its height in half (new view below) with Controlx 2, or split its width in half (new view on right side) with Controlx 3, as many times as desired. Equally distribute the size of all the tiled views with Controlx +. The computer does the computing.

Close (kill) the buffer/document in the current view with Controlx k RET and then the next most recent buffer is shown in the same view, keeping the layout the same. Collapse a view to nothing (without closing the document) to give its space to a nearby view with Controlx 0 (zero), and the document remains available in the list of buffers. Or do both: collapse the view and close the document shown within it at the same time with Controlx 4 0 (zero), for less clutter.

For example, imagine the whole screen is one view showing the contents of a document. After splitting the width of that view in half with Controlx 3, the right half shows the same content as the left half, and the left half retains the focus. Scroll a few pages down in the left half and the right half will stay still, it retains the original position. Split the width of the left view in half and there will be a new right half. Both are one-quarter of the screen width because they began as the left half of the screen. So, three views of the same document: two views are one-quarter of the screen width, one view is one half of the screen width. Now equally distribute the three views with Controlx + and the width of each will become one-third of the screen width: left, middle, right. The left still has the focus, so now close that one with Controlx 0: its area is merged with the middle, and now has the focus. That means there are now two views: the left view is two-thirds of the screen width, and the right side is one-third of the screen width.

Of course, a document can be edited at any time in any of its views, they are all functional. That can make it easier to copy/cut from one section of a document and then past in another of its sections, while being able to see both places at once.

Switch the focus to the other view with Controlx o, either from top to bottom or from left to right. Or, switch to the other view in the other direction with Control- Controlx o. Or, switch the focus to any view with command repeatability, f.e. switch to the fifth next view with Control5 Controlx o.

Therefore there is nothing to move because views are always aligned edge to edge, and no listing of views because they are all visible. Instead, peruse a listing of buffers/documents, or a dired listing ("directory edit" mode). Just choose what buffer/document is shown in a view, split a view in half for viewing the same buffer/document or for showing another one, and collapse any view no longer needed in order to give space to everything else.

With that said, it is worth knowing that all views are together within a frame, and it is also possible to have more frames. For example, using emacs with the whole screen means all the views are in a frame that is the size of the whole screen. Creating another frame the size of the whole screen would obscure the other frame. However, in this way it would be possible to have multiple layouts of views because each frame would have its own set of views showing whichever buffers/documents have been chosen for them.

Multiple frames within emacs is akin to virtual desktops implemented with over-lapping views of most every window manager of most any operating system (OS). But with emacs, this is without wastefully displaying an iconic directory listing of an unchangeable default directory that can't be accessed beneath overlapping views. Instead, in emacs any directory is listed with dired mode in any view of any width/height without having to hide everything else, and unlike a desktop such a directory listing can be closed whenever no longer needed.

# getting to know emacs

Mac OS X is notorious for having an ancient version of emacs, and macOS is no different. Best to find and install the latest emacs on macOS instead.

Starting emacs will show a message saying to start the tutorial with C-h t, which means to use the CONTROL key to type Controlh and then type t. (Recall from the shortcuts description that the CONTROL key is used like the SHIFT key.)

After completion of the tutorial, it's worthwhile reading manual sections 30, 17, 13, and 44 sooner rather than later, t.i. rather than starting with section 1. As revealed with help on help (with Controlh Controlh), the emacs manual can be referenced at any time desired with Controlh r by means of Info mode.

The latest emacs manual is also available at the developer's website.

When reading anything in Info mode the node name for a page can be seen at its top. A name in parentheses indicates the manual name, and after the parentheses is a section name. The node name for a page can be instantly copied with c regardless of where the cursor is located, and then the name is also temporarily shown in the minibuffer. The manual name in parentheses is needed only when changing manuals.

Use g to go to a node by name, then the minibuffer at the bottom will prompt with "Go to node: ". The keyboard shortcut ESC ( (for ESC x insert-parentheses) inserts a pair of parentheses and places the text cursor in between them. Tab completion for typing manual page names is possible, as expected.

For example, Controlh i evokes Info mode with a listing of all available manuals. Type g and then the minibuffer at the bottom will show the prompt "Go to node: ", then type (ses) to switch to the "Simple Emacs Spreadsheet" manual. Or, type (emacs)Rmail Basics to switch to a page within the rmail section in the emacs manual. Or, type (emacs)Rmail TAB to use tab completion to reveal in another view a listing of emacs manual page names beginning with "Rmail".

# SPOILER to the emacs manual

Note that section 17 is about the "editing macros", which is the namesake of emacs. It's the basic premise of ancient science fiction about computers: at the touch of a button a computer does whatever is desired, no computer programming necessary.

In short, F3 starts memorizing all keystrokes as a new macro until F4 is typed to end recording it. Then each time F4 is typed, whatever keystrokes were memorized are done again. Note that commands are typed, shortcuts are typed, text is typed, and so on. Therefore, any series of actions ever done in emacs can be memorized by the computer as a list of instructions, and then it can be repeated at the press of a button.

Select a document in dired, open it, search for a specific location in the text, insert a copy of some text, save and close the document: repeat. Anything that becomes repetitive can be recorded and repeated. There can even be moments when a macro queries whether to continue, which also allows for doing something different at any time within the middle of a macro, as many times as helpful. To emphasize again: no programming necessary at all.

Of course, a macro can be repeated a specific number of times, too. For example, type Control4 2 for 42, and then type F4: the prior memorized sequence is performed that number of times.

With emacs, the computer does the work. Just show it how. No computer engineer needed, no code needed.

# email is text

Reading email in emacs is quick and simple with rmail, t.i. ESC x rmail. The key factor is installing mailutils for accessing IMAP email accounts. Consider using this alternate rmail.el.gz library for checking email from multiple email accounts.

Sending email works simply. Configuring requires setting at least two variables: send-mail-function, message-send-mail-function. Consider using this alternate smtpmail.el.gz library for sending email from multiple email accounts, and also obviating a slew of other variables.

# ImageMagick