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…

A Novelist in Business School: Zeno’s Paradox and Graduation

A Novelist in Business School: Zeno’s Paradox and Graduation

“A Novelist In Business School” is a series about putting my literary arts brain through formal management training.

Zeno’s Paradox (more specifically, Zeno’s Dichotomy Paradox)states that to cover any distance, you must first cover half that distance, then half of the remaining distance, then half of that distance… and so forth, the end result being that you can’t ever actually arrive anywhere.

Of course this is silly. We’ve all set to to get somewhere and arrived there. But right now it feels like Zeno might have been right. Even though objectively the time between me and graduation must be reduced every day by exactly one day, subjectively it doesn’t feel that way at all.

At halfway through my program I remember thinking “I’m halfway through! That was hard but it’s over now! I can do another half!”

Now I’m halfway through my last class. Objectively I have five weeks left. Subjectively I will never ever be done with school ever. The five weeks ahead of me feel just as long as an entire year felt eleven months ago.

Holistically Wrong: BBC America’s Dirk Gently Remake

Holistically Wrong: BBC America’s Dirk Gently Remake

I just finished watching the latest take on Douglas Adams’ lesser-known series, Dirk Gently’s Holistic Detective Agency. I’ve always loved the books, so I was excited to see that they were putting some budget behind this one. However it didn’t come out immediately on Netflix or Amazon Prime, so I more or less ignored it.1 Apparently I wasn’t alone. The series was cancelled after only two seasons, which apparently angered some people, but struck me as the right move. Let’s talk about why.

A Universe in Need of a Reason

The latest take on Dirk Gently feels like someone created a comic book-esque universe and needed a way to get it on the air. They had some very compelling characters. The Rowdy 3, for example, a four member ensemble of energy vampire punks. 2 Todd and his sister Amanda provide both an everyman in the form of Todd and an enthusiastic novice to the weird world in the form of Amanda. Bart, the holistic assassin, who kills people who need to die, is an interesting concept and a good compliment to the TV version of Dirk, the holistic detective, who seeks to solve crimes that need to be solved.

Not all the characters are great, of course. Alan Tudyk plays a character they call “Mr. Priest” but I called “Mr. Cliche”. Everything he says has been said by a dozen other man hunter characters. There’s a shapeshifter who speaks in a creepy little girl voice but is nice! Also there’s a guy from the Big Bad Organization who is possibly illiterate? But even if he can read he’s very stupid and looks like Vanilla Ice.

Anyway, I could have handled these characters If they had created this show centered around Amanda instead of Todd, If they had invented a new character instead of naming one Dirk Gently, I probably would have liked it better.

But it feels like Dirk was dropped into this world with little understanding of his character beyond “he seeks to solve crimes using the interconnectedness of all things.”

Yes, We See You Are a Fan.

The show goes out of its way to demonstrate their Douglas Adams fan credentials, mostly by referencing Hitchhiker’s Guide. Just a sample:

  • One of the characters wears a letterman’s jacket from “D Adams” high school with the number 42 on the arm.
  • There’s a dog named Agrajag, the character that Arthur Dent keeps killing on accident.
  • Dirk quite clearly says “DON’T PANIC” to himself at one point.
  • In a rare nod to the Dirk Gently books, Dirk mentions knowing Thor.
  • Another nod to the actual source: characters call Dirk Svlad a couple of times, his original name.

Dear the writers: We see you. Yep! you’re fans of Douglas Adams! Thanks! Good to know.

But if you’re a fan, why did you ignore the books?

My main complaint with the new series is that it completely ignores who Dirk actually is in the original series. Dirk might have supernatural powers, but he denies it, and in fact works hard to fight it. He talks a big game about the interconnectedness of all things, but when he’s alone, in the middle of the night, just looking for a cigarette, that’s all he’s doing. Yes, he still ends up in the right place, but at his core, Dirk doesn’t believe his powers are real.

In the television series, not only does Dirk believe in his powers, but Frodo, excuse me, Todd, ends up basically being Dirk’s first apostle. The shadowy bad buy organization has a whole collection of these special people, like a more evil X-Men. Dirk (and Bart) keep saying things like “It doesn’t work that way,” whereas the original Dirk Gently would vehemently deny that there was any “it” that worked in any way. Making Dirk actually special made him less interesting.

