Day: August 18, 2014

Writing formats for books

I’ve recently started contributing to another book, and one of my tasks was, like, “start the book.” I’ve been dealing with the tyranny of choice – poorly, as it turns out – and I think I’ve finally solved one of the hardest problems:

In what format should the book be written?

I’ve gone around and around on that question. It comes down to two features: simplicity and power.

Simplicity is what you get when you use plain text; you’re just writing. Most writer’s editors emphasize a plain writing surface; they just present you a simple screen, with nothing in front of you but the plain page. No proportional fonts, no bolds, no italics, no spellchecking, nothing: just the page; you get to (or have to) focus on just writing; the editor is out of your way. (This is a good thing.)

Power is the ability to modify the text, adding features and maximizing the impact of each word. It implies all the cool fonts, leading drop-text, references, specific layout control, grammar checking, spelling, all the bells and whistles.

Publishers tend to prefer Microsoft Word; that’s the format I’ve used for another book. Word’s certainly capable, but it’s not open source (a critical aspect for this book), and it’s not available on all of my platforms. Word strikes a good balance between simplicity and power; the ribbon doesn’t help (you have to learn how to use it, and it’s not especially fast with which to interact). As far as open source and wider availability goes, well, LibreOffice can work with Word documents, for the most part, but that “for the most part” isn’t really enough.

LibreOffice Writer might be a workable substitute altogether for Word, of course. The Open Document Format isn’t terrible; I don’t know what really biases me against this choice, but I am biased. Maybe it’s because I also use Word, and the finger-familiarity dissonance isn’t entirely pleasant. LibreOffice is a lot like Word on the balance between simplicity and power; it’s a little simpler without necessarily losing power.

I considered DocBook, and even set about writing some with it (with the help of Publican). I can’t argue against DocBook’s raw power, and won’t… but I will say that writing in DocBook is almost as fun as gnawing off your own neck. Almost. The signal-to-noise ratio for DocBook is incredibly bad – I spent more time muttering under my breath about <para> than I did actually writing the text. DocBook is the epitome of power, and doesn’t even pretend simplicity; SGML, for the … win.

If a format like DocBook prevents you from concentrating on writing, it’s a bad format for you.

HTML is out there, of course, and while HTML is very well known, it is pretty much straight markup.

I looked at Markdown, which is the format I use when writing on my blog (thanks to JetPack in WordPress). Markdown’s fairly old, but closer to what I think I want, except as a format for large, printable documents it’s vastly underpowered. Markdown tries to end up more on the side of “simplicity,” with some power; this is a good thing, because it means a simple text editor can be used to write workable Markdown.

That led me to AsciiDoctor, which is a lot like Markdown in substance, but has a lot more power: footnotes to abuse, a full working table of contents, references, a bibliography, customized rendering templates (including to DocBook)… basically, AsciiDoctor has most of the features one thinks of when considering word processors, without the “word processor” part – it’s just a markup engine with a lot of power.

AsciiDoctor strikes probably the best balance I’ve seen between simplicity and power. If you need it, you have all of the power you need; it’s not a layout engine, so the power you have to endure to get layout isn’t in your way. (This is where Word fails, honestly; you can use Word for layout, which means you get to face features aimed at layout.)

So there you have it, folks: I’m choosing AsciiDoctor to write with.

A quick first-contact tutorial for PencilBlue

Let’s see if we can figure out how to use PencilBlue. It looks interesting enough, and I like much about the approach they’re taking (“Eventually someone who’s not in love with the technology has to manage the site”); let’s see if we can hammer out some basic workflows.

The philosophy PencilBlue seems to prefer is “less is more,” and boy howdy, do they stick to that. My new site, after setting a banner, looks like this when it’s invoked:

PencilGlue's site, with my custom banner
PencilGlue’s site, with my custom banner

All right then! After I log in, it looks way different:

The site after I've logged in
The site after I’ve logged in

… except, no, it doesn’t really look different at all. The main difference is the “log out” button on the top right. If we select the farthest left icon, we end up being able to manage our profile (which allows us to change our password, our name, and our picture), but there’s still not a lot of information being thrown at us.

I actually could not find a way to get to any content administration from the landing page, whether I was logged in or not (and I’m the administrator on the site, so I should have access – and I do, as we’ll see.)

I can open the administration console by going to /admin – which is available only if I’m logged in, which is good. The admin console looks like this:

The administration console
The administration console

