Browsed by
Category: Writing

Moving to Markua

Moving to Markua

I decided to move Painless Git from “Leanpub-Flavored Markdown” to Leanpub’s newer, fancier Markdown variant Markua. This wasn’t a decision I made lightly. I’ve built up a fairly slick workflow around LFM and publishing from Scrivener to Leanpub and out to the world. But in the end the benefits far outweighed the costs. Especially since the effort-cost was fairly low.

What were the Benefits?

Glad you asked, imaginary question asker! Let’s go down the list:

Future Proofing

Leanpub is putting more effort into Markua than Leanpub-flavored Markdown, which makes sense. Markua is very focused on making it easy to write books and full-on courses using nothing but a markup language. They have put a lot of thought into streamlining all the “fiddly bits” of writing, things like including images, or text figures, or code snippets, or what have you. All of these includes have features in common, and Markua reduces the differences to where including a JavaScript file is really no different from including a picture.

Easier Publishing Through Better Markup

Using Markua means I no longer have to maintain three different meta-information files:

  • A book.txt to tell Leanpub which files were in the main, published book.
  • A sample.txt to create an abbreviated sample version, to give readers a taste but not the whole thing.
  • Optionally, a preview.txt file, which would just generate a tiny little preview for you to see if your formatting was working correctly.

My fancy Python/Git hybrid solution that I wrote about last year handled the book.txt file, but I had to maintain the other two by hand, which means that I didn’t. I never really did small previews, and I never had a sample version.

That whole system is no longer necessary! I now have one book.txt file and it has one line in it:

manuscript.txt

Since I can now use markings in the text itself to dictate which sections are included in the published book, or in the sample book, or neither, or both, I simply use Scrivener’s impressively powerful “Compile” feature to output a single manuscript.txt file.

A directory containing my manuscript and that one-line book.txt now lives in a shared folder. Leanpub can grab that file when I hit the “publish” button and it all just…works. All that stuff I used to have to do with numbering folders and files and auto-generating a book.txt file? Gone. All that file juggling to keep my images out of the manuscript directory while python was doing stuff, but putting them back when python was done? A thing of the past. Things just got a whole lot easier.

How Hard Was the Hard Part?

But this was an effort, right? There was some work involved in the change, right?

Well, yeah. But not really a ton. This is my list of tasks that I put together while working on the conversion:

Change my italics

In most Markdown variants, _this_ and *this* both make italic text. I’ve used both more or less interchangeably, but I tend to find underscores easier to type. In Markua, _this_ will be the markup for underlined text instead of italics. So I had to change all _underscore italics_ to *star italics*. I do like me some underlines, but over-using them is a bad plan. As of this writing Markua still seems to be treating _this_ as italics, but I don’t want to suddenly have that change on me.

Change “Part” Markers

Easy:

  • Old: -# Part name.
  • New: # Part name #.

The manual says this will change again soon, but I can live with that. There are only four “parts” in my book anyway.

Update Chapter Headings

I include ID tags for chapters so I can cross-link between parts of my book. I had to convert those id tags from # Chapter Name {#chapter-name} to:

{id: chapter-name, book: true, sample: false}
#Chapter Name

Which looks more complicated, but is far more useful. (And I’ve automated away the complexity, but we’ll get to that.) This new version is a large part of why I decided to switch to Markua, as I mentioned above. Handling it this way makes the management of the book so much easier, and allows me to keep unwritten sections out of the published book without doing any fancy trickery with exports and whatnot.

Fix Code Blocks

The old style:

{lang="java"}
~~~~~~~~
class Stupid{
public static void main (String[] args){

}
}
~~~~~~~~

Was never super popular, even in markdown variants that supported it. The new style is basically “fenced code blocks” as used by every Markdown variant:


```java class Stupid{ public static void main (String[] args){ } }

“`

Markua also has other plans to make the whole “text figure” system more consistent with images and imported code and all manner of cool stuff.

Miscellany

Actually, that’s all I had to change. All my other markup, like asides and tips totally still work. Best of all, footnotes still work as they always have. ✅

Markua adds a lot of enhancements to asides, but they’re non-breaking, so I can add them in as I get around to revising.
In addition to normal footnotes, they’ve added an endnote notation that, should I ever want to create endnotes, I can now do that. That’s right, I can two different kinds of witty little bits o’ text.

Updating TextExpander Snippets

I use TextExpander to automate some of the repetitive parts of books, like markdown links and chapter headings. The main change was to my “Create a new chapter” snippet, as previously mentioned.

In the update process I discovered that TextExpander has cool little macros that let you choose the state of the book and sample thing without all that tedious typing, saving me of four or possibly even five keystrokes. Fancy.