Where Dirk Came From

Admittedly, Adams’ works have a history of being changed and warped over time. The entire history of Dirk Gently reflects that:

The original Dirk Gently was created out of a script for Doctor Who that never aired. The original story is called Shada and if you want to experience a good rendition of one of Adams’ old scripts read Gareth Roberts’ novelization of that story. It’s excellent.

Douglas Adams took Shada filed off all references to Time Lords or TARDISes or Gallifrey, created Dirk Gently by crossing the Fourth Doctor with Stanley Featherstonehaugh Ukridge, a character created by P.G. Wodehouse.3, And magic was born. This isn’t the first nor the last time Adams would plunder his own works; the second Dirk Gently novel The Long Dark Tea-time of the Soul, got its title from a line in the Hitchhiker’s series, and its plot from a party in the same series. Going the other direction, the plot of one of the Hitchhiker’s books stems from yet another unaired Doctor Who script Adams wrote called Doctor Who and the Krikketmen .

Your point?

My point is this:

The BBC is very good at making word-for-word adaptations of great books. They’ve made a number of shows based on Terry Pratchett’s Discworld, they’ve remade Pride and Prejudice more times than anyone can count, and they’ve always stayed true to the source material. I want the same treatment for Dirk Gently.

One thing you should have noticed winding through that history is that Douglas Adams was a screenwriter, and a very good one at that. The Dirk Gently novels are already screenplays. It would take very little work to bring the original Dirk to screen, and 80’s retro is in right now. Show us Dirk in all his disgraced glory, unsure of himself, bombastic and worried, wearing a stupid red hat. Show us his battles with his cleaning lady and his fridge.

Let us see Dirk the way Douglas first wrote him, working the cases Douglas gave him.


  1. After all, this isn’t the first time someone tried to bring Dirk to the small screen. In 2010 BBC Four made a show just called Dirk Gently that only made it four episodes before being scrapped. 
  2. They may have been an oblique reference to the Hitchhiker’s Guide to the Galaxy, a trilogy that eventually ends up with six books still gets called a trilogy because it’s funnier that way. 
  3. I can’t prove that, but Adams was very forthcoming about his love of P.G. Wodehouse and….look, read the Dirk Gently books, then read an Ukridge story and tell me they aren’t related.). 
Experience is Sedimentary, Wisdom is Lamellar

Experience is Sedimentary, Wisdom is Lamellar

Concerning the metaphors for learning we use:

For a long time I understood learning as  sedimentary. We learn by the slow, steady accretion of experiences, based on our choices and the nature of the world. As we subject what we’ve learned to the “pressure” of testing, it hardens into sandstone (knowledge) and—given enough time and pressure—granite (wisdom). 

But there’s a problem with this analogy: passivity. The accumulation of sediment isn’t selective; sediment is whatever lands in that spot. There’s no place in this analogy for the conscientious, deliberate quest to gain specific experiences that will contribute to your knowledge in a desired field.

The part of the sedimentary analogy that resonates with me is the slow, steady growth. We don’t become experts without effort. If you want to achieve mastery, no shortcuts exist; we must stack those ten thousand hours up, at a rate of one hour per hour, during our steady, purposeful practice of the craft. 

So I’ve been searching for a better analogy. This isn’t a red-yarn-on-corkboard search. Just a question mark, sitting quietly in the back of my mind, looking for something better. 

And as I’ve been reading and thinking (and thinking about reading and its effect on thinking) one word has quietly brought itself into my mind, subtly asking for my attention:

Lamellar

Admittedly, not a word most people use. Just looking at it, you sense that it’s related to “laminate” which as a verb usually means “put between two sheets of plastic and seal it there” and as a noun refers to a flooring made of fine sheets of wood grain, stacked and pressed. A feeling of “layers coming together” emerges.  And that‘s what it means. A lamella is a small, thin plate-like structure. Something is lamellar when composed of many lamellae coming together. 

So how is this a more accurate model of accumulating wisdom? 

When making lamellar armor, the armorer cuts each lamella, shapes it, hardens it, aligns it with the existing armor and adds to the overall structure. Their work isn’t random, isn’t passive. 

