The Stylz Book Authoring Environment

The Stylz project is purposed exclusively for writing long documents, such as books, which will be output to combinations of ePub, PDF and other documents. It's a write once, deploy multiple formats tool. It's a format optimized for fast authoring, without a special editor.

Stylz is really xhtml with a few conveniences for the purpose of speed. Xhtml was chosen because it captures styles, not appearances. Only through CSS do those styles get converted to appearances in HTML pages and ePub books. Compare this to other tools, such as Markdown and Asciidoc, which convert styles to appearance early in the process, and make it extremely difficult to make your own arbitrary styles. With Stylz, you can make any style you want, and know it will still be a style in a well-formed xhtml file, which can be XML parsed to do anything.

Xhtml is also good because many people are at least somewhat familiar with it and know how to write it. Also, CSS is a spectacular technology that works with various (x)html versions to give you exactly what you want almost all of the time.

Stylz is designed to be easy to convert, so it has some restrictions ordinary xhtml wouldn't have. They'll be easy to get used to.

Why Not Just Author in XHTML?

Xhtml can do almost anything and it's fairly easy to author. So what's better about Stylz than authoring directly into Xhtml? The answer is speed. The things you do most are quicker and easier. For instance, you'll never need to put <p> and </p> around ordinary paragraphs. If a block of text is bordered top and bottom by blank or empty lines, it's considered an ordinary paragraph, so the Stylz to xhtml conversion program inserts the <p> and </p>.

Of course, you might have paragraphs with special styles. Perhaps a style called "story", which will ultimately have bigger margins and italic fonts. No problem: You just start the paragraph with the following:

Perhaps that paragraph also has an ID called bills_story. Then it would begin with the following:

As shown in the preceding, if a paragraph has both a class and an ID, the class must come first.

If a paragraph has just an ID called stats324, it would look like the following:

Stylz has a similar facility for headings h1 through h6 (actually to h9). the following three headings demonstrate how it's done:

Character Style Shortcuts

The preceding section discussed shortcuts for ordinary paragraphs, styled and/or ID'ed paragraphs, and headings. But typically, in LyX and Xhtml for instance, character styles take more time. Because Stylz is basically xhtml, you can write character style designations in xhtml format. But Stylz gives you six shortcut character styles you can match to any character styles you want. You simply surround the text the character style should be applied to by one of the following special characters:

Stylz' default configuration file assigns the following character styles to the preceding:

Those not listed in the preceding have no existing definition, and once again, you can redefine the ones already defined.

There's one additional character style shortcut: Surrounding the affected text with @#$. This special shortcut is meant to be used <pre> blocks, to indicate text typed by the user. This is a necessity in technical writing. In the unlikely event that these three characters appear naturally in text, and this would happen probably only in a document describing Stylz, substitute "@" for "@".

Stylz Restrictions

Because Stylz substitutes short strings for the most often used xhtml tags, Stylz cannot be parsed as xhtml. The first few parsing steps parse it line by line. So here are some of the restrictions:

<div> and <pre> must stand alone

<div> and <pre> must be preceded by a blank line, must have nothing else on their line, and must be directly followed by actual content, not a blank line. </div> and </pre> must be preceded by a line with content, must have nothing else on their line, and must be directly followed by a blank or empty line.

Paragraphs must be surrounded by empty lines or special tags

A line whose preceding line was blank or empty begins a paragraph. A line preceded by a line consisting of <<div> or <pre> is the first line of a paragraph. A line followed by a blank or empty line is the last line of the paragraph. A line followed by a line consisting of <</div> or </pre> is the last line of a paragraph.

Evaluation of Character Style Shortcuts

Character style shortcuts can't span lines. If one does, replace it with the true xhtml character style tags. Only one character style shortcut can appear on a single line. Insert newlines where appropriate to comply with this rule.

Project Priorities

Write once, read everywhere

This is the whole reason I wrote Stylz. Believe me, if the LyX project showed any intent to make a semantically faithful HTML export en route to ePub, or even if they made the native LyX format well formed XML, I would have used LyX. But, with the LyX project's focus on satisfying Mac users and authors of doctoral theses, I doubt this will happen any time soon.

I've not found any free software tool that exports both quality PDF and quality ePub, so I had to write it myself.

Styles based authoring

Some folks enjoy applying appearances directly to text, without a thought for the purpose of the appearance. Such direct application of appearance is called fingerpainting

NOTE:

The word "fingerpainting" in the preceding normal paragraph was styled using <span class="term">, not <i>. This means that all my terminology terms look the same, and if I want to change the look for my terminology terms, I can just change the span.term CSS definition, without also changing my emphasized text and everything else that happens to be italic. This is the essence of styles-based authoring.

Fingerpainters often end up with half their quotations being 150% text size and the other half of the quotations being bold and italic. And if they ever need to change the appearance of all their quotations, they're in big trouble, because although they could search for italic appearance, they'd need to decide, for each instance found, whether it is for a quotation, and manually change every single one. Styles based authoring avoids this.

As a practical matter, it's almost impossible to write and edit a 50K word fingerpainted document. You'll be spending all your time navigating, fixing formatting errors, and various other unproductive timewasting.

Fast authoring

Every time your concentration switches from the content you're writing to the mechanics of the writing process, you're in risk of forgetting what you were thinking of writing, cutting your authoring speed in half or worse. Fast, braindead simple authoring is essential, so your valuable brainpower can be used to express your plot, characters, concepts or technology.

The preceding speed enhancers are given you by Stylz. In addition, somebody could further speed up authoring, within the editor itself, with hotkeys or zen-coding. Stylz is designed to be editor agnostic, you can use it in Emacs, Vim, Bluefish, or even TECO. That being said, most editors offer tools to speed up the editing of any kind of format, especially something as simple as Stylz.