Display the TextExpander UI for creating a Markua Title.

Conclusion: If You’re Using Leanpub, You Should Be Using Markua

Overall the process took about four hours, and now I’m back to writing. Aside from the italics thing my writing has stayed the same. I use the same TextExpander snippets that I used to use, they just create Markua style output now.

And my publishing workflow is drastically easier. Here are the steps it used to take:

  1. Export the files, using Scrivener’s awesome defaults.
  2. Check the files into git
  3. Commit
  4. Push
  5. Ensure that book.txt was updated correctly by my Python script. (It always was, but I’m paranoid, even of my own code)
  6. Hit the publish button on Leanpub.

Versus the new workflow:

  1. Compile the manuscript using Scrivener’s awesome compile feature. Scrivener remembers all my settings so this is literally a single button press.
  2. Hit the publish button on Leanpub.

And now I can start looking forward to all the other things that Markua can do , once the text is complete…

Using Camp NaNoWriMo to Get Back on Track

Using Camp NaNoWriMo to Get Back on Track

I’m down to the final…four months of my program. It feels like both a lot and not that much. But dang ol’ school has been getting in the way of my book, Painless Git.

So I can’t promise that I’ll be doing huge work, but I’m going to promise a solid hour a day working on Painless Git, and you can keep track of my progress on Camp NaNoWriMo!

Also, I’ll start publishing updates again, of course. Today I finished the first draft of my chapter on using SSH to connect to remotes instead of HTTPS, and worked on the chapter on Stashes.

Face to Face with Tremain

Face to Face with Tremain

Leaving work late at night, its dark out and there’s nobody around. The train home is almost empty.

I get on board and fall into a seat. I had to pick this seat, Because across the aisle from me is Tremain.

Well, not really. I’m not sitting across the aisle from a person I made up. I’m sitting across the aisle from someone I saw on the train a year or so ago and meticulously detailed in my notebook, realizing that he was who I was looking for as a template for this character I’ve invented.

Alan Tremain is a weary detective in a story I made up that needed a POV character to anchor the action, give it context. I’d gone back and forth on who he is, and in early drafts, his personality bounces between far-too-affable to far-too-weary. I needed a face; someone for him to “be” while I figured out who he was.

And then I saw him.

I don’t know this person’s actual name. I don’t know anything about him, except for how he looks.

Tall, thin, with a pinker-than-normal cast to his skin. Short cropped gray hair, white-blue eyes and a small white goatee around his mouth, trimmed precisely and grown out to about a quarter inch. Wearing a black coat, waist length and built for action. No ring on his left hand but there’s a slight depression around his ring finger, a mute testament that there used to be one there. A faint, sardonic smile on his face. Unlike everyone else on the train he’s not looking at his phone, he’s looking out the window; one long leg bent with his foot resting on the radiator that runs along the inner wall of the train, under the seats.

But that was a year ago. My actual notes were hand-written, scribbled into a Field Notes memo book that now lives under my bed. I have a high-security system for my hand-written notes: my handwriting is terrible. Once I got out of eyeshot, I wrote up the note you see above.

And over the intervening year, this unknown fellow passenger has turned to Tremain. My detective. I’ve been thinking about this face and how he interacts with a bunch of other people I’ve invented. He doesn’t know that, of course, and, intellectually, I know he doesn’t know. But I want to grill him, ask him questions about parts of the plot that are getting away from me because he’s seen them, he’s lived them. Except of course he hasn’t. I want to ask him questions about who he is as a real person, what he likes, what he eats for dinner, how the divorce went, who got the kids if there were kids. Except I’m pretty sure that the answer to “what do you dislike” would be “strangers who ask surprisingly intimate questions on public transportation.”

So I say nothing, sitting across from someone who is incredibly important to me, someone I’ve never met.

Will Write for Money

Will Write for Money

You may have noticed a new button over there on the right. Looks like a mug with a heart on it. Looks kinda like this:

Yeah, that’s the one. what’s that lil’ guy doing there?

Here’s the thing: back in the day I ran ads on my blogs. They never brought in all that much money, usually just enough to keep the lights on. But I never liked it. I’m not some fancy auteur who thinks I’m “too good” for advertising; I just don’t like feel of ads, they’re a distraction from the content.

So here’s my new solution: a tip jar. If you like this site, and you have a few bucks to spare, I’d love it if you drop me a tip.

ko-fi is great because every cent you drop in there goes directly to me. no middle men. I like that! 😆 Right now I’m playing with “ko-fi Gold” which costs me $6/month, but if three people every month chip in I’m still in good shape.

And Here’s What You Get