And this process more accurately depicts my understanding of the act of gaining wisdom. We aren‘t content to let knowledge build up haphazardly. Instead we select information, investigate it, refine it, and add it to our existing knowledge, strengthening the whole and protecting us more completely from errant information.

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.

A Novelist in Business School: How to Teach

A Novelist in Business School: How to Teach

“A Novelist In Business School” is a series about putting my literary arts brain through formal management training. This article was originally published on my write. as blog and is republished here with permission from the original author. Which is me. I gave myself permission. I’m very strict about things like this.

I’m in the final week of my last accounting class ever. I’m pleased with this. In two weeks I will have mostly forgotten everything I’ve ever known about managerial accounting. I’m less happy about that, but that’s the nature of the game. At least I have my notes.

But here’s what I’m not going to forget:

My professor in this class is an excellent teacher. I’ve been thinking about his teaching style all session, trying to identify the things that make his style so impressive, and here are some things I’ve identified.

Passion

He loves this topic, and that enthusiasm comes through in his teaching.
One of the most common phrases in his lectures is “now this is interesting…” and you know what? He’s right! When he points out something that interests him I get interested. I start thinking about how full absorption moves costs compared to variable costing. He is telling stories using numbers.

On the other side of the coin, he’s fully aware that there are people in his class who don’t love variance analysis on static budgets vs. actuals. So he works to “motivate” us (his word) to want to learn the topics with stories, concrete examples, and, when the situation demands, MegaBlocks to demonstrate how costs move through a system. It works. I don’t love cost accounting, but I understand it far better than anyone would have any right to expect.

Compassion

Our professor knows what it’s like to be a student in his class. He knows this because he listens to feedback. He monitors his emails and answers incredibly quickly. He has moved deadlines, changed assignments, and given extra tutoring sessions because people asked for help. He listened and worked to do what is best for the person asking, and the class in general. He treats us with respect, and it’s effortless to respond in kind.

Reflection

I’ve never had a professor in any of my classes who is so open about how much he’s learning. Our professor asks for feedback and asks to follow up questions about the input. He tells us what he’s trying to do and why he thinks it is the right choice, then asks for our opinions.

Which isn’t to say he’s a pushover. I spent three hours studying for Part I of a four-part take-home final last night. I expect to spend another three hours for part II tonight. The class is hard. But no matter how hard it is I know it’s fair. I know that my professor has thought through what he’s asking of us.

I’m never going to be a college professor. (Probably.) But there will always be opportunities to teach others, and when they come up, I hope I can be as dedicated and competent in my teaching as this professor is in his.

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.

A Novelist in Business School: The Emperor’s Club

A Novelist in Business School: The Emperor’s Club

“A Novelist In Business School” is a series about putting my literary arts brain through formal management training.

There are two parts to this one — first, my thoughts on the use of films as teaching aids. Second, my feelings about a specific movie that was recently used as a teaching aid in one of my classes.

Don’t Use Commercial Motion Pictures as Teaching Aids

There are exceptions to this rule. Film Studies classes, any of the performing arts, any course that has to do with film production or theater or even music are exempt from this rule. But for anyone else you are relying on Hollywood to make your point. Classroom movies were marginally acceptable up through about junior high school, when sometimes the teacher needed an hour or so to grade papers or take a break. But in graduate-level classes this is insane. If you have something to tell us, please tell us. Or ask us to read the novel. Yes, it will take longer, but we’ll get so much more out of it.

Especially in this case.

Read More Read More

A Novelist in Business School: Make it Stick

A Novelist in Business School: Make it Stick

“A Novelist In Business School”, is a series about putting my literary arts brain through formal management training.

I’ve always thought of myself as an excellent learner. I enjoy staying curious. But my innate curiosity doesn’t have a lot of bearing on formal education, because on my own I can be an educational dilettante. If my ability to learn something new doesn’t matter I can say I’ve learned it without actually gaining any knowledge.

Fortunately one of the professors in my first semester of my MBA program was aware he was teaching people who have been away from education for a while. He recommended, along with his coursework, a book called Make It Stick. This book is all about learning effectively and maximizing the time you can put into learning.

