Reactions on "The Stylz Book Authoring Environment"

February 1, 2015

I subscribe to my University’s “Platform Independent Linux List”. Yesterday, Steve Litt sent out an email announcing his new markup language specification. I spent some time reading through it, and it looks interesting, especially in how data is stored hierarchically.

Take a look at the email thread:

For convenience reprinted his announcement (with some formatting tweaks) and my response here.

Reactions

On Sat, 31 Jan 2015 20:49:04 -0500
Steve Litt wrote:

Hi all,

I just finished and uploaded the first draft of the Stylz book-writing specifications:

http://www.troubleshooters.com/projects/stylz/

Obviously I still need to write the fix executable and the Stylz->TeX->PDF and Stylz->HTML->ePub exporters, but I’m optimistic that I got the Stylz native format right, and for the author, that’s the important thing.

One Stylz file will be able to export to both PDF (via either TeX or LaTeX, not sure which) or ePub. And as people write more exporters, more target outputs can be made by the single manuscript, with no or minimal human intervention.

SteveT

Steve Litt — http://www.troubleshooters.com/
Troubleshooting Training — Human Performance

Steve,

First off: Wow. This looks awesome! These days I use pandoc’s markdown for almost everything, but I’ve used reStructuredText quite a bit. One of the things I liked about reST was the flexibility and extensibility of the syntax, which you seem to have captured.

Unfortunately, I’ve found that most of my writing isn’t for a book, but rather notes for classes, one-off write-ups, assignments, software documentation, and just recently I started a blog. As a result, I’ve begun to highly value the conciseness I can achieve with small amounts of markdown. Additionally, I feel that between inline HTML/LaTeX and pandoc’s huge amount of markdown extensions, I can achieve most of what I care about. At first glance, your syntax seems rather verbose with !!begincomment and whatnot.

But perhaps this is besides the point, as it seems you have a clear, differentiated use-case from markdown1. Books are hard.

So, not to diminish the incredible amount of effort you must have put into this, I’d like to provide my immediate thoughts on the format.

YAML

I love yaml, because I find it easy to write. Sure, it sucks to parse, and there’s a bit of a learning curve, but damn is it easy for me to write. Besides that, it makes deeply nested hierarchies less painful. Perhaps that’s a bad thing though.

One thing that’s frustrated me about Ansible2 is the somewhat forced directory structure. Because of this, I’m sometimes forced to split up small roles into multiple folders. Even though I use vim and have plugins like ctrlp to help me, I find switching between files bothersome.

Dependencies

I used to agree that dependencies were the spawn of Satan, but I’ve since changed my opinion. IMHO, dependencies are fine, if you have a good way to manage dependencies. When I work on a Python, JavaScript, Java, or Ruby project, often the first thing I do is set up virtualenv+pip, npm/bower, gradle, or bundler+gem. Once that one-time work is out of the way, it tends to be easy to add dependencies, which allows me to benefit from other libraries, and focus on my application-specific logic.

I’ll concede here though that three problems remain:

  1. Not all languages have good dependency management
  2. Mixing languages requires mixing package managers, which works poorly at best. Perhaps pants will solve this one day.
  3. It’s still hard to distribute self-contained binaries to people.

I’ve tried to work around that last point in my ansible-honeybadger project, and there’s some great software like py2exe, cx_freeze, PyInstaller, etc3, but I still don’t know of a perfect catch-all solution.

Overall, however, I feel that dealing with the cost of dependencies up-front allows for much easier development later.

Conclusions

— Benjamin Woodruff


  1. Yes, I read the FAQ.

  2. I seem to have a love-hate relationship with Ansible these days.

  3. I’m incredibly jealous of how easy golang devs have it.

The views expressed on this site are my own and do not reflect those of my employer.