mdlbear: (technonerdmonster)
[personal profile] mdlbear

A few years ago I read an article about how to set up a Mac for distraction-free writing. I can't seem to find it anymore (okay, some rather large value of "a few"), but "there's an app for that" now. Many writers on my reading list are talking about distraction-free writing tools like iA Writer (seems to be the one people are most impressed by at the moment) and FocusWriter (free and cross-platform). There's even an Emacs mode.

These all work roughly the same way: run a text editor in full-screen mode, and write plain text with simplified markup in a fixed-width font. Worry about formatting later, if at all. Grey out everything but the sentence or paragraph you're working on. The article I can't find -- written before specialized writing programs and even before the web -- suggested getting the same effect by taking all of the icons off your screen and setting your default font to Courier.

If you're happily using one of these tools, you may want to skip ahead to the section on formatting, and maybe fill in the gaps later. If you're still using a word processor, or typing into a text field in a browser (even in "rich text" mode), you should probably stick with me.

What You See is All You Can Get

WYSIWYG (What You See Is What You Get) word processors are arguably the worst thing to have happened to writing in the last half-century. They have three huge problems:

The first is that they make a promise they can't deliver on. In fact, they should be called WYSIAYCG -- What You See Is All You Can Get. If your word processor doesn't support kerning, multiple fonts, paragraphs with hanging indents large initial capitals, mathematical notation, or internal cross-linking, you can't use them. If they make it difficult to use these features, you still won't use them unless you absolutely have to, and then you find yourself wasting time doing clumsy work-arounds. Think about how you'd go about formatting song lyrics with chords over them. Shudder. How about making the space between sentences equal to one-and-a-half times the space between words?

The second is related to the first: word processors target a specific page layout. If you want to make a printed book, a web page, and an eBook, you're going to have to do extra work to accommodate the differences, or settle for something that has about the same level of mediocrity in all of those environments.

At a lower level, word processors use proportional-spaced fonts. That means you have to peer over the tops of your glasses to see whether that character at the end of the sentence is a period or a comma, and if your hands are shaking from too much coffee you'll have trouble selecting it. Or putting the cursor in front of it without selecting it, if you want to add a few words.

The third is that they distract you from actually writing, tempting you to fiddle with fonts, reformat your footers, worry about word-wrapping and hyphenation, and place your page breaks to avoid widows and orphans, at a time when you should be concentrating on content.

There's a fourth, mostly unrelated, problem which is so pervasive these days that most people accept it as The Way Things Are: if you accidentally select something and then type, whatever you selected goes away. In almost all cases, even if your word processing has an "undo" feature, this can't be undone. So let's talk a little more about...

Editing

Anyone who's been hanging around me long enough is expecting me to mention GNU Emacs at some point, and I will. But there are plenty of other text editors, and most of them are perfectly usable. They're often called "programmers' editors".

I'm not going to tell you how to use a text editor here; I'm just going to tell you more about why, and point you at some resources. Michael Hartl's Learn Enough Text Editor to Be Dangerous is a pretty good introduction to most of them, though you may want to skip the chapter on Vim. It gives short shrift to Emacs, but fortunately the first thing on your screen after starting Emacs is the tutorial. Start there.

So, why would you, a writer, want to use a programmer's editor?

One reason is that programmers have been writing on computers for a quite a bit longer than writers have, so text editors have a considerable head start. More to the point, programmers use their own programs. This gives them a strong incentive to make their programs fast, efficient, and powerful. Not every programmer who has a problem with their text editor is going to fix it, but enough do to make them improve rapidly.

Word processors, on the other hand, are written by programmers, but they are usually written for ordinary users, not experts, and they're written to be products, not programming tools. As products, they have to appeal to their customers, which means that they have to be easy to learn and easy to use. They don't have to work well for people who spend their entire work day writing -- those are a tiny fraction of the customer base.

Another reason is that text editors use fixed-width fonts and encourage you to use comparatively short lines (typically 72 or 80 characters, for reasons that date back to the late 1880s). Paragraphs are separated by blank lines. Since line breaks inside of paragraphs are ignored by formatters, some authors like to start every sentence on a new line, which makes them particularly easy to move around, and makes it easier to spot differences between versions.

A text editor also makes you more efficient by giving you a wide range of keyboard commands -- you can write an entire book without ever taking your fingers off the keyboard. (This is, in part, due to their long history -- text editors predate graphical user interfaces by several decades.) And most modern text editors are extensible, so that if you want new commands or want them to behave differently for different kinds of markup, they're easy to add. (I have a set that I use for my band's lead sheets, for example, and another for my to-do files.)

