all repos — h3rald @ 6b243ded05a7593922d198634c681075de1c12e2

The sources of https://h3rald.com

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
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111
 112
 113
 114
 115
 116
 117
 118
-----
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 &#8212; 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> &#8212; 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>&lt;div&gt;</code> tags and <code>&lt;tables&gt;</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 &#8220;problem&#8221; 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="/images/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&#8230; 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 &#8212; most
	importantly &#8212; 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 =&gt;[http://www.princexml.com|Prince].
  ]   
]</code></pre>
</div>
<p>Which translates to:</p>
<div class='html'>
	<pre><code>&lt;div class="section"&gt;
  &lt;h2 id="h_1"&gt;Something about Glyph&lt;/h2&gt;
  &lt;p&gt;You can use Glyph macros in conjunction with 
     &lt;em&gt;Textile&lt;/em&gt; or &lt;em&gt;Markdown&lt;/em&gt; to
     produce HTML files effortlessly.&lt;/p&gt;
  &lt;div class="section"&gt;
   &lt;h3 id="pdf"&gt;What about PDFs?&lt;/h3&gt;
   &lt;p&gt;Once you have a single, well-formatted HTML 
      file, converting it to PDF is
      extremely easy with a 3rd-party renderer 
      like &lt;a href="http://www.princexml.com"&gt;Prince&lt;/a&gt;.&lt;/p&gt;
  &lt;/div&gt;
&lt;/div&gt;</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> &#8212; <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> &#8212; For the high-level command line interface.</li>
	<li><a href="http://rake.rubyforge.org/">rake</a> &#8212; For the mid-level interdependent task layer.</li>
	<li><a href="http://treetop.rubyforge.org/">treetop</a> &#8212; 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> &#8212; 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) &#8212; 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&#8230;</h3>
<p>&#8230;head over to <a href="/glyph/">Glyph's homepage</a>.</p>