Glyph – A Ruby-Powered Document Authoring Framework
I’ve been writing technical documents for a living for the past four years, and I can tell you: there is no easy way to go about it. I love Textile and Markdown. When people aren’t looking, I even use them at work to generate HTML code, because it’s just so much faster.
For things like <div> tags and <tables> though, Textile is not the best thing in the world, so you end up falling back to HTML. Moreover, if you are producing a book, Textile can’t help you if you want to generate things like a Table of Contents automatically or validate links: those things are simply not part of Textile’s job.
Glyph follows a much more radical approach, which consists in using a macro language on top of Textile or Markdown. The good thing about it is that this macro language is very simple to learn and — most importantly — very easy to extend.
Fabio Cevasco
Glyph(GitHub repo) is an interesting looking "document authoring framework" built in Ruby by Fabio Cevasco. Glyph is both a tool chain and a macro language that's parsed by Treetop into XHTML (which can then be transformed into PDF).
Fabio has clearly put a ton of work into this and has been eating a lot of his own dogfood, as this 72 page PDF manual for Glyph (produced by Glyph itself) demonstrates. In an e-mail to me, Fabio stressed that "he could really use some help" from people interested in document authoring and building in the form of code contributions and testing, and he's ready to help people get started with that.
Glyph looks great, but I'm not entirely convinced that implementing a sort of "XML lite" that uses square brackets is the right way to go when using regular XML would add little overhead and already be more familiar to most developers.
June 19, 2010 at 5:48 pm
Thanks for the post Peter!
One small note: I no longer rely on Treetop for parsing, as for 0.3.0 release I introduced my own, StringScanner-based parser for both performance and practical reasons (more control over the AST and diagnostics etc.).
Regarding the "XML lite" syntax I agree it's not the best in the world, but at least it should be less verbose than raw XML and LaTeX... Also Glyph is meant to be extended easily, so if you create your own macro or rewrites you can dramatically decrease the verbosity of your code.
At any rate, I'm very open to any suggestion as long as it's constructive: I can even change syntax tomorrow if anybody can come up with something less verbose but equally powerful (and not to difficult to parse) :-)
June 20, 2010 at 12:59 pm
It's not really "XML lite" syntax, though; it's light-weight inter-text markup in the spirit of wiki formatting. I don't see any reason to introduce anything XML-ish; it would defeat the purpose.
Please don't change it.
June 20, 2010 at 8:57 pm
Just taking a chunk:
In regular, but simplistic, XML, that could become:
I find the latter a lot more readable as the separation between the semantics and the content is clearer and, really, because I've had to stare at HTML and XML in various forms for 15 years now and it's second nature.
@Dave: Isn't a key difference here that wiki markup doesn't require a lot of nesting except for complex features? Things are more sequential and list-like than tree-like.
June 20, 2010 at 8:58 pm
The other benefit of the XML-style solution, of course, is ease of translation. So you could build a document in, say, Haml and it'd translate right across. You also get the benefits of syntax highlighting, macros (in TextMate) and autocompletion (in many editors).
Of course, anything's better than TeX style formatting ;-)
September 3, 2010 at 4:03 pm
now if it could output to latex...