Markup

Up until somewhere around 1990, everyone who did any serious writing knew how to edit a manuscript using proofreaders' marks. Manuscripts were typed double-spaced to leave room for insertions, corrections, and cryptic little marks between the lines and in the margins. This was, logically enough, called "marking up" the manuscript. You've probably heard of Markdown. You've certainly heard of HTML, which stands for "HyperText Markup Language". HTML, in turn, is a variant on SGML, "Standard General Markup Language". You may have heard of LaTeX, which is the standard for academic -- especially scientific -- writing.

Markup languages let you separate content writing from formatting. Semantic markup lets you add additional information about what the things you are marking up mean; it's up to a stylesheet to determine what they look like . In HTML, you don't have to <i>italicize</i> something, you can <em>emphasize</em> a talking point, or <cite>cite</cite> a book title. They usually look the same, so most people don't bother, until they decide to turn all the book titles in their two thousand blog posts into links.

You can see how using semantic markup can free you from having to think about formatting while you're writing. There's another, less obvious advantage: you aren't stuck with just one format. By applying different styles to your document you can make it a web page, a printed book, an eBook, a slide show, or an email.

Another advantage of markup languages is that all of the markup is visible. This week's xkcd: "Invisible Formatting", shows how you can accidentally make a boldface space in the middle of normal text, where it can distract you by making an insertion unexpecedly boldface. It may also make subtle changes in line and word spacing that are hard to track down down.

There are two main kinds of markup languages: ones like Markdown and Textile, that use simple conventions like **double asterisks** for strong emphasis, and the ones that use tags, like <cite>HTML</cite>. LaTeX and Restructured Text are somewhere in the middle, using both methods. You can be a lot more specific with HTML, but Markdown is far easier to type. Markdown and Textile let you mix in HTML for semantic tagging; Markdown, Textile, and Resturectured Text all use LaTeX for mathematical notation. Some formatters let you embed code with colored syntax highlighting.

These days, it looks as though Markdown is the most popular, in part thanks to GitHub; you can find it in static site generators like Hugo and Jekyll, and it's accepted by many blogging platforms (including Dreamwidth). Unfortunately they all accept different dialects of Markdown; there is an enormous number of Markdown-to-whatever converters. But the nice thing about markup languages is that you aren't stuck with just one. That brings us to...

Formatting

Once you have a file that says exactly what you want to say, the next thing you'll want to do is format it. Formatting programs (a category that includes LaTeX, web browsers, website generators like Jekyll and Hugo) all use some kind of style sheet that describes what each kind of markup is supposed to look like. You probably know about CSS, the "Cascading Style Sheets" that are used on the web. LaTeX has a different set, written in the typesetting language TeX.

If you wrote your file in HTML and you want to publish it on the web, you're done. You may want to make your own stylesheet or customize one of the thousands that are already out there, but you don't have to. Modern browsers do a perfectly reasonable job of formatting. CSS lets you specify a separate style for print, so when a reader wants a printed copy it actually looks like something you'd want to read on paper.

If you wrote your file in LaTeX and you want to publish it on paper, you're done -- it's safe to assume that LaTeX knows more about formatting and typesetting than you do, so you can just tell LaTeX what size your pages, pick one of the hundreds of available stylesheets (or write your own), and let it make you a PDF. You can change the page size or layout with just a few keystrokes.

If you wrote your file in Markdown or some other markup language, there are dozens of formatting programs that produces HTML, LaTeX, PDF, or some combination of those. (My favorite is Pandoc -- see below.) Markdown is also used by static website generators like Hugo or Jekyll, and accepted by everything from blogging sites to GitHub. If you're publishing on the web or in some other medium your formatter supports, you're done.

The advantage of separating content from format is that you're not stuck with one format. Web? Print? eBook? You don't have to pick one, you have all of them at your fingertips. There are hundreds of conversion programs around: html2latex, latex2html, kramdown (which GitHub uses),... For most purposes I recommend Pandoc. The subtitle of Pandoc's home page calls it "a universal document converter", and it is. It can convert between any of the the markup languages I've mentioned here, and more, in either direction. In addition it can output eBook, word processor, wiki, and documentation formats, not to mention PDF. As an example of what it can do, I write these posts in either HTML or Markdown as the mood takes me, and use Pandoc to convert them to HTML for Dreamwidth and plain text, stripping out the tags, so that I can get accurate word counts.