But this isn’t just a one-way street. When you drop me a tip in ko-fi you can make a little comment along with that tip. Why not make it an idea for a story or an essay? If it’s family friendly I’ll write it up and post it to ko-fi as a (timed) subscriber-only post.

Beyond being family friendly I really don’t have any limits. If you want me to write about you waking up as a bear in a new version of the Metamorphosis I’m game. If you like one of my stories or series and want more of that you can just yell “MOAR ANGEL LIZ” in the comments and I’ll get the hint. And you’ll have access to an Angel Liz story that won’t be on the site for at least 30 days.

Like I said, this is an experiment. Running these blogs isn’t exactly breaking the bank, but it’s not free either. I can’t wait to see what kind of weird stuff you wonderful people want me to write.

Automation for Authors

Automation for Authors

Or: Writing with Python

I really love Scrivener. I may have mentioned this before. And I really love Leanpub. And for the most part, they work really well together. But there’s always room for improvement. And tonight I have added yet another layer of sophistication to my workflow. I’m pretty excited to share this with you.

The Workflow

Here’s a high level overview of how this all works:

  1. Write in Scrivener
  2. Export text files from Scrivener
  3. Check text files into a git repository shared with Leanpub
  4. Tell Leanpub to publish the book

Scrivener: Writing and Exporting

In Scrivener, you write all your text in little individual sections that you can move around at will. This is incredibly handy. If you decide the chapter on configurations should be in Part I: Beginning instead of Part II: Refinement you just drag it to the appropriate folder and you’re good to go. You can then export all these snippets as text files, and Scrivener will keep your file structure intact, like so:

A list of topics in Scrivener

Which turns into this on export:

The exported files from Scrivener

But where did those numbers in the file names come from? They came from here:

Scrivener Export Options

So now we’ve got a directory full of directories full of text! Let’s send it to Leanpub, right? Well, we need to do a little work first.

Prep for Print: The Leanpub Stuff

If you just give the Leanpub book generator a pile of text files it doesn’t know what order they should be in. So you provide it an extra file, book.txt, that includes all of your text files and the order in which they should be put into the book. The current book.txt file for Painless Git looks like this:

1 Front Matter/1 frontmatter.txt
1 Front Matter/2 Book Status.txt
1 Front Matter/3 Preface.txt
1 Front Matter/4 Introduction.txt
1 Front Matter/5 Structure.txt
2 Main Matter/1 mainmatter.txt
2 Main Matter/2 Beginning/01 Part 1.txt
2 Main Matter/2 Beginning/02 A Brief History of Git.txt
2 Main Matter/2 Beginning/03 Installing.txt
2 Main Matter/2 Beginning/04 First Steps.txt
2 Main Matter/2 Beginning/05 Commit.txt
2 Main Matter/2 Beginning/06 Interlude Tools.txt
2 Main Matter/2 Beginning/07 Branching.txt
2 Main Matter/2 Beginning/08 Configure.txt
2 Main Matter/2 Beginning/09 Sharing.txt
2 Main Matter/2 Beginning/10 Oops.txt
2 Main Matter/3 Refinement/01 Part 2.txt
2 Main Matter/3 Refinement/02 Good Git Habits.txt
2 Main Matter/3 Refinement/03 Small Commits.txt
2 Main Matter/3 Refinement/04 Hygiene.txt
...

When I wrote Painless Vim and Painless Tmux I kept this book.txt file up to date by hand. It was just another text file in Scrivener. So when I added a new section to the book I would go into book.txt and add each new section. The benefit to doing it that was was that I could work on a new section for a while before it got added to the book. The downside, of course, is human error. Sometimes I would add a new file in the wrong place, so chapter two came before chapter one. Or I would update the order in Scrivener and not update it in book.txt, which meant that when I published a new version it didn’t include my new chapter, and I had to fix book.txt, then publish again immediately. Whatever the case, sometimes book.txt got out of sync with reality.

It’s so easy to get files lined up in Scrivener and once you’ve done it in Scriv you shouldn’t have to do it again in book.txt. If you’re a developer the words “write a script” are already foremost in your mind, aren’t they? What if we could hook into git’s workflow to generate book.txt just before we commit?

Oh right, we can.

Python and Git Hooks

So now you need to create book.txt programmatically from your actual file structure. You’ve got numbered everything, so you can just recurse through the directory, find each leaf node and then prepend its path, and you’ve got a file path, right?

You just did too much work. Python is made to make things easy. os.walk will find every file in your directory and all subdirectories. I wrote a short python script that finds all the files, puts them in order, and then calls git add book.txt. Make that executable and save it as /painless_git/.git/hooks/pre-commit and you’re in business, my friend.