There’re a few things we can do here – set email preferences, see the configuration (as shown here), look at users, and check out the plugins (which include a few useful things, but nothing marvelous yet besides a mechanism by which you can import data from WordPress.)

Settings, mostly read-only
Settings, mostly read-only

What really interests us, though, is the content. Choosing the content dropdown gives us options for:

  • Navigation
  • Topics
  • Pages
  • Articles
  • Media
  • Comments
  • Custom objects

Let’s start with topics, because taxonomies should be determined fairly early (or so I think) – if we decide to add to the taxonomic structure, well, I don’t think anyone will blame us.

The topics screen is really pretty easy: It has an option for adding topics, searching for topics, and importing topics; it allows us to delete topics already created. This seems easy enough to use.

Our topics, which I'm not yet sure how to use
Our topics, which I’m not yet sure how to use

I’m not sure offhand what the difference is between a page and an article. In WordPress, a page is contained in a different structure than a post is (even though internally they’re almost identical); I’m guessing that this is similar, that articles represent information that is time-relevant, and pages represent static content for the site.

Let’s assume this is right, and create an “About” page, because everyone wants to know about this site.

Opening the pages menu option (under “content”) gives you the ability to manage your pages, and add new ones; we don’t have one, so let’s add one.

The content addition page has four headings of information for a given page: the page content, any media attached to it, topics, and SEO, which makes a lot of sense.

I’m going to add the page under the url “/page/about”, with a headline of “About this site,” and a subheading of “All the stuff you didn’t know you wanted to know.” I’m setting the publication date to now, because… just because, and I’m basically typing in an equivalent to lorem ipsum as the actual content.

At the bottom there’re two buttons: “Cancel” and “Save draft,” except “Save draft” also has an option (accessible through an up arrow) of “Save.” I’m not worried about drafting – either I’m a fantastic writer, or I’m not too concerned about the draft of this content, since it’s mostly throwaway stuff – so let’s choose “Save.”

Now, the pages … page says that it’s been published; saving is the same as publishing, based on the publication date. This is fairly important. It’s also not obvious to me, but then again, I’m probably used to more traditional publication cycles.

The problem now is: how do I find this page? The front page of the site looks exactly the same as it did. Maybe it’s time to add some navigation to my about page.

Navigation items can fit one of five different types: container, section, page, article, and link. We want to add a page, so let’s try that.

I entered “About” as the name, a short description, ignored the parent navigation item; off to “Content.” Here, it’s asking us to search for the right content. I happen to remember (because I wrote it down, you know) that the content I’m trying to include has “about” in the name, so I typed “about” and then selected “About this site,” since that was what the dropdown tried to show me.

Naturally, once I’d done that, I tried to save it, because saving is important.

Opening the site now shows me a marvelous change: I have an “About” link! It even works!

Success!
Success!

Well, that’s exciting. It’s time to see what else we can do. I’m going to create a page called “Node.js,” just because; it’s going to be like our other page, and mostly consist of content to throw away.

Now, I open my navigation panel, and add “Languages” as a container. After that, I add Node.js as a page, except instead of not having a parent navigation item, I’m choosing “Languages.” Opening the site now gives me “About” – a direct link – and “Languages,” with a dropdown including our new Node.JS page.

Except that doesn’t work! The “.js” makes it look like something it’s not; we need to use _js instead. After we fix that, the page works. We now have rudimentary, rather sparse content to go with our sparse site.

It’s time to blog, then. I’m adding two articles, called “Hello world” and “hello world, again”, both under the languages taxonomy. After saving, both show as being “published.”

And WHOA! Now we have two pieces, published in most-recent order (just like every other blog), on our home page!

It looks like a blog now.
It looks like a blog now.

Now we’re cooking with gas. I’m not sure what it does with long content – I was creating very short articles so I don’t know how well the system reduces front page content; I’m not yet sure how to use the taxonomies. But the site works – theoretically I could create a prettier (i.e., more busy) theme and publish a real, live site with PencilBlue – and it wasn’t even difficult to do.

You may be wondering where this magic site is; after all, http://developerstorm.com resolves, but doesn’t necessarily work. This is not PencilBlue’s fault, at all; it’s because the VPS I use has limited resources, and it just doesn’t have the horsepower to keep everything up at the same time. I had to choose between applications; DeveloperStorm, being a simple demonstration site, just didn’t have enough priority for me to allocate resources. If I find a different container to run it on, I’ll point the IP there.