Version Control, etc.

Text files with short lines are ideal for other tools in the Linux (and Unix -- did you know that Unix was originally used by technical writers?) environment. When you compare two files, a line-by-line comparison (which is what diff gives you) is more useful than a paragraph-by-paragraph comparison (which is what diff gives you if you don't hard-wrap your text). Text editors can run formatters, spelling checkers, search tools, and others, and put the cursor on the exact line you're looking for. Want to search nearly 6500 blog posts for your favorite quote from G. K. Chesterton? Took me one line and a little over 4 seconds.

        time find . -type f -exec grep -nHi -e 'rules of architecture' {} +

Many formatting tools simply ignore single line breaks and use a blank line to separate paragraphs, examples include LaTeX and most (though not all) Markdown translators. HTML ignores line breaks altogether and relies on tags. I take advantage of that to make HTML more readable by indenting the text by four spaces, and using 80- or 90-character lines. If you want an example and you're reading this page in a browser, just hit Ctrl-U to look at the page source. Compare that to web pages made without hard-wrapped lines -- you may find yourself scrolling dozens, if not hundreds, of characters to the right because browsers don't do any wrapping when displaying source. Nor would you want them to.

The biggest advantage (in my not-so-humble opinion) is version control. (Those of you who've been around me were just waiting for me to mention git, weren't you?) Being able to find all the changes you made this week -- and why you made them -- can be incredibly useful. Being able to retrieve a file from three years ago that you accidentally deleted is priceless.

This post is already pretty long, so the next post in this series is going to be about version control (and the other things you can do with git and GitHub; it's not just version control) for writers. Stay tuned.

Resources

Another fine post from The Computer Curmudgeon (also at computer-curmudgeon.com).

Programming editors

Date: 2019-03-02 03:05 am (UTC)
librarygeek: cute cartoon fox with nose in book (Default)
From: [personal profile] librarygeek
Thank you! Some of this I've learned over the years, some it seems I have forgotten ever knowing. Information and library science uses some of these at times.

I'm still finding odd gaps from anoxia bouts the year before my open heart surgery to repair the congenital heart defects. :-/ Adding a tag for memory for me!

Date: 2019-03-02 07:03 pm (UTC)
kyleri: (Default)
From: [personal profile] kyleri
Ahh, this makes me miss early 90s Word Perfect, & Reveal Codes...

Date: 2019-03-03 06:19 am (UTC)
thnidu: A maze. www.promrds.com/chapter9/mazegenerator.htm (maze)
From: [personal profile] thnidu
Oh yeah, tagging this "memory". And maybe downloading it too... except I have so many different quasi-toplevel directories I have a hard time finding something that I parked someplace that seemed perfectly reasonable at the time.

  • my home directory on my Mac
  • my late wife's home directory, which things sometimes seem to default to
  • "Google Drive" on the laptop
  • "Google Drive" on the net??
  • "Creative Cloud"

and lots more at lower levels than these.

And it's even worse on my Android phone.

Date: 2019-03-03 03:54 pm (UTC)
mxsupermarinespitfire: Mx Supermarine Spitfire (Default)
From: [personal profile] mxsupermarinespitfire
I switched over to doing the majority of my writing in Sublime Text, which really does live up to its name. :)

Date: 2019-03-03 11:45 pm (UTC)
cellio: (Default)
From: [personal profile] cellio
For work I use an IDE for doc (Flare) but keep the XML view open because often that's just easier. I've been writing HTML, XML, and markdown in emacs for decades and prefer that.

You might be interested in an answer I wrote to a question about why writers should use source control. (No specific system covered there, and in fact this was before I started using git.)

Wonderful!

Date: 2019-03-06 09:14 pm (UTC)
jesse_the_k: harbor seal's head with caption "seal of approval" (Approval)
From: [personal profile] jesse_the_k
I've been writing "Why WYSIWYG Is a Lie" since 1985, and this is the best iteration I've seen.

Newline for each sentence is a new idea for me, and it kinda breaks my brain. Could this be why so few text editors have "sentence" as a functional unit? Seems like almost every editor offers cursor movement, delete, highlight by words, lines, and paragraphs.

Most Popular Tags

Style Credit

Page generated 2019-03-20 01:03 am
Powered by Dreamwidth Studios