contents/articles/introducing-glyph.html
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 |
-----
title: Introducing Glyph
content-type: article
timestamp: 1270834239
tags: glyph|ruby|frameworks|writing
-----
<p>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.</p>
<p>For example, you can use:</p>
<ul>
<li><strong>a Word Processor</strong> like MS Word, for example — anyone can do that, right? Sure, but no, thanks: I strongly believe that Word Processors should not be used for writing technical documents as I firmly don’t believe GUIs are suitable for doing this at a professional level.</li>
<li><strong>a Document Authoring Software</strong> like Adobe Framemaker, Robohelp, etc. Still GUIs, only more complicated to use.</li>
<li><strong><span class="caps">XML</span>, like <span class="caps">DITA</span> or DocBook, or other markups</strong>, like ReStructuredText. Better, but still not easily extensible and flexible enough.</li>
<li><strong>your company’s tools</strong>, if you have them. That’s great if they are usable enough and the result makes your boss happy.</li>
<li><strong>LaTeX</strong>, and that’s probably your best option, if you know what you’re doing.</li>
<li><strong><span class="caps">XHTML</span> and CSS3</strong>, in conjunction with a <span class="caps">PDF</span> renderer like <a href="http://www.princexml.com/">Prince <span class="caps">XML</span></a> — that’s great if you know <span class="caps">HTML</span> and <span class="caps">CSS</span>, and you don’t mind hand-crafting the structure of the document.</li>
</ul>
<h3>Lightweight markups</h3>
<p>I love Textile and Markdown. When people aren’t looking, I even use them at work to generate <span class="caps">HTML</span> code, because it’s just so much faster. Textile in particular can be used as a drop-in replacement for <span class="caps">HTML</span> (and a bit of LaTeX, too), as it can produce most inline <span class="caps">HTML</span> tags effortlessly and some block-level tags, too.</p>
<p>For things like <code><div></code> tags and <code><tables></code> though, Textile is not the best thing in the world, so you normally end up falling back to <span class="caps">HTML</span>.</p>
<p>Another “problem” is that <strong>Textile</strong> or other similar lightweight markups cannot be extended easily, simply because they were not meant to be extended in the first place.</p>
<p>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.</p>
<h3>How Glyph can help</h3>
<p style="float:right;"><img src="/img/pictures/glyph.png" alt="" /></p>
<p>There are a few projects on the Internet that tackle structured document generation. One of them is <a href="http://github.com/fnando/kitabu">Kitabu</a>, which looks promising and is able to produce pretty documents using Textile and Prince for <span class="caps">PDF</span> rendering… but again, it’s not extensible because it relies too much on Textile and Markdown.</p>
<p><a href="/glyph/">Glyph</a> is different. For one, it is much younger than any other, therefore it is most likely full of bugs.</p>
<p>Jokes aside, Glyph follows a much more radical approach, which consists in using a <em>macro language</em> 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.</p>
<p>Here’s an example:</p>
<div class='text'><pre><code>section[header[Something about Glyph]
You can use Glyph macros in conjunction
with _Textile_ or _Markdown_ to
produce HTML files effortlessly.
section[header[What about PDFs?|pdf]
Once you have a single, well-formatted HTML
file, converting it to PDF is
extremely easy with a 3rd-party
renderer like =>[http://www.princexml.com|Prince].
]
]</code></pre></div><p>Which translates to:</p>
<div class='html'><pre><code><div class="section">
<h2 id="h_1">Something about Glyph</h2>
<p>You can use Glyph macros in conjunction with
<em>Textile</em> or <em>Markdown</em> to
produce HTML files effortlessly.</p>
<div class="section">
<h3 id="pdf">What about PDFs?</h3>
<p>Once you have a single, well-formatted HTML
file, converting it to PDF is
extremely easy with a 3rd-party renderer
like <a href="http://www.princexml.com">Prince</a>.</p>
</div>
</div></code></pre></div><p>Glyph macros can be used to:</p>
<ul>
<li>Generate block-level <span class="caps">HTML</span> tags not commonly managed by lightweight markups, like <code>head</code>, <code>body</code>, <code>div</code> and <code>table</code>.</li>
<li>Create and validate internal and external links.</li>
<li>Include and validate images and figures.</li>
<li>Automatically determine header levels based on the document structure.</li>
<li>Automatically generate a Table of Contents based on the document structure.</li>
<li>Store common snippets of text in a single <span class="caps">YAML</span> file and use them anywhere in your document, as many times as you need.</li>
<li>Store configuration settings in a <span class="caps">YAML</span> file and use them anywhere in your document, as many times as you need.</li>
<li>Evaluate Ruby code within your document.</li>
<li>Call macros from other macros (including snippets), carefully avoiding mutual calls.</li>
<li>Include text files in other text files.</li>
<li>Include the contents of configuration settings (author, title) in the document.</li>
<li>Filter input explicitly or implicitly, based on file extensions when including files.</li>
<li>Manage comments and todo items.</li>
</ul>
<p>An example Glyph project? Sure, Glyph’s own guide (<a href="https://github.com/h3rald/glyph/tree/master/book/">source</a> — <a href="http://cloud.github.com/downloads/h3rald/glyph/glyph.pdf"><span class="caps">PDF</span> output</a>).</p>
<h3>Technical Details</h3>
<p>Glyph is built on top of the following Ruby Gems:</p>
<ul>
<li><a href="http://github.com/davetron5000/gli">gli</a> — For the high-level command line interface.</li>
<li><a href="http://rake.rubyforge.org/">rake</a> — For the mid-level interdependent task layer.</li>
<li><a href="http://treetop.rubyforge.org/">treetop</a> — For parsing Glyph Language, whose grammar is <a href="http://github.com/h3rald/glyph/blob/master/lib/glyph/glyph_language.treetop">ridiculously simple</a>, but it seems to work so far.</li>
<li><a href="http://rubyforge.org/projects/extlib/">extlib</a> — Because I can’t leave without it.</li>
</ul>
<h3>Disclaimer</h3>
<p>Glyph is <strong>alpha software</strong> (hence the 0.1.0 version number) — handle with care and be aware that <em>everything</em> could change tomorrow. If you want to keep up-to-date and/or provide feedback, feel free to join <a href="http://groups.google.com/group/glyph-framework">Glyph’s User Group</a>.</p>
<h3>For more information…</h3>
<p>…head over to <a href="/glyph/">Glyph’s homepage</a>.</p>
|