We all know that WYSIWYG authoring tools are faster because you don't get as lost. Maybe someday somebody will make a WYSIWYG editor for Stylz. But until then, you can rest assured that what you lose by the absence of WYSIWYG is pretty much made up for with Stylz' simplicity and keyboard centricity.

Minimal dependencies

Dependencies are a hassle for the user. One year, LyX decided to depend on a newer than one year old Qt4 that was difficult to install on my version of Mandriva, so to take advantage of a needed new feature I had to jump through a day's worth of hoops.

I'm forced to use a three year old version of Sigil because no Linux distro I've found has the Qt5 that modern Sigil insists on. Sigil also has about twenty other dependencies, such that its installability on a given distro is a crap shoot. I love VimOutliner, but its installation increasingly depends on stuff like pathogen and vimballs or whatever they're called. All this dependency stuff makes it less likely to successfully deploy an application. Plus, as several applications and tools start depending on each other, especially if they have complex interfaces that can't easily be simulated or stubbed, the whole construction starts becoming rickety, and hard to debug problems follow.

I've tried to make Stylz dependent on little else but Python (it might need an XML parser, I'm not sure). Instead of fancy YAML config files, it uses hierarchies of directories with filenames and file contents serving as key->value pairs. A few of the text files are ordered lists with each element occupying its own line. You can read and write these in plain vanilla Python, Perl, Ruby, Lua, C or shellscripts. I have no doubt this data storage mechanism will offend many who call themselves developers. They're sure to call this a "kludge", "1980", "a toy", "a hobby", or "written by a neckbeard". Ho hum.

Those characterizations are nice, but the fact is, this data storage mechanism means you can easily code a new exporter or other Stylz component in C/C++, a Shellscript, or Python/Perl/Ruby/Lua/php/Java without needing to install or code a YAML parser, or having to code a parser for some one-off config file with square braces and equal signs, or a tab indented outline. Users won't need to install such parsers either, and that makes deployment easier.

If you need just a couple data elements, reach right onto the disk and grab them. If you need them all in memory, it's easy to make an object containing a Python dictionary or Lua table or Perl hash to contain the whole thing, with a simple method to load them all from the disk. I'll be doing that the first time I write an exporter, which will be within a couple weeks.

Format simplicity

Docbook? Why anyone would expect somebody to hand-edit XML is beyond me. You know eventually they'll make an hour-consuming mistake. The same is pretty much true for HTML, although I'm currently writing this, using Bluefish with zen-coding, on HTML, frequently checked with my home-grown XML checker. But the fact is, anything with widespread begin and end tags invites mistakes, and at a glance is confusing.

The simplest format is plain text, where paragraphs are delineated by one or more blank line, and linebreaks within the paragraph are ignored by the word-wrapping export mechanism. So that's exactly how normal paragraphs are built in Stylz.

When specially formatted paragraphs are necessary, Stylz requires only a start tag, because Stylz paragraphs are ended by one or more blank lines. And the start tag can be simple, because it's restricted to the beginning of the paragraph. Because whitespace before and after the start tag is insignificant and removed, such start tags can be made easily identified at a glance. All told, paragraph styling requires few extra keystrokes, and doesn't visually confuse the document.

For simplicity of both authoring and conversion, paragraph style start tags apply to only one paragraph. If you want five in a row styled with, let's say, the "story" paragraph style, mark each as such. The inconvenience of doing it five times is greatly overshadowed by the reduction in looking for end tags every time. And if you simply must format a bunch of paragraphs the same with one begin/end tag set, you can use a container.

For obvious reasons, character styles require a begin and end tag. So Stylz makes character styles something easy to type, visually unobtrusive, and unlikely to clash with likely actual content. They look like the beginning of the following clause, ::thetruth{the text in here is character style thetruth}. Easy to type, non-confusing on the eyes. Curly braces inside the character style text will need to be escaped, with a backslash.

Paragraph and character styles will be by far the most used modifiers, so they are the most important to simplicity. Containers, which can serve a wide variety of uses, are more complicated and have more usage rules, but they don't (or shouldn't) happen enough to significantly slow writing or visually obfuscate the document.

Expandability

When you get right down to it, Stylz contains only content text, style names, and a minimum of constructs common to every document. What's done with those text and styles are up to the creator of the export program. Via styles, substitution tokens and containers, it will probably be somewhat easy to add new capabilities, assuming export programs are updated to take advantage of those capabilities.

What this means is you can write your own capabilities and modify existing export programs, or if your new capability is useful enough and fulfills the priorites of Stylz, you can submit it to me and I'll put it in the Stylz distribution.

DIY friendly, granular toolkit

There's no human way to create a singular program to fulfill every need. LyX tried, and now their code is too complicated to accommodate correct HTML export.

Stylz' approach is different. Stylz provides the most useful set of capabilities for a typical self-published book author, in the form of programs that act as filters, each changing what is passed to it and passing the changes out to the next program, eventually terminating in the target reading format (HTML, ePub or LaTeX). Each intersection between these programs, each pipe in UNIX terminology, is a place where you can insert your own program or shellscript to add a capability or a preference.

Deployability

I once wrote a program, called UMENU, that is a deployment nightmare. It's incredibly useful, but less than 100 people use it, I think because it's almost undeployable if you're not its author. I don't want that happening to Stylz.

The Stylz exporters and manipulators I write will be written either as Python programs or shellscripts. If Python, they'll use a minimum of dependencies, so you won't need to use your package manager to install much. There will be two tarballs: One to install the programs, and one to start a brand new book project. There will be adequate documentation so that a non-helpless computer user can use the system.

If I'm about my business, all the executables and their configuration will be in one tree, with a single instantiation program on the path. This program will be deployable.