Chapter 1 - Where We Set Things On Fire
The majority of writing is simply the process of arranging letters into words and then grouping those words: paragraphs, chapters, and novels. This is true regardless if you're are writing in a publishing program like Microsoft Word or a text editor.
However, readers expect a little more than just the words across the pages. There are various conventions used, such as typographical quotes, italicizing the names of novels or ships, marking elements as bold, or using block quotes while writing. I personally use epigraphs heavily in my writing and a number of writers like section breaks.
Programs like Microsoft Word will do this automatically, working with text files requires hints to be given to the formatters to produce the same results.
Plain Text
One of the goals with text files is to have the “source” of the project contain the original narrative and intention. That means if we need an italic or something else, it remains in the source file. There is also a balance since we don't want to litter our words with extraneous formatting codes and hints.
She giggled. \enquote{No! I\rq\m right here!}
The above example isn't reasonable, just an exaggeration of formatting codes. Ideally, we want the formatter to figure out most of the fancy stuff without having to call it out and then use as minimal of a markup to indicate the ones that cannot be automatically inferred.
She giggled. "No! I'm right here!"
Typography
In Microsoft Word, the program will change the single quotes (' and ") into typographical variants (’, “, and ”). This is done on the fly but can be undone with a Control-Z.
She giggled. “No! I’m right here!”
In the above example, “I’m” is written as I'm and the quote marks are typographical quotes, also known as fancy quotes.
This means that the author will continue to see and write single quotes but the resulting EPUB or PDF file will have the fancy typographical ones.
🛈 When I first started writing with text files, this is one of the hardest struggles I had. I was so used to making sure all the quotes were right, that the italics looked right, and epigraphs where indented “just write” but with text files, that's the job of the formatter, and I had to trust it would work out in the end.
Substitutions
The substitution of simple characters into typographical ones is dependent on the tools being used, but common ones are:
- Typographical quotes
- Converting
...into elapses (…) - Two or more dashes converts into en-dash (–) or em-dashes (–)
The number of dashes is one of those tool-specific substitutions. This garden plot and my own writing use -- for en-dash and --- for em-dash.
Formatting
There is another category of common writing conventions that cannot be done easily with pure text and copy/pasting: formatting. These are things like italicizing the name of a ship or a foreign word, block quotes, headers, and section breaks.
To do those, “markup” is used to identify what need to be formatted. Today, the most common form of lightweight, text-based markup is Markdown but there are others.
Markdown can't do much more than normal text, but it covers the common cases used by most writers:
- Making something italic by using
*italic* - Bold formatting with
**bold** - Block quotes and epigraphs using
> - Headers with
#,##, and###
Headers
Normally with plain files, there needs to be exactly one top-level header (also known has “H1” or “Heading 1”) at the top of the file. Headers underneath it should be one additional # to signify higher level headings.
Something happened.
## Heading 2
This is a second-level header.
### Heading 3
This is a third-level header.
## Second Heading 2
This is the second second-level header.
However, with top matter, the first level header is folded into the YAML matter as a title property.
---
title: Chapter 1 - Where We Set Things On Fire
---
Something happened.
## Heading 2
This is a second-level header.
### Heading 3
This is a third-level header.
## Second Heading 2
This is the second second-level header.