The book resonates strongly with me, and has shaped the way I study over the past year and a half. Looking back, it sheds light on experiences I’ve had but didn’t have any formal language to describe.

The thrust of Make It Stick is that we learn best when our learning is put to the test, that frequent practice of new knowledge engrains that knowledge us, and halts the progress of forgetting far better than just repeated exposure. In other words, re-reading a text doesn’t help you learn it all that much, but testing yourself on a text will force you to learn it. While I dislike this as much as anyone (what do you mean I’ve been wasting my time????) I can see how it’s true in an example from my own life.

The Twelve Steps of Laser Printers

When I was young in my career I was given the opportunity to get my A+ certification, a certificate that says you are more or less competent to do desktop support and repair. This certification asks you to identify and diagnose a wide variety of computer parts and issues. One of the more relevant and intricate things it asks about is laser printers. Anyone who has worked with a laser printer knows that they are sometimes finicky beasts, and there are a lot of moving parts in there that can fail on you mysteriously. At the time I was tasked with supporting some ten or twelve such beasties, so the information about what was going on inside them was immediately relevant to my job, and I was tested on it informally every time I was asked to get a laser printer working again. Beyond that I prepared myself a series of quizzes based on the steps of laser printing, forcing myself to recall all the steps at random intervals along with all the other things that I was being asked to learn.

I didn’t know it at the time, but I was doing exactly what Make It Stick recommends. According to the authors, repeated practice (or testing), varying your topic of study, and varying the intervals of study are the key strategies for actually learning something new. Which might be why, nine years after I left my desktop support job, I can still identify all the steps and parts of a laser printer’s paper path.

I’m trying to do the same thing as I go through school. It’s an interesting challenge, because each topic, each class, demands a different type of study. Note taking strategies that worked in my Accounting classes are less useful in marketing classes. But the process, the act of conscientious, meticulous note taking and reviewing still matters, still works.

A Novelist in Business School: Managerial Ethics and Twenty-One Pilots

A Novelist in Business School: Managerial Ethics and Twenty-One Pilots

“A Novelist In Business School”, is a series about putting my literary arts brain through formal management training.

I’m currently taking a class on the Ethics of Management. The glib response to this statement is, “that must be a short class! Har har har!”

But the fact is that for every amoral, thieving, headline-making corrupt executive there are hundreds of thousands of managers and executives at every level who are genuinely trying to make the world around themselves a little better, and are concerned with making the best of the choices facing them.

The author of our textbook is one such. This is a slim volume, and it took me a while to warm up to it; to understand what it is genuinely trying to represent inside its somewhat repetitive passages:

This book represents the crystallized thoughts of someone who has spent decades earnestly trying to understand how you bring your human soul to bear in the act of management.

It’s a deeply intellectualized approach to answering the question “how can I be a good person?”

So What Does This Have To Do With 21 Pilots?

I often wonder how 21 Pilots feels about being the 21st century band that  Gen-Xers in their early 40s point to as the modern music they like so they can say, “See? I’m still cool!” But that is not the point.

The point is that Tyler Joseph’s lyrics are an emotional approach to the same problem. I was listening to “Car Radio” (see? I’m still cool!) this morning while waiting for the train.

from the things that work there are only two
And from the two that we choose to do
Peace will win
And fear will lose
There’s faith and there’s sleep
We need to pick one please because
Faith is to be awake
And to be awake is for us to think
And for us to think is to be alive
And I will try with every rhyme
To come across like I am dying
To let you know you need to try to think

This lyric conveys so much; the internal conflict that Joseph has; that he’s got the kind of mind that explores all possible solutions to the human problem and has tentatively selected two that “work”. And the one hurts (faith, being awake, thinking) is the one that he proposes we do. Mr. Hosmer says almost the same thing:

An action such as lying that is considered wrong in one ethical system will generally be considered wrong in all others, but these ethical systems cannot be reconciled into a single, logically consistent whole.
–Hosmer, La Rue. The Ethics of Management (Page 98). McGraw-Hill Higher Education -A. Kindle Edition.

He’s explored a number of ethical systems and intellectually has decided that there are multiple paths that “work”. And while it hurts, we have to face our ethical choices with eyes open, we have to think our way through them, and accept the choices we make.