So now I no longer have to manage book.txt by hand. Using the features in Scrivener and in git, I’ve made it that much more painless to write Painless Git.

I’ve also come up with a good excuse for why I haven’t added any actual text to Painless Git today.

Introducing Painless Git

Introducing Painless Git

I have a three week break between summer and fall terms in my MBA program, so naturally I decided to write a new Painless book. I’m excited to announce Painless Git, the third [1] book in the Painless series.

The most common request I have received is for a book on something people actually use. And I’m well positioned to write this one. Unlike Painless Vim, which I wrote to help me learn vim, or Painless Tmux, which I wrote to help me learn Tmux, I’m actually already pretty good with git.

At my last job I helped move the entire 600+ developers in our organization from subversion to git, and spent months training individual teams on the new system. Then I switched jobs and moved our team here from subversion to git, and trained them on it. In my time as the “git guy” I’ve seen just about every git mess people can cause and found my way back out of most of them.

So Why Are you Writing This Book Now?

For years I’ve resisted writing Painless Git. I kept coming up with excuses like “I want to write novels!” Or “My wife just had another baby!” Or “I’m getting an MBA and it’s really hard!”

But then a wonderful thing happened: I have been put in charge of a brand new team of developers and guess what? It’s time to teach them git. Faced with this prospect I thought “I could dig up all my old presentations and cheat sheets and teach this team git over the course of a few weeks, or I could spend the next year or so finally writing Painless Git. As I’ve already demonstrated, it doesn’t take much to push me over the edge.

I’m very exited to share this one. Painless Git is a distillation of the tips, tricks, methods, and patterns that I’ve been teaching to teams from one part of Salt Lake City all the way to a suburb twenty miles outside of Salt Lake City. These are patterns and recommendations that have been battle hardened and stood up to old SVN pros and brand new interns alike.


  1. and final. I mean it this time!  ↩
Prism, Not Mirror

Prism, Not Mirror

My story, To: The Lady on the Train has gotten a lot of praise, for some reason. I’m still learning what people actually like in my writing, and sometimes things just catch.

But the criticism that has been leveled against it is that it’s not really fiction, because it’s so clearly based on something that really happened. This is somewhat confusing to me, because everything I’ve ever written is based on things that have really happened. Sometimes I put dragons or spaceships (or dragons on spaceships) in the mix because I like dragons and spaceships. But the core of every story is the world around me.

It’s been said that art holds a mirror up to life, but I disagree. If I had tried to directly reflect the experiences that seeded To: The Lady on the Train the piece would have been a lot longer and a lot less focused. It would have contained all the little pauses and moments where I had to say “I’m sorry, I couldn’t hear you, what was that?” Things like that are real but not good fiction. I took a forty-five minute conversation, edited out all the parts that didn’t fit the narrative I was trying to relate, simplified and clarified the things that made my point, and that’s what you got.

Instead of a mirror, I would say that art acts as a prism. Any work of art refracts out a part of the artists’s experiences. Life doesn’t fit on the canvas or the page. Ideas, feelings, themes; those are things you can distill out and communicate. If an artist of any stripe has done their job the authenticity of that idea, feeling, or theme will resonate with you and you will feel the truth of it.

Perhaps, if you take all the creative output of our entire species, every story, every song, every sculpture, every YouTube video, every podcast, every painting, every drawing, every poem, every hastily scribbled love letter; perhaps then you would get something approaching a “mirror”. But, like a reflection, it would still be a shallow, flat copy of an infinitely deep reality.

Daft

Daft

You used to be witty and wise? Me too!
But now I’m so daft it’s depressing.

Pull up a chair, let’s sit here and share
A laugh at how fast we’re regressing.

NaNoWriMo Year Nine

NaNoWriMo Year Nine

I’ve been participating in National Novel Writing Month so long they needed a second row for a

nano-history
Purple means “won”, teal means “participated.” The Halo means I donated.

ll the icons. Next year I hit double digits. And what have I gotten out of it? Have I published any novels? Am I famous? Or am I just wasting my time?

Well, neither. No, I haven’t published a novel, but that’s not because I haven’t been writing, or because NaNoWriMo is useless to me. But I have written a lot, and have sharpened my skills, and kept my hand in as I go through a lot of life stuff.

And I’ve written and self-published a couple of tech books, something I never thought I’d do. I’ve loved that experience as well.

I’ve found the confidence to keep writing even when it feels like it might just be pointless, even when the book I’m working on feels like a train wreck. And I’ve found a large community of helpful people and resources that help me see the value in pressing forward in my noveling even if it never will make me rich and/or famous.

I honestly believe that creativity is its own reward. I’m greateful to NaNoWriMo for encouraging that belief.