Added missing contents; updated projects and stylesheet improvements.
h3rald h3rald@h3rald.com
Sun, 15 Oct 2017 17:07:50 +0200
100 files changed,
9212 insertions(+),
648 deletions(-)
jump to
M
assets/js/search.js
→
assets/js/search.js
@@ -24,7 +24,6 @@ search();
} function result(data) { - console.log(data.id); var id = data.id.replace(/\/index\.html$/i, ''); var card = window.document.createElement('div'); card.classList.add('card');@@ -40,10 +39,6 @@ var link = window.document.createElement('a');
link.setAttribute('href', id); link.innerHTML = '→ ' + id; - var subtitle = window.document.createElement('div'); - title.classList.add('card-subtitle'); - title.classList.add('text-gray'); - var body = window.document.createElement('div'); body.classList.add('card-body'); body.innerHTML = data.highlight;@@ -51,7 +46,6 @@
// Structure title.appendChild(link); header.appendChild(title); - header.appendChild(subtitle); card.appendChild(header); card.appendChild(body);@@ -76,7 +70,6 @@ return;
} searchInput.value = decodeURIComponent(q); var req = endpoint + '?search=' + q + '&contents=false'; - console.log('executing...'); axios.get(req).then(function(resp){ results(resp.data.results); }).catch(function(resp){@@ -98,7 +91,6 @@ var info = window.document.createElement('p');
info.textContent = items.length + ' results found.'; resultsDiv.innerHTML = ''; resultsDiv.appendChild(info); - resultsDiv items.forEach(function(item) { resultsDiv.appendChild(result(item)); });
A
assets/styles/atom-one-light.css
@@ -0,0 +1,96 @@
+/* + +Atom One Light by Daniel Gamage +Original One Light Syntax theme from https://github.com/atom/one-light-syntax + +base: #fafafa +mono-1: #383a42 +mono-2: #686b77 +mono-3: #a0a1a7 +hue-1: #0184bb +hue-2: #4078f2 +hue-3: #a626a4 +hue-4: #50a14f +hue-5: #e45649 +hue-5-2: #c91243 +hue-6: #986801 +hue-6-2: #c18401 + +*/ + +.hljs { + display: block; + overflow-x: auto; + padding: 0.5em; + color: #383a42; + background: #fafafa; +} + +.hljs-comment, +.hljs-quote { + color: #a0a1a7; + font-style: italic; +} + +.hljs-doctag, +.hljs-keyword, +.hljs-formula { + color: #a626a4; +} + +.hljs-section, +.hljs-name, +.hljs-selector-tag, +.hljs-deletion, +.hljs-subst { + color: #e45649; +} + +.hljs-literal { + color: #0184bb; +} + +.hljs-string, +.hljs-regexp, +.hljs-addition, +.hljs-attribute, +.hljs-meta-string { + color: #50a14f; +} + +.hljs-built_in, +.hljs-class .hljs-title { + color: #c18401; +} + +.hljs-attr, +.hljs-variable, +.hljs-template-variable, +.hljs-type, +.hljs-selector-class, +.hljs-selector-attr, +.hljs-selector-pseudo, +.hljs-number { + color: #986801; +} + +.hljs-symbol, +.hljs-bullet, +.hljs-link, +.hljs-meta, +.hljs-selector-id, +.hljs-title { + color: #4078f2; +} + +.hljs-emphasis { + font-style: italic; +} + +.hljs-strong { + font-weight: bold; +} + +.hljs-link { + text-decoration: underline; +}
M
assets/styles/fonts.css
→
assets/styles/fonts.css
@@ -29,32 +29,32 @@
@font-face { font-family: 'Hack'; - src: url('../fonts/hack-regular-latin-webfont.eot?v=2.020'); - src: url('../fonts/hack-regular-latin-webfont.eot?#iefix&v=2.020') format('embedded-opentype'), url('../fonts/hack-regular-latin-webfont.woff2?v=2.020') format('woff2'), url('../fonts/hack-regular-latin-webfont.woff?v=2.020') format('woff'), url('../fonts/hack-regular-latin-webfont.ttf?v=2.020') format('truetype'); + src: url('../fonts/hack-regular-webfont.eot?v=2.020'); + src: url('../fonts/hack-regular-webfont.eot?#iefix&v=2.020') format('embedded-opentype'), url('../fonts/hack-regular-webfont.woff2?v=2.020') format('woff2'), url('../fonts/hack-regular-webfont.woff?v=2.020') format('woff'), url('../fonts/hack-regular-webfont.ttf?v=2.020') format('truetype'); font-weight: 400; font-style: normal; } @font-face { font-family: 'Hack'; - src: url('../fonts/hack-bold-latin-webfont.eot?v=2.020'); - src: url('../fonts/hack-bold-latin-webfont.eot?#iefix&v=2.020') format('embedded-opentype'), url('../fonts/hack-bold-latin-webfont.woff2?v=2.020') format('woff2'), url('../fonts/hack-bold-latin-webfont.woff?v=2.020') format('woff'), url('../fonts/hack-bold-latin-webfont.ttf?v=2.020') format('truetype'); + src: url('../fonts/hack-bold-webfont.eot?v=2.020'); + src: url('../fonts/hack-bold-webfont.eot?#iefix&v=2.020') format('embedded-opentype'), url('../fonts/hack-bold-webfont.woff2?v=2.020') format('woff2'), url('../fonts/hack-bold-webfont.woff?v=2.020') format('woff'), url('../fonts/hack-bold-webfont.ttf?v=2.020') format('truetype'); font-weight: 700; font-style: normal; } @font-face { font-family: 'Hack'; - src: url('../fonts/hack-italic-latin-webfont.eot?v=2.020'); - src: url('../fonts/hack-italic-latin-webfont.eot?#iefix&v=2.020') format('embedded-opentype'), url('../fonts/hack-italic-latin-webfont.woff2?v=2.020') format('woff2'), url('../fonts/hack-italic-latin-webfont.woff?v=2.020') format('woff'), url('../fonts/hack-italic-latin-webfont.ttf?v=2.020') format('truetype'); + src: url('../fonts/hack-italic-webfont.eot?v=2.020'); + src: url('../fonts/hack-italic-webfont.eot?#iefix&v=2.020') format('embedded-opentype'), url('../fonts/hack-italic-webfont.woff2?v=2.020') format('woff2'), url('../fonts/hack-italic-webfont.woff?v=2.020') format('woff'), url('../fonts/hack-italic-webfont.ttf?v=2.020') format('truetype'); font-weight: 400; font-style: italic; } @font-face { font-family: 'Hack'; - src: url('../fonts/hack-bolditalic-latin-webfont.eot?v=2.020'); - src: url('../fonts/hack-bolditalic-latin-webfont.eot?#iefix&v=2.020') format('embedded-opentype'), url('../fonts/hack-bolditalic-latin-webfont.woff2?v=2.020') format('woff2'), url('../fonts/hack-bolditalic-latin-webfont.woff?v=2.020') format('woff'), url('../fonts/hack-bolditalic-latin-webfont.ttf?v=2.020') format('truetype'); + src: url('../fonts/hack-bolditalic-webfont.eot?v=2.020'); + src: url('../fonts/hack-bolditalic-webfont.eot?#iefix&v=2.020') format('embedded-opentype'), url('../fonts/hack-bolditalic-webfont.woff2?v=2.020') format('woff2'), url('../fonts/hack-bolditalic-webfont.woff?v=2.020') format('woff'), url('../fonts/hack-bolditalic-webfont.ttf?v=2.020') format('truetype'); font-weight: 700; font-style: italic; }
D
assets/styles/github.css
@@ -1,99 +0,0 @@
-/* - -github.com style (c) Vasily Polovnyov <vast@whiteants.net> - -*/ - -.hljs { - display: block; - overflow-x: auto; - padding: 0.5em; - color: #333; - background: #f8f8f8; -} - -.hljs-comment, -.hljs-quote { - color: #998; - font-style: italic; -} - -.hljs-keyword, -.hljs-selector-tag, -.hljs-subst { - color: #333; - font-weight: bold; -} - -.hljs-number, -.hljs-literal, -.hljs-variable, -.hljs-template-variable, -.hljs-tag .hljs-attr { - color: #008080; -} - -.hljs-string, -.hljs-doctag { - color: #d14; -} - -.hljs-title, -.hljs-section, -.hljs-selector-id { - color: #900; - font-weight: bold; -} - -.hljs-subst { - font-weight: normal; -} - -.hljs-type, -.hljs-class .hljs-title { - color: #458; - font-weight: bold; -} - -.hljs-tag, -.hljs-name, -.hljs-attribute { - color: #000080; - font-weight: normal; -} - -.hljs-regexp, -.hljs-link { - color: #009926; -} - -.hljs-symbol, -.hljs-bullet { - color: #990073; -} - -.hljs-built_in, -.hljs-builtin-name { - color: #0086b3; -} - -.hljs-meta { - color: #999; - font-weight: bold; -} - -.hljs-deletion { - background: #fdd; -} - -.hljs-addition { - background: #dfd; -} - -.hljs-emphasis { - font-style: italic; -} - -.hljs-strong { - font-weight: bold; -}
M
assets/styles/style.css
→
assets/styles/style.css
@@ -15,7 +15,15 @@ font-weight: normal;
font-size: 1rem; } -b, strong, h1, h2, h3, h4, h5, h6, .panel-title { +code, pre { + color: #333; + background-color: #f8f8f8; + font-family: 'Hack', monospace; + font-size: 0.8rem; + line-height: 1.2rem; +} + +b, strong, h1, h2, h3, h4, h5, h6, .h1, .h2, .h3, .h4, .h5, .h6, .panel-title { font-weight: bold; }@@ -72,7 +80,8 @@
article { } -article header h3 { +article.article header h3, +article.project header h3 { font-weight: normal; font-style: italic; font-size: 1.2em;@@ -161,6 +170,36 @@ float: right;
margin-bottom: 1em; } -.archives .card { +.archives .card, .projects .card { margin-bottom: 1em; } + +.label { + font-variant: small-caps; + vertical-align: middle; +} + +.card-subtitle { + font-style: italic; +} + +a[href^=http]::after { + font-family: "entypo"; + content: "\e9ab"; + font-size: 0.8rem; + color: #aaa; + font-weight: normal; +} + +.project-card { + margin-bottom: 0.5rem; +} + +.project-card.card .card-footer { + text-align: center; + padding: 0.4rem; +} + +.project-card .card-footer a { + font-variant: small-caps; +}
M
contents/500.html
→
contents/500.html
@@ -2,4 +2,4 @@ -----
title: "Internal Server Error" content-type: page ----- -<p>Something went wrong. Try to go back <a href="/">home</a> and if things improve. If not, send a <a href="/">tweet</a> to <em>@h3rald</em> and I’ll try to sort it out.</p> +<p>Something went wrong. Try to go back <a href="/">home</a> and if things improve. If not, send a tweet <em>@h3rald</em> and I’ll try to sort it out.</p>
M
contents/concatenative.html
→
contents/concatenative.html
@@ -1,17 +1,13 @@
----- title: "Concatenative" content-type: project -github: concatenative -status: On Hold -version: 0.2.0 +github: "concatenative" +docs: "http://concatenative.rubyforge.org" +home: "/concatenative/" +summary: "A Ruby DSL for concatenative programming. Although quite slow if compared to other concatenative languages like Factor, it implements all the most common concatenative combinator and makes it possible to use Ruby objects in a concatenative way." +inactive: true +version: "0.2.0" ----- -<nav class="project-links"> -<p><a href="http://concatenative.rubyforge.org"><span class="caps">DOCUMENTATION</span></a> | <a href="http://rubyforge.org/projects/concatenative"><span class="caps">DOWNLOAD</span></a> | <a href="http://github.com/h3rald/concatenative/tree/master"><span class="caps">SOURCE</span></a> | <a href="http://github.com/h3rald/concatenative/issues"><span class="caps">TRACKING</span></a></p> -</nav> -<ul class="project-data"> - <li>Project Status: <strong>On Hold</strong></li> - <li>Version: <strong>0.2.0</strong></li> -</ul> <p>Concatenative is a Ruby <acronym title="Domain-specific Language"><span class="caps">DSL</span></acronym> for concatenative programming. It is heavily inspired by <a href="http://www.latrobe.edu.au/philosophy/phimvt/joy.html">Joy</a>, a minimalist programming language by Manfred von Thun. Like Joy, Concatenative features:</p> <ul> <li>function composition, instead of function application</li>@@ -44,10 +40,10 @@ <li>All other method have an arity of 0</li>
<li>If a method has a different arity, you must specify it explicitly using the pipe (|) operator.</li> </ul> <p>Example:</p> -<div class='ruby'><pre><code>concatenate( - "Goodbye, World!", /Goodbye/, "Hello", :sub|2 - )</code></pre></div><p>The program above is equivalent to <code>"Goodbye, World!".sub(/Goodbye/, "Hello")</code>.</p> +<div class='ruby'><pre><code>concatenate("Goodbye, World!", /Goodbye/, "Hello", :sub|2)</code></pre> +</div> +<p>The program above is equivalent to <code>"Goodbye, World!".sub(/Goodbye/, "Hello")</code>.</p> <h3>Latest Updates</h3> -<ul><li><a href="/articles/concatenative-020/">Concatenative 0.2.0 released</a> — <time class="timeago" datetime="2009-04-19T07:42:00Z">Sunday, 19 April 2009</time></li> -<li><a href="/articles/concatenative-programming-in-ruby/">Concatenative programming in Ruby</a> — <time class="timeago" datetime="2009-03-28T06:24:00Z">Saturday, 28 March 2009</time></li> +<ul><li><a href="/articles/concatenative-020/">Concatenative 0.2.0 released</a></li> + <li><a href="/articles/concatenative-programming-in-ruby/">Concatenative programming in Ruby</a> </li> </ul>
D
contents/contact.html
@@ -1,15 +0,0 @@
------ -title: "Contact" -content-type: page ------ -<div class="contact-list"> -<ul> - <li><i class="fa fa-envelope"></i> <a href='mailto:h3rald@h3rald.com'>h3rald@h3rald.com</a></li> - <li><i class="fa fa-twitter"></i> <a href="http://twitter.com/h3rald">@h3rald</a></li> - <li><i class="fa fa-linkedin"></i> <a href="http://it.linkedin.com/in/fabiocevasco">LinkedIn</a></li> - <li><i class="fa fa-bookmark"></i> <a href="http://pinboard.in/u:h3rald/">Pinboard</a></li> - <li><i class="fa fa-instagram"></i> <a href="http://instagram.com/h3rald/">Instagram</a></li> - <li><i class="fa fa-github"></i> <a href="https://github.com/h3rald">Github</a></li> - <li><i class="fa fa-foursquare"></i> <a href="http://foursquare.com/h3rald">Foursquare</a></li> -</ul> -</div>
M
contents/glyph.html
→
contents/glyph.html
@@ -3,174 +3,141 @@ title: "Glyph"
content-type: project subtitle: "A Rapid Document Authoring Framework" github: glyph -status: Active +home: /glyph/ +summary: "A Rapid Document Authoring Framework written in Ruby that can be used to create and manage books and articles." +inactive: true +docs: /glyph/book/ version: 0.5.3.1 ----- -<nav class="project-links"> - <a href="http://www.github.com/h3rald/glyph/">REPOSITORY</a> | <a href="http://www.rubygems.org/gems/glyph">DOWNLOAD</a> | <a href="/glyph/book/">DOCUMENTATION</a> | <a href="http://groups.google.com/group/glyph-framework">USER GROUP</a> -</nav> -<ul class="project-data"> - <li>Project Status: <strong>Active</strong></li> - <li>Version: <strong>0.5.3.1</strong></li> -</ul> - - -<section class="section"> <p>Glyph is a <em>Rapid Document Authoring Framework</em>.</p> <p>With Glyph, creating and maintaining any kind of document becomes as easy as… <em>programming</em>. Glyph enables you to minimize text duplication, focus on content rather than presentation, manage references seamlessly and automate tedious tasks through a simple but effective macro language, specifically geared towards customization and extensibility.</p> - <section class="section"> -<header><h1 id="h_1" class="toc">Main Features</h1></header> -<section class="section"> -<header><h1 id="h_2" class="toc">Command Line Interface</h1></header> +<h3>Main Features</h3> +<h4>Command-line Interface</h4> <p>Glyph is 100% command line. Its interface resambles <a href="http://git-scm.com/">Git’s</a> for its simplicity and power (thanks to the <a href="http://github.com/davetron5000/gli">gli</a> gem). Here are some example commands:</p> <ul> - <li><code>glyph init</code> — to initialize a new Glyph project in the current (empty) directory.</li> - <li><code>glyph add introduction.textile</code> — to create a new file called <em>introduction.textile</em>.</li> - <li><code>glyph compile</code> — to compile the current document into a single <span class="caps">HTML</span> file.</li> - <li><code>glyph compile --auto</code> — to keep recompiling the current document every time a file is changed.</li> - <li><code>glyph compile -f pdf</code> — to compile the current document into <span class="caps">HTML</span> and then transform it into <span class="caps">PDF</span>.</li> - <li><code>glyph compile readme.glyph</code> — to compile a <em>readme.glyph</em> located in the current directory into a single <span class="caps">HTML</span> file.</li> - <li><code>glyph outline -l 2</code> — Display the document outline, up to second-level headers.</li> - <li><code>glyph stats</code> — Display project statistics.</li> + <li><code>glyph init</code> — to initialize a new Glyph project in the current (empty) directory.</li> + <li><code>glyph add introduction.textile</code> — to create a new file called <em>introduction.textile</em>.</li> + <li><code>glyph compile</code> — to compile the current document into a single <span class="caps">HTML</span> file.</li> + <li><code>glyph compile --auto</code> — to keep recompiling the current document every time a file is changed.</li> + <li><code>glyph compile -f pdf</code> — to compile the current document into <span class="caps">HTML</span> and then transform it into <span class="caps">PDF</span>.</li> + <li><code>glyph compile readme.glyph</code> — to compile a <em>readme.glyph</em> located in the current directory into a single <span class="caps">HTML</span> file.</li> + <li><code>glyph outline -l 2</code> — Display the document outline, up to second-level headers.</li> + <li><code>glyph stats</code> — Display project statistics.</li> </ul> -</section> - <section class="section"> -<header><h1 id="h_3" class="toc">Minimalist Syntax</h1></header> +<h4>Minimalist Syntax</h4> <p>Glyph syntax rules can be explained using Glyph itself:</p> - <div class="CodeRay"> - <div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span>section[ -<span class="line-numbers"> <a href="#n2" name="n2">2</a></span> @title[Something about Glyph] -<span class="line-numbers"> <a href="#n3" name="n3">3</a></span> txt[ -<span class="line-numbers"> <a href="#n4" name="n4">4</a></span>You can use Glyph macros in conjunction -<span class="line-numbers"> <a href="#n5" name="n5">5</a></span>with _Textile_ or _Markdown_ to -<span class="line-numbers"> <a href="#n6" name="n6">6</a></span>produce HTML files effortlessly. -<span class="line-numbers"> <a href="#n7" name="n7">7</a></span> ] -<span class="line-numbers"> <a href="#n8" name="n8">8</a></span> p[Alternatively, you can just use em[Glyph itself] to generate HTML tags.] -<span class="line-numbers"> <a href="#n9" name="n9">9</a></span> section[ -<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span> @title[What about PDFs?] -<span class="line-numbers"><a href="#n11" name="n11">11</a></span> @id[pdf] -<span class="line-numbers"><a href="#n12" name="n12">12</a></span> p[ -<span class="line-numbers"><a href="#n13" name="n13">13</a></span>Once you have a single, well-formatted HTML -<span class="line-numbers"><a href="#n14" name="n14">14</a></span>file, converting it to PDF is -<span class="line-numbers"><a href="#n15" name="n15">15</a></span>extremely easy with a free 3rd-party -<span class="line-numbers"><a href="#n16" name="n16">16</a></span>renderer like =>[http://www.princexml.com|Prince] -<span class="line-numbers"><a href="#n17" name="n17">17</a></span>or =>[http://code.google.com/p/wkhtmltopdf/|wkhtmltopdf]. -<span class="line-numbers"><a href="#n18" name="n18">18</a></span> ] -<span class="line-numbers"><a href="#n19" name="n19">19</a></span> ] -<span class="line-numbers"><strong><a href="#n20" name="n20">20</a></strong></span>]</pre></div> -</div> +<pre><code> +section[ + @title[Something about Glyph] + txt[ +You can use Glyph macros in conjunction +with _Textile_ or _Markdown_ to +produce HTML files effortlessly. + ] + p[Alternatively, you can just use em[Glyph itself] to generate HTML tags.] + section[ + @title[What about PDFs?] + @id[pdf] + p[ +Once you have a single, well-formatted HTML +file, converting it to PDF is +extremely easy with a free 3rd-party +renderer like =>[http://www.princexml.com|Prince] +or =>[http://code.google.com/p/wkhtmltopdf/|wkhtmltopdf]. + ] + ] +] +</code></pre> <p>The Glyph code above corresponds to the following HTML code:</p> - <div class="CodeRay"> - <div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span><span class="tag"><div</span> <span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">section</span><span class="delimiter">"</span></span><span class="tag">></span> -<span class="line-numbers"> <a href="#n2" name="n2">2</a></span> <span class="tag"><h2</span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">h_10</span><span class="delimiter">"</span></span><span class="tag">></span>Something about Glyph<span class="tag"></h2></span> -<span class="line-numbers"> <a href="#n3" name="n3">3</a></span> <span class="tag"><p></span> -<span class="line-numbers"> <a href="#n4" name="n4">4</a></span> You can use Glyph macros in conjunction with -<span class="line-numbers"> <a href="#n5" name="n5">5</a></span> <span class="tag"><em></span>Textile<span class="tag"></em></span> or <span class="tag"><em></span>Markdown<span class="tag"></em></span> to -<span class="line-numbers"> <a href="#n6" name="n6">6</a></span> produce HTML files effortlessly. -<span class="line-numbers"> <a href="#n7" name="n7">7</a></span> <span class="tag"></p></span> -<span class="line-numbers"> <a href="#n8" name="n8">8</a></span> <span class="tag"><p></span> -<span class="line-numbers"> <a href="#n9" name="n9">9</a></span> Alternatively, you can just use <span class="tag"><em></span>Glyph itself<span class="tag"></em></span> -<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span> to generate HTML tags. -<span class="line-numbers"><a href="#n11" name="n11">11</a></span> <span class="tag"></p></span> -<span class="line-numbers"><a href="#n12" name="n12">12</a></span> <span class="tag"><div</span> <span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">section</span><span class="delimiter">"</span></span><span class="tag">></span> -<span class="line-numbers"><a href="#n13" name="n13">13</a></span> <span class="tag"><h3</span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">pdf</span><span class="delimiter">"</span></span><span class="tag">></span>What about PDFs?<span class="tag"></h3></span> -<span class="line-numbers"><a href="#n14" name="n14">14</a></span> <span class="tag"><p></span> -<span class="line-numbers"><a href="#n15" name="n15">15</a></span> Once you have a single, well-formatted HTML -<span class="line-numbers"><a href="#n16" name="n16">16</a></span> file, converting it to PDF is -<span class="line-numbers"><a href="#n17" name="n17">17</a></span> extremely easy with a free 3rd-party renderer -<span class="line-numbers"><a href="#n18" name="n18">18</a></span> like <span class="tag"><a</span> <span class="attribute-name">href</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://www.princexml.com</span><span class="delimiter">"</span></span><span class="tag">></span>Prince<span class="tag"></a></span> -<span class="line-numbers"><a href="#n19" name="n19">19</a></span> or <span class="tag"><a</span> <span class="attribute-name">href</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://code.google.com/p/wkhtmltopdf/</span><span class="delimiter">"</span></span><span class="tag">></span>wkhtmltopdf<span class="tag"></a></span>. -<span class="line-numbers"><strong><a href="#n20" name="n20">20</a></strong></span> <span class="tag"></p></span> -<span class="line-numbers"><a href="#n21" name="n21">21</a></span> <span class="tag"></div></span> -<span class="line-numbers"><a href="#n22" name="n22">22</a></span><span class="tag"></div></span></pre></div> -</div> + -</section> +<pre><code> +<div class="section"> + <h2 id="h_10">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> + <p> + Alternatively, you can just use <em>Glyph itself</em> + to generate HTML tags. + </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 free 3rd-party renderer + like <a href="http://www.princexml.com">Prince</a> + or <a href="http://code.google.com/p/wkhtmltopdf/">wkhtmltopdf</a>. + </p> + </div> +</div> +</code></pre> - <section class="section"> -<header><h1 id="h_4" class="toc">Content Reuse</h1></header> +<h4>Content Reuse</h4> <p>Finding yourself repeating the same sentence over an over? Glyph allows you to create snippets. Within snippets. Within other snippets (and so on, for a long long time…) as long as you don’t define a snippet by defining itself, which would be kinda nasty (and Glyph would complain!):</p> - <div class="CodeRay"> - <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>snippet:[entities|snippets and macros] -<span class="line-numbers"><a href="#n2" name="n2">2</a></span>snippet:[custom_definitions| -<span class="line-numbers"><a href="#n3" name="n3">3</a></span> p[Glyph allows you to define your own &[entities].] -<span class="line-numbers"><a href="#n4" name="n4">4</a></span>] -<span class="line-numbers"><a href="#n5" name="n5">5</a></span>&[custom_definitions]</pre></div> -</div> - <p>...which results in:</p> - <div class="CodeRay"> - <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span><span class="tag"><p></span>Glyph allows you to define your own snippets and macros.<span class="tag"></p></span></pre></div> -</div> +<pre><code> +snippet:[entities|snippets and macros] +snippet:[custom_definitions| + p[Glyph allows you to define your own &[entities].] +] +&[custom_definitions] +</code></pre> + +<p>...which results in:</p> + +<pre><code> +<p>Glyph allows you to define your own snippets and macros.</p> +</code></pre> - <p>If yourself dreaming about <em>parametric</em> snippets, just create your own macros (see the <a href="http://github.com/h3rald/glyph/blob/master/book/text/changelog.glyph">source</a> of Glyph’s changelog, just to have an idea).</p> +<p>If yourself dreaming about <em>parametric</em> snippets, just create your own macros (see the <a href="http://github.com/h3rald/glyph/blob/master/book/text/changelog.glyph">source</a> of Glyph’s changelog, just to have an idea).</p> -</section> - <section class="section"> -<header><h1 id="h_5" class="toc">Automation of Common Tasks</h1></header> +<h4>Automation of Common Tasks</h4> <p>If you’re writing a book, you shouldn’t have to worry about pagination, headers, footers, table of contents, section numbering or similar. Glyph understands you, and will take care of everything for you (with a little help from CSS3, sometimes).</p> -</section> - <section class="section"> -<header><h1 id="h_6" class="toc">Reference Validation</h1></header> +<h4>Reference Validation</h4> <p>Feel free to add plenty of links, snippets, bookmarks, … if Glyph doesn’t find something, it will definitely complain. Broken references are a thing on the past, and you don’t need to worry about it.</p> -</section> - <section class="section"> -<header><h1 id="h_7" class="toc">Extreme Extensibility</h1></header> +<h4>Extreme Extensibility</h4> <ul> - <li>You miss a <code>!!!</code> macro to format really, <em>really</em> important things? Create it. In under 3 seconds, in Ruby or Glyph itself. And yes, you can use special characters, too.</li> - <li>You want your own, very special special <code>glyph create --everything</code> command to create all <em>you</em> need in a Glyph project? You can do it. Using your own Rake tasks, too.</li> - <li>You want Glyph to output <span class="caps">ODF</span> files? You can do it, and you’ll be able to run <code>glyph generate -f odf</code>. This would probably require a little more time, but it’s trivial, from a technical point of view.</li> + <li>You miss a <code>!!!</code> macro to format really, <em>really</em> important things? Create it. In under 3 seconds, in Ruby or Glyph itself. And yes, you can use special characters, too.</li> + <li>You want your own, very special special <code>glyph create --everything</code> command to create all <em>you</em> need in a Glyph project? You can do it. Using your own Rake tasks, too.</li> + <li>You want Glyph to output <span class="caps">ODF</span> files? You can do it, and you’ll be able to run <code>glyph generate -f odf</code>. This would probably require a little more time, but it’s trivial, from a technical point of view.</li> </ul> -</section> - <section class="section"> -<header><h1 id="h_8" class="toc">Convention over Configuration</h1></header> +<h4>Convention over Configuration</h4> <p>Put your text files in <code>/text</code>, your images in <code>/images</code>, add custom macros in a <code>macro</code> folder within your <code>/lib</code> folder… you get the picture: Glyph has its special places.</p> <p>Nonetheless, you also have 1 (<em>one</em>) configuration file to customize to your heart’s content (with smart defaults).</p> -</section> - <section class="section"> -<header><h1 id="h_9" class="toc">Free and Open Source</h1></header> +<h4>Free and Open Source</h4> <p>Glyph is 100% Open Source Software, developed using the Ruby Programming Language and licensed under the very permissive terms of the <a href="http://www.opensource.org/licenses/mit-license.php"><span class="caps">MIT</span> License</a>.</p> <p>If you have Ruby installed, just run <code>gem install glyph</code>. That’s all it takes.</p> -</section> - -</section> - <section class="section"> -<header><h1 id="h_10" class="toc">Resources</h1></header> +<h3>Resources</h3> <ul> - <li>Home Page: <a href="http://www.h3rald.com/glyph/">http://www.h3rald.com/glyph/</a></li> - <li>Repository: <a href="http://www.github.com/h3rald/glyph/">http://www.github.com/h3rald/glyph/</a></li> - <li>Bug Tracking: <a href="http://www.github.com/h3rald/glyph/issues">http://www.github.com/h3rald/glyph/issues</a></li> - <li>Development Wiki <a href="http://wiki.github.com/h3rald/glyph">http://wiki.github.com/h3rald/glyph</a></li> - <li>RubyGem Download <a href="http://www.rubygems.org/gems/glyph">http://www.rubygems.org/gems/glyph</a></li> - <li>Book (<span class="caps">PDF</span>): <a href="http://github.com/downloads/h3rald/glyph/glyph.pdf">http://github.com/downloads/h3rald/glyph/glyph.pdf</a></li> - <li>Book (Web): <a href="http://www.h3rald.com/glyph/book/">http://www.h3rald.com/glyph/book/</a></li> - <li>Reference Documentation: <a href="http://rubydoc.info/gems/glyph/">http://rubydoc.info/gems/glyph/</a></li> - <li>User Group: <a href="http://groups.google.com/group/glyph-framework">http://groups.google.com/group/glyph-framework</a></li> + <li>Repository: <a href="http://www.github.com/h3rald/glyph/">http://www.github.com/h3rald/glyph/</a></li> + <li>Bug Tracking: <a href="http://www.github.com/h3rald/glyph/issues">http://www.github.com/h3rald/glyph/issues</a></li> + <li>Development Wiki <a href="http://wiki.github.com/h3rald/glyph">http://wiki.github.com/h3rald/glyph</a></li> + <li>RubyGem Download <a href="http://www.rubygems.org/gems/glyph">http://www.rubygems.org/gems/glyph</a></li> + <li>Book (<span class="caps">PDF</span>): <a href="http://github.com/downloads/h3rald/glyph/glyph.pdf">http://github.com/downloads/h3rald/glyph/glyph.pdf</a></li> + <li>Book (Web): <a href="http://www.h3rald.com/glyph/book/">http://www.h3rald.com/glyph/book/</a></li> + <li>Reference Documentation: <a href="http://rubydoc.info/gems/glyph/">http://rubydoc.info/gems/glyph/</a></li> + <li>User Group: <a href="http://groups.google.com/group/glyph-framework">http://groups.google.com/group/glyph-framework</a></li> </ul> -</section> - -</section> - - <h3>Latest Updates</h3> - -<ul><li><a href="/articles/glyph-050-released/">Glyph 0.5.0 Released</a> — <time class="timeago" datetime="2011-08-28T19:18:00Z">Sunday, 28 August 2011</time></li> -<li><a href="/articles/glyph-040-released/">Glyph 0.4.0 Released</a> — <time class="timeago" datetime="2010-09-03T17:45:00Z">Friday, 03 September 2010</time></li> -<li><a href="/articles/glyph-030-released/">Glyph 0.3.0 Released</a> — <time class="timeago" datetime="2010-06-13T12:10:00Z">Sunday, 13 June 2010</time></li> -<li><a href="/articles/glyph-020-released/">Glyph 0.2.0 Released</a> — <time class="timeago" datetime="2010-05-09T15:00:00Z">Sunday, 09 May 2010</time></li> -<li><a href="/articles/introducing-glyph/">Introducing Glyph</a> — <time class="timeago" datetime="2010-04-09T17:30:39Z">Friday, 09 April 2010</time></li> +<ul><li><a href="/articles/glyph-050-released/">Glyph 0.5.0 Released</a> </li> + <li><a href="/articles/glyph-040-released/">Glyph 0.4.0 Released</a></li> + <li><a href="/articles/glyph-030-released/">Glyph 0.3.0 Released</a></li> + <li><a href="/articles/glyph-020-released/">Glyph 0.2.0 Released</a></li> + <li><a href="/articles/introducing-glyph/">Introducing Glyph</a></li> </ul> - -
A
contents/glyph/book/acknowledgements.html
@@ -0,0 +1,18 @@
+----- +title: "Glyph – Acknowledgements" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/license.html">← License</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/getting_started/create_project.html">Creating your first Glyph Project →</a></nav> +<p>Glyph was designed and developed by <a href="http://www.h3rald.com">Fabio Cevasco</a> (h3rald).</p> +<p>Special thanks to the following individuals who contributed to Glyph by reporting and fixing issues, proposing and implementing new features or provided Glyph-related resources and plugins:</p> +<ul> + <li><a href="http://www.jabbslad.com">Jamie Atkinson</a> (Jabbslad)</li> + <li><a href="http://koraktor.github.com">Sebastian Staudt</a> (koraktor)</li> + <li><a href="http://balcone.eveel.ru">Dmitry A. Ustalov</a> (eveel)</li> + <li><a href="http://www.stuartellis.eu">Stuart Ellis</a> (stuartellis)</li> + <li>Eric Givens (darthzippy)</li> + <li><a href="http://www.taylored-software.com/">Tammy Cravit</a> (tammycravit)</li> + <li><a href="https://github.com/grv87">Basil Peace</a> (grv87)</li> +</ul> + +<nav class="navigation"><a href="/glyph/book/license.html">← License</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/getting_started/create_project.html">Creating your first Glyph Project →</a></nav>
A
contents/glyph/book/changelog.html
@@ -0,0 +1,891 @@
+----- +title: "Glyph – Changelog" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/config/output.html">← <code>output.*</code></a> | <a href="/glyph/book/index.html">Contents</a> | </nav> + + + + + + + <section class="section"> +<header><h1 id="h_298" class="toc">v0.5.3 – October 4 2014</h1></header> +<section class="section"> +<header><h1 id="h_299" class="toc">1 Bug Fixed</h1></header> +<table> + <tr> + <th>ID</th> + <th>Description</th> + </tr> + + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/216">#216</a></td> + <td> +<p>Fix error with <span class="caps">SCSS</span> generation</p> +</td> + </tr> + + </table> + +</section> + +</section> + + <section class="section"> +<header><h1 id="h_300" class="toc">v0.5.2 – November 11th 2012</h1></header> +<section class="section"> +<header><h1 id="h_301" class="toc">2 Features Implemented</h1></header> +<table> + <tr> + <th>ID</th> + <th>Description</th> + </tr> + + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/208">#208</a></td> + <td> +<p><span class="caps">HTML</span> output now indented automatically.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/206">#206</a></td> + <td> +<p><span class="caps">CSS</span> improvements.</p> +</td> + </tr> + + </table> + +</section> + + + <section class="section"> +<header><h1 id="h_302" class="toc">2 Bugs Fixed</h1></header> +<table> + <tr> + <th>ID</th> + <th>Description</th> + </tr> + + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/209">#209</a></td> + <td> +<p>Made Glyph compatible with gli v2.×.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/207">#207</a></td> + <td> +<p>Fixed heading level of aliased macro always set to 2.</p> +</td> + </tr> + + </table> + +</section> + +</section> + + <section class="section"> +<header><h1 id="h_303" class="toc">v0.5.1 – December 4th 2011</h1></header> +<section class="section"> +<header><h1 id="h_304" class="toc">2 Bugs Fixed</h1></header> +<table> + <tr> + <th>ID</th> + <th>Description</th> + </tr> + + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/203">#203</a></td> + <td> +<p>Fixed error in <a href="/glyph/book/macros/macros_block.html#m_pubdate"><code>pubdate</code></a> macro.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/204">#204</a></td> + <td> +<p>Updated CodeRay stylesheet.</p> +</td> + </tr> + + </table> + +</section> + +</section> + + <section class="section"> +<header><h1 id="h_305" class="toc">v0.5.0 – August 28th 2011</h1></header> +<section class="section"> +<header><h1 id="h_306" class="toc">16 Features Implemented</h1></header> +<table> + <tr> + <th>ID</th> + <th>Description</th> + </tr> + + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/152">#152</a></td> + <td> +<p>It is now possible to generate a <span class="caps">PDF</span> document through HTML5, not only <span class="caps">HTML</span>, by setting the <code>output.pdf.through</code> setting to <code>html5</code>.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/165">#165</a></td> + <td> +<p>The <a href="/glyph/book/macros/macros_core.html#m_fragment"><code>fragment</code></a> macro and the <a href="/glyph/book/macros/macros_core.html#m_embed"><code>embed</code></a> macro can be used to delimit and embed text fragments, in a way much similar to snippets.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/177">#177</a></td> + <td> +<p>Introduced the concept of “macro representations”, to make macro code output-independent.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/179">#179</a></td> + <td> +<p>Macro can be composed with other macros via backslashes, provided that containers only take exactly one parameter. The new <a href="/glyph/book/macros/macros_core.html#m_xml"><code>xml</code></a> macro dispatcher must be used composed with other macros to create raw <span class="caps">XML</span> tags, prepending = to macro names no longer works.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/180">#180</a></td> + <td> +<p>Glyph can now generate ebooks in <span class="caps">MOBI</span> and <span class="caps">EPUB</span> format – with Calibre’s help.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/181">#181</a></td> + <td> +<p>By using the new <a href="/glyph/book/macros/macros_core.html#m_let"><code>let</code></a> macro macro, it is possible to define lexically scoped “variables” via the <a href="/glyph/book/macros/macros_core.html#m_attribute_"><code>attribute:</code></a> macro, and retrieve them within the scope of the let macro using the <a href="/glyph/book/macros/macros_core.html#m_attribute"><code>attribute</code></a> macro.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/182">#182</a></td> + <td> +<p>A <a href="/glyph/book/macros/macros_core.html#m_while"><code>while</code></a> macro can be used to execute glyph code multiple times.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/183">#183</a></td> + <td> +<p>The <a href="/glyph/book/macros/macros_core.html#m_s"><code>s</code></a> macro dispatcher can be used to call almost any instance method of the Ruby String class. The <code>match</code> macro cannot be used anymore; use <code>s/match</code> instead.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/184">#184</a></td> + <td> +<p>The old <code>rewrite:</code> macro has been renamed to <code>define:</code>. The new <a href="/glyph/book/macros/macros_core.html#m_define_"><code>define:</code></a> macro fully supports recursion.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/189">#189</a></td> + <td> +<p>The <a href="/glyph/book/macros/macros_core.html#m_add"><code>add</code></a> macro, the <a href="/glyph/book/macros/macros_core.html#m_subtract"><code>subtract</code></a> macro and the <a href="/glyph/book/macros/macros_core.html#m_multiply"><code>multiply</code></a> macro macro can be used to perform operations on integers.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/190">#190</a></td> + <td> +<p>The lt, gt, lte, gte macros can be used to compare integer values.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/194">#194</a></td> + <td> +<p>The <a href="/glyph/book/macros/macros_core.html#m_load"><code>load</code></a> macro macro can be used to embed the contents of a file without performing any evaluation.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/195">#195</a></td> + <td> +<p><code>\/</code> must not be used as invisible space separator, instead of <code>\.</code>.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/197">#197</a></td> + <td> +<p>Snippets are no longer managed via a separate snippet.yml file and <em>must</em> be defined within Glyph source files, using the <a href="/glyph/book/macros/macros_core.html#m_snippet_"><code>snippet:</code></a> macro.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/200">#200</a></td> + <td> +<p>Typing <code>glyph -v</code> now prints the current version of Glyph on the screen.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/201">#201</a></td> + <td> +<p>Glyph no longer depends on Jeweler to create and manage its gem.</p> +</td> + </tr> + + </table> + +</section> + + + <section class="section"> +<header><h1 id="h_307" class="toc">4 Bugs Fixed</h1></header> +<table> + <tr> + <th>ID</th> + <th>Description</th> + </tr> + + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/151">#151</a></td> + <td> +<p>Fixed a bug related to Jeweler’s gemspec validation. And for all it matters, Jeweler is no longer a development dependency for Glyph.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/166">#166</a></td> + <td> +<p>Temporary output files are now placed in a temporary folder.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/196">#196</a></td> + <td> +<p>Glyph now handles non-<span class="caps">ASCII</span> characters properly with Ruby 1.9 as well.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/199">#199</a></td> + <td> +<p>Fixed a bug that caused incorrect <span class="caps">TOC</span> nesting when using the <code>src</code> attribute of the <a href="/glyph/book/macros/macros_structure.html#m_section"><code>section</code></a> macro.</p> +</td> + </tr> + + </table> + +</section> + +</section> + + <section class="section"> +<header><h1 id="h_308" class="toc">v0.4.2 – October 22th 2010</h1></header> +<section class="section"> +<header><h1 id="h_309" class="toc">3 Features Implemented</h1></header> +<table> + <tr> + <th>ID</th> + <th>Description</th> + </tr> + + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/172">#172</a></td> + <td> +<p>A new <a href="/glyph/book/macros/macros_core.html#m_output_"><code>output?</code></a> macro can be used to test whether Glyph is compiling to a particular output format.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/175">#175</a></td> + <td> +<p>The conditional macro now support a third parameter (else branch).</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/176">#176</a></td> + <td> +<p>A bunch of new aliases and shortcuts are available for the section macro.</p> +</td> + </tr> + + </table> + +</section> + + + <section class="section"> +<header><h1 id="h_310" class="toc">1 Bug Fixed</h1></header> +<table> + <tr> + <th>ID</th> + <th>Description</th> + </tr> + + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/178">#178</a></td> + <td> +<p>No error is raised anymore if less than the required parameters/attributes are supplied to a rewritten macro.</p> +</td> + </tr> + + </table> + +</section> + +</section> + + <section class="section"> +<header><h1 id="h_311" class="toc">v0.4.1 – September 23th 2010</h1></header> +<section class="section"> +<header><h1 id="h_312" class="toc">5 Bugs Fixed</h1></header> +<table> + <tr> + <th>ID</th> + <th>Description</th> + </tr> + + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/169">#169</a></td> + <td> +<p>*.scss files are now supported by the <a href="/glyph/book/macros/macros_structure.html#m_style"><code>style</code></a> macro.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/170">#170</a></td> + <td> +<p>Improved default CodeRay stylesheet.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/171">#171</a></td> + <td> +<p><span class="caps">SCSS</span> now used internally by Glyph to generate default <span class="caps">CSS</span> files.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/173">#173</a></td> + <td> +<p>Consecutive escape sequences are now interpreted correctly in topics.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/174">#174</a></td> + <td> +<p>Fixed error causing broken images in web5/html5 output.</p> +</td> + </tr> + + </table> + +</section> + +</section> + + <section class="section"> +<header><h1 id="h_313" class="toc">v0.4.0 – September 3th 2010</h1></header> +<section class="section"> +<header><h1 id="h_314" class="toc">13 Features Implemented</h1></header> +<table> + <tr> + <th>ID</th> + <th>Description</th> + </tr> + + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/40">#40</a></td> + <td> +<p>A new <a href="/glyph/book/ref_commands.html#c_stats"><code>stats</code></a> command can be used to display statistics about project files, snippets, macros, bookmarks and links.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/73">#73</a></td> + <td> +<p>It is now possible to validate online <span class="caps">HTTP</span> links.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/112">#112</a></td> + <td> +<p>It is now possible to use <em>wkhtmltopdf</em> instead of Prince to generate <span class="caps">PDF</span> files from <span class="caps">HTML</span> files.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/114">#114</a></td> + <td> +<p>It is now possible to generate documents comprised of multiple files (topics).</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/115">#115</a></td> + <td> +<p>It is now possible to define layouts (used when generating multi-file outputs) using Glyph macros.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/120">#120</a></td> + <td> +<p>It is now possible to compile your project to a single HTML5 file (<code>html5</code> output) or multiple files (<code>web5</code> output)</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/135">#135</a></td> + <td> +<p>Stylesheets can now be linked and imported as well as embedded.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/138">#138</a></td> + <td> +<p><code>web</code> and <code>web5</code> output formats inherit <code>html</code> macros.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/142">#142</a></td> + <td> +<p>A new <a href="/glyph/book/macros/macros_block.html#m_navigation"><code>navigation</code></a> macro can be used in <code>web</code> and <code>web5</code> outputs to navigate through topics.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/143">#143</a></td> + <td> +<p>A topic-based <span class="caps">TOC</span> is generated when compiling to <code>web</code> or <code>web5</code></p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/144">#144</a></td> + <td> +<p>Two new validators are now available to check whether a macro has (or doesn’t have) a certain ancestor: <code>within</code> and <code>not_within</code>.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/147">#147</a></td> + <td> +<p>The default stylesheets provided by Glyph are now compatible with HTML5 outputs (html5 and web5).</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/148">#148</a></td> + <td> +<p>It is now possible to create custom tasks and commands to extend Glyph functionality.</p> +</td> + </tr> + + </table> + +</section> + + + <section class="section"> +<header><h1 id="h_315" class="toc">7 Bugs Fixed</h1></header> +<table> + <tr> + <th>ID</th> + <th>Description</th> + </tr> + + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/133">#133</a></td> + <td> +<p>Added <span class="caps">HTML</span> charset to Glyph documents (utf-8).</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/136">#136</a></td> + <td> +<p>Moved utility functions to separate <code>Glyph::Utils</code> module.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/139">#139</a></td> + <td> +<p>Heavily restructured Glyph configuration.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/140">#140</a></td> + <td> +<p>Added <code>Glyph::Macro::Helpers</code> module to avoid code duplication in macros for different output formats.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/141">#141</a></td> + <td> +<p>Prevented non-rb files to be loaded as macros.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/145">#145</a></td> + <td> +<p>Dotfiles are now ignored by <a href="/glyph/book/ref_commands.html#c_init"><code>init</code></a> command.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/167">#167</a></td> + <td> +<p>Fixed <span class="caps">PDF</span> book download links.</p> +</td> + </tr> + + </table> + +</section> + +</section> + + <section class="section"> +<header><h1 id="h_316" class="toc">v0.3.0 – June 13th 2010</h1></header> +<section class="section"> +<header><h1 id="h_317" class="toc">13 Features Implemented</h1></header> +<table> + <tr> + <th>ID</th> + <th>Description</th> + </tr> + + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/39">#39</a></td> + <td> +<p>A new <a href="/glyph/book/ref_commands.html#c_outline"><code>outline</code></a> command is available to display the document outline.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/110">#110</a></td> + <td> +<p>It is now possible to use Glyph language to produce arbitrary <span class="caps">XML</span> code.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/111">#111</a></td> + <td> +<p>System settings are now stored within a <code>system.*</code> namespace and cannot be changed via the <a href="/glyph/book/macros/macros_core.html#m_config_"><code>config:</code></a> macro or the <a href="/glyph/book/ref_commands.html#c_config"><code>config</code></a> command.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/116">#116</a></td> + <td> +<p>It is now possible to use named attributes within Glyph macros.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/119">#119</a></td> + <td> +<p><a id="new_parser"></a>A new parser was implemented from scratch to improve performance. Treetop gem no longer required.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/121">#121</a></td> + <td> +<p>Some macros have been removed in favor of <span class="caps">XML</span> fallback, others have been updated.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/123">#123</a></td> + <td> +<p>The SyntaxNode class has been specialized to differentiate between macros, attributes, parameters, text and escapes.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/124">#124</a></td> + <td> +<p>Implemented new <a href="/glyph/book/macros/macros_structure.html#m_article"><code>article</code></a> macro and <a href="/glyph/book/macros/macros_structure.html#m_book"><code>book</code></a> macro.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/126">#126</a></td> + <td> +<p>A new <code>rewrite</code> macro has been implemented to create simple macros using just Glyph code.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/127">#127</a></td> + <td> +<p>A new <a href="/glyph/book/macros/macros_core.html#m_alias"><code>alias</code></a> macro has been implemented to create macro aliases.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/128">#128</a></td> + <td> +<p>A blacklist for <span class="caps">XML</span> tags has been exposed via the <code>language.options.xml_blacklist</code> setting.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/129">#129</a></td> + <td> +<p>The <a href="/glyph/book/macros/macros_core.html#m_include"><code>include</code></a> macro can now be used in lite mode, it can evaluate ruby files and requires relative paths.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/130">#130</a></td> + <td> +<p>A new “safe mode” has been implemented to explicitly forbid certain potentially unsafe macros.</p> +</td> + </tr> + + </table> + +</section> + + + <section class="section"> +<header><h1 id="h_318" class="toc">3 Bugs Fixed</h1></header> +<table> + <tr> + <th>ID</th> + <th>Description</th> + </tr> + + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/109">#109</a></td> + <td> +<p>Performance has been dramatically improved by implementing a parser from scratch (see <a href="#new_parser">#119</a>)</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/122">#122</a></td> + <td> +<p>Macro encoding/decoding no longer necessary due to the new parser (see <a href="#new_parser">#119</a>)</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/125">#125</a></td> + <td> +<p>Warning messages have been streamlined.</p> +</td> + </tr> + + </table> + +</section> + +</section> + + <section class="section"> +<header><h1 id="h_319" class="toc">v0.2.0 – May 9th 2010</h1></header> +<section class="section"> +<header><h1 id="h_320" class="toc">11 Features Implemented</h1></header> +<table> + <tr> + <th>ID</th> + <th>Description</th> + </tr> + + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/62">#62</a></td> + <td> +<p>A new <a href="/glyph/book/macros/macros_filters.html#m_highlight"><code>highlight</code></a> macro is available to highlight source code (CodeRay or UltraViolet required).</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/76">#76</a></td> + <td> +<p>It is now possible to use Glyph programmatically via the new <code>Glyph#filter</code> and <code>Glyph#compile</code> methods.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/87">#87</a></td> + <td> +<p>It is now possible to define snippets inside a Glyph source file using the <a href="/glyph/book/macros/macros_core.html#m_snippet_"><code>snippet:</code></a> macro.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/88">#88</a></td> + <td> +<p>It is now possible to change configuration settings inside a Glyph source file using the <a href="/glyph/book/macros/macros_core.html#m_config_"><code>config:</code></a> macro (Jabbslad).</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/89">#89</a></td> + <td> +<p>It is now possible to compile a single Glyph source file without creating a Glyph project.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/92">#92</a></td> + <td> +<p>6 new macros have been defined to allow conditional processing (<a href="/glyph/book/macros/macros_core.html#m_condition"><code>condition</code></a> macro, <a href="/glyph/book/macros/macros_core.html#m_eq"><code>eq</code></a> macro, <a href="/glyph/book/macros/macros_core.html#m_not"><code>not</code></a> macro, <a href="/glyph/book/macros/macros_core.html#m_and"><code>and</code></a> macro, <a href="/glyph/book/macros/macros_core.html#m_or"><code>or</code></a> macro, <a href="/glyph/book/macros/macros_core.html#m_match"><code>match</code></a> macro)</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/94">#94</a></td> + <td> +<p>It is now possible to add <em>validators</em> to macros, for example to check the number of parameters they take.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/97">#97</a></td> + <td> +<p>The <a href="/glyph/book/ref_commands.html#c_compile"><code>compile</code></a> command command can now take an extra <code>--auto</code> switch to trigger document auto-regeneration whenever a source file is changed (koraktor).</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/99">#99</a></td> + <td> +<p>Added a <code>document.draft</code> setting. If set to <code>true</code>, comments and TODOs are rendered in output files.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/100">#100</a></td> + <td> +<p><a id="system_css"></a>Glyph <span class="caps">CSS</span> files are no longer copied to new projects, but they can be referenced as if they were (see also <a href="#css_not_copied">#93</a>).</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/108">#108</a></td> + <td> +<p>It is now possible to define Glyph macros within Glyph source files using the <a href="/glyph/book/macros/macros_core.html#m_macro_"><code>macro:</code></a> macro.</p> +</td> + </tr> + + </table> + +</section> + + + <section class="section"> +<header><h1 id="h_321" class="toc">8 Bugs Fixed</h1></header> +<table> + <tr> + <th>ID</th> + <th>Description</th> + </tr> + + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/86">#86</a></td> + <td> +<p>Warning and error messages have been updated, and it is now possible to show additional debug information. Additionally, syntax errors are now handled before the document is processed.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/93">#93</a></td> + <td> +<p><a id="css_not_copied"></a>Default css files were not copied when creating a new project. The issue has been resolved by allowing the <a href="/glyph/book/macros/macros_structure.html#m_style"><code>style</code></a> macro to reference Glyph’s system styles (see also <a href="#system_css">#100</a>).</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/95">#95</a></td> + <td> +<p>The <a href="/glyph/book/ref_commands.html#c_config"><code>config</code></a> command did not save data to <span class="caps">YAML</span> configuration files. This has been fixed ensuring that internal configuration overrides are not saved to the <span class="caps">YAML</span> file too.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/98">#98</a></td> + <td> +<p>Glyph is now fully compatible with Ruby 1.9.1 and JRuby 1.4.0.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/101">#101</a></td> + <td> +<p>Additional tests have been developed to improve Textile support. There should no longer be errors when using textile block elements inside Glyph macros.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/103">#103</a></td> + <td> +<p>Fixed a bug that caused test failures when deleting the test project directory.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/104">#104</a></td> + <td> +<p>Nested Glyph macros calling <code>Macro#interpret</code> no longer ignore escape delimiters.</p> +</td> + </tr> + + <tr> + <td><a href="https://github.com/h3rald/glyph/issues/107">#107</a></td> + <td> +<p>Added the possibility to encode (using the <code>encode</code> macro) and decode (using the <code>decode</code> macro) macros so that they can be interpreted later.</p> +</td> + </tr> + + </table> + +</section> + +</section> + + <section class="section"> +<header><h1 id="h_322" class="toc">v0.1.0 – April 8th 2010</h1></header> +Initial release. + +</section> +<nav class="navigation"><a href="/glyph/book/config/output.html">← <code>output.*</code></a> | <a href="/glyph/book/index.html">Contents</a> | </nav>
A
contents/glyph/book/compiling/compiling.html
@@ -0,0 +1,82 @@
+----- +title: "Glyph – Compiling a project" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/text_editing/evaluation.html">← Simple Programming and Code Evaluation</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/compiling/lite_mode.html">Compiling single Glyph files →</a></nav> +<p>By default, a Glyph project can be “compiled” into an <span class="caps">HTML</span> document. Additionally, Glyph can also be used to produce documents in the following formats:</p> +<ul> + <li>HTML5</li> + <li><span class="caps">PDF</span> (generated from <span class="caps">HTML</span> using a third-party generator like <a href="http://www.princexml.com/">Prince</a> or <a href="http://code.google.com/p/wkhtmltopdf/">wkhtmltopdf</a>)</li> + <li>Web (i.e. multiple <span class="caps">HTML</span> files)</li> + <li>Web5 (i.e. multiple HTML5 files)</li> +</ul> +<section class="section"> +<header><h1 id="h_50" class="toc">HTML/HTML5 output</h1></header> +<p>To compile a Glyph project to an HTML document, use the <a href="/glyph/book/ref_commands.html#c_compile"><code>compile</code></a> command within your Glyph project folder. Glyph parses the <code>document.glyph</code> file (and all included files and snippets); if no errors are found, Glyph creates an HTML document in the <code>/output/html</code> folder.</p> + <p>The name of the HTML file can be set in the configuration (<a href="/glyph/book/config/document.html#s_document_filename"><code>document.filename</code></a> setting).</p> + <p>To create an HTML5 file instead, you must specify it explicitly like this:</p> + <p> +<code> glyph compile -f html5 </code> +</p> + +</section> +<section class="section"> +<header><h1 id="h_51" class="toc">PDF Output</h1></header> +<p>To generate a PDF document, you must specify <code>pdf</code> as format, like this:</p> + <p> +<code> glyph compile -f pdf </code> +</p> + <p>The command above will attempt to compile the project into an HTML document and then call a third-party PDF generator to convert it into a PDF file.</p> + <p>Currently, Glyph supports:</p> +<ul> + <li><a href="http://www.princexml.com/">Prince</a> (version 7.0 or higher) — a commercial generator that can be used freely for personal use. Prince produces high-quality <span class="caps">PDF</span> files and implement most of the new features introduced in CSS3, used heavily in Glyph’s <a href="/glyph/book/text_editing/stylesheets.html#default_stylesheets"><code>pagination.css</code></a> default stylesheet.</li> + <li><a href="http://code.google.com/p/wkhtmltopdf/">wkhtmltopdf</a> (version 1.0 beta4 or higher) — an open source generator that uses the WebKit rendering engine to transform <span class="caps">HTML</span> files into <span class="caps">PDF</span>. Although not as advanced as Prince, it produces very satisfactory results.</li> +</ul> +<p>By default, Glyph attempts to use wkhtmltopdf. To change this, set the <a href="/glyph/book/config/output.html#s_output_pdf_generator"><code>output_pdf_generator</code></a> setting to <code>prince</code>.</p> + <aside class="note"> +<span class="note-title">Note</span>Glyph expects PDF generators to be installed on the local machine and callable via command line using the <code>wkhtmltopdf</code> or the <code>prince</code> commands. Just install them as you would with any other program, depending on your operating system (yes, they both offer Windows installers). + +</aside> + +</section> + +<section class="section"> +<header><h1 id="h_52" class="toc">EPUB/MOBI output</h1></header> +<p>To generate .epub or .mobi e-books, you must specify <code>epub</code> or <code>mobi</code> as format, like this:</p> + <p> +<code> glyph compile -f mobi </code> +</p> + <p> +<code> glyph compile -f epub </code> +</p> + <p>This option requires that you have <a href="http://calibre-ebook.com/">Calibre</a> and its command-line tools installed. Glyph assumes the ebook-convert command is installed in /usr/bin. If this is not so, you can set the <code>options.ebook.converter</code> option to the path to the ebook-convert command.</p> + <p>If you have cover art for your e-book, put it in the <code>images</code> folder, and specify the name of the file in the <code>document.cover</code> configuration option.</p> + <p>You can also specify the output profile used by the <code>ebook-convert</code> command by setting the <code>output.epub.profile</code> and <code>output.mobi.profile</code> options. If these are not specified, the conversion will use the <code>kindle</code> output profile for mobi files, and the <code>nook</code> output profile for epub files. See the documentation for Calibre for a list of available output profiles.</p> + <aside class="tip"> +<span class="note-title">Tip</span>Giving the command <code> glyph compile -f ebooks </code> will generate both mobi and epub files. + +</aside> + +</section> + +<section class="section"> +<header><h1 id="web_output" class="toc">Web/Web5 Output</h1></header> +<p>To generate a Web or Web5 output, specify <code>web</code> or <code>web5</code> as format. These two output formats behave different way from the others, and require that your project uses <a href="/glyph/book/text_editing/topics.html#topics">topics</a> and <a href="/glyph/book/extending/layouts.html#layouts">layouts</a>.</p> +<p>Basically, here’s what happens when you compile your project in web or web5 format:</p> +<ol> + <li>The document code is parsed as normal</li> + <li>Separate topic files are generated according to the <code>@src</code> attributes of your sections</li> + <li>The <code>document.glyph</code> (or whatever file you’re using as document source) is <em>not</em> rendered. Instead, an <code>index.html</code> file will be created in the output folder based on the contents of your <a href="/glyph/book/extending/layouts.html#index_layout">index layout</a>.</li> +</ol> + +</section> +<section class="section"> +<header><h1 id="auto_regeneration" class="toc">Auto Regeneration</h1></header> +<p>You can also call the <a href="/glyph/book/ref_commands.html#c_compile"><code>compile</code></a> command with a <code>--auto</code> switch. If you do so, your project will be recompiled automatically every time any source file is changed.</p> + <aside class="note"> +<span class="note-title">Note</span>Auto regeneration requires the <a href="http://rubygems.org/gems/directory_watcher">directory_watcher</a> gem to be installed. + +</aside> + +</section> +<nav class="navigation"><a href="/glyph/book/text_editing/evaluation.html">← Simple Programming and Code Evaluation</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/compiling/lite_mode.html">Compiling single Glyph files →</a></nav>
A
contents/glyph/book/compiling/lite_mode.html
@@ -0,0 +1,25 @@
+----- +title: "Glyph – Compiling single Glyph files" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/compiling/compiling.html">← Compiling a project</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/compiling/programmatic_usage.html">Using Glyph programmatically →</a></nav> + <p>Glyph's primary goal is to author complex documents like books or manuals. In order to do so, a Glyph project is required to keep everything organized and automated via a set of predefined conventions, exactly like Ruby on Rails or other similar frameworks do.</p> + <p>If you want to write a one-page article or a short draft, however, creating and managing Glyph projects can be an unnecessary burden. Luckily, you don't have to: you can use Glyph to compile single files containing Glyph code, by adding one parameter (or two if you want to specify a custom destination file) to the <a href="/glyph/book/ref_commands.html#c_compile"><code>compile</code></a> command, like this:</p> + <p> +<code>glyph compile source.glyph destination.htm</code> +</p> + <p>This command will process a file called <code>source.glyph</code> and produce an HTML file called <code>destination.htm</code>.</p> + <section class="section"> +<header><h1 id="lite_limitations" class="toc">Limitations</h1></header> +<p>This sort of “lite” mode comes with a few minor limitations:</p> +<ul> + <li>Snippets can only be defined inside the source file, using the <a href="/glyph/book/macros/macros_core.html#m_snippet_"><code>snippet:</code></a> macro.</li> + <li>Project configuration settings can only be defined inside the source file, using the <a href="/glyph/book/macros/macros_core.html#m_config_"><code>config:</code></a> macro.</li> + <li>Custom macros can only be defined inside the source file, using the <a href="/glyph/book/macros/macros_core.html#m_macro_"><code>macro:</code></a> macro.</li> + <li>Images must be referenced with their absolute path, or a path relative to the current directory, and will not be copied anywhere when the output file is generated.</li> + <li>Stylesheets must be referenced with their absolute path, or a path relative to the current directory, or the name of an existing Glyph <a href="/glyph/book/text_editing/stylesheets.html#default_stylesheets">system stylesheet</a>.</li> + <li>The files included through the <a href="/glyph/book/macros/macros_core.html#m_include"><code>include</code></a> macro must be referenced with their absolute path, or a path relative to the current directory.</li> +</ul> + +</section> +<nav class="navigation"><a href="/glyph/book/compiling/compiling.html">← Compiling a project</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/compiling/programmatic_usage.html">Using Glyph programmatically →</a></nav>
A
contents/glyph/book/compiling/programmatic_usage.html
@@ -0,0 +1,99 @@
+----- +title: "Glyph – Using Glyph programmatically" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/compiling/lite_mode.html">← Compiling single Glyph files</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/stats/stats.html">Using the stats command →</a></nav> + <p>Besides using Glyph from the command line, you can also use it straight from your code. Glyph’s public <a href="http://rubydoc.info/gems/glyph"><span class="caps">API</span></a> is simple and can be used to:</p> +<ul> + <li>Retrieve and update configuration settings (using <code>Glyph[]</code> and <code>Glyph[]=</code>)</li> + <li>Filter text to <span class="caps">HTML</span> (using <code>Glyph#filter</code>)</li> + <li>Compile Glyph source files into <span class="caps">HTML</span> or <span class="caps">PDF</span> files (using <code>Glyph#compile</code>)</li> +</ul> +<p>That’s pretty much it. Of course, both the <code>filter</code> and <code>compile</code> method cause Glyph to run in <a href="/glyph/book/compiling/lite_mode.html#lite_mode"><em>lite</em> mode</a>, so the same <a href="/glyph/book/compiling/lite_mode.html#lite_limitations">limitations</a> apply.</p> + <aside class="tip"> +<span class="note-title">Tip</span><p>For an example on how to use Glyph programmatically (specifically in conjunction with the <a href="http://nanoc.stoneship.org/">nanoc</a> static site generator), see <a href="http://github.com/h3rald/h3rald">h3rald.com source code</a>, in particular:</p> +<ul> + <li><a href="http://github.com/h3rald/h3rald/blob/master/lib/glyph_filter.rb">lib/glyph_filter.rb</a> — using the <code>Glyph#filter</code> method.</li> + <li><a href="http://github.com/h3rald/h3rald/blob/master/lib/glyph_context.rb">lib/glyph_context.rb</a> — using the <code>Glyph#compile</code> method to generate <span class="caps">PDF</span> files.</li> +</ul> + +</aside> + <section class="section"> +<header><h1 id="modes" class="toc">Modes</h1></header> +<p>It is possible to specify some flags (or "modes") to make Glyph behave slightly different than normal, as shown in the following table (by default, none of these is used).</p> + <table> + <tr> + <th>Name</th> + <th>Writer Method</th> + <th>Reader Method</th> + <th>Description</th> + </tr> + <tr> + <td>Test Mode</td> + <td> +<code>Glyph.test_mode=</code> +</td> + <td> +<code>Glyph.test?</code> +</td> + <td>Used internally by the <code>rake spec</code> task to run Glyph's specs.</td> + </tr> + <tr> + <td>Library Mode</td> + <td> +<code>Glyph.library_mode=</code> +</td> + <td> +<code>Glyph.library?</code> +</td> + <td>If enabled, the <a href="/glyph/book/ref_commands.html#c_compile"><code>compile</code></a> command command will raise exceptions instead of printing errors on the screen. Enabled by the <code>Glyph.compile</code> command.</td> + </tr> + <tr> + <td>Debug Mode</td> + <td> +<code>Glyph.debug_mode=</code> +</td> + <td> +<code>Glyph.debug?</code> +</td> + <td>If enabled, additional diagnostic information (such as backtraces or macro values) will be displayed. Enabled by specifying the <a href="/glyph/book/ref_commands.html#debug_switch">debug switch</a> when running a Glyph command.</td> + </tr> + <tr> + <td>Lite Mode</td> + <td> +<code>Glyph.lite_mode=</code> +</td> + <td> +<code>Glyph.lite?</code> +</td> + <td> + <p>Used to compile <a href="/glyph/book/compiling/lite_mode.html#lite_mode">single files</a>. Enabled by:</p> +<ul> + <li>The <code>Glyph.compile</code> and <code>Glyph.filter</code> methods.</li> + <li>The <a href="/glyph/book/ref_commands.html#c_compile"><code>compile</code></a> command, if at least one parameter is supplied.</li> +</ul> + </td> + </tr> + <tr> + <td>Safe Mode</td> + <td> +<code>Glyph.safe_mode=</code> +</td> + <td> +<code>Glyph.safe?</code> +</td> + <td> + <p>If enabled, the following macros cannot be used and will return an error:</p> +<ul> + <li><a href="/glyph/book/macros/macros_core.html#m_ruby"><code>ruby</code></a> macro</li> + <li><a href="/glyph/book/macros/macros_core.html#m_macro_"><code>macro:</code></a> macro</li> + <li><a href="/glyph/book/macros/macros_core.html#m_include"><code>include</code></a> macro</li> + <li><a href="/glyph/book/macros/macros_core.html#m_define_"><code>define:</code></a> macro</li> + <li><a href="/glyph/book/macros/macros_core.html#m_config_"><code>config:</code></a> macro</li> +</ul> + </td> + </tr> + </table> + +</section> +<nav class="navigation"><a href="/glyph/book/compiling/lite_mode.html">← Compiling single Glyph files</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/stats/stats.html">Using the stats command →</a></nav>
A
contents/glyph/book/config/document.html
@@ -0,0 +1,172 @@
+----- +title: "Glyph – <code>document.*</code>" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/macros/macros_structure.html">← Structure Macros</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/config/filters.html"><code>filters.*</code> →</a></nav> +The following configuration settings are related to the current Glyph document. Therefore, you should update them right after creating a project. + +<table> + <tr> + <th>Name</th> + <th>Description</th> + <th>Default</th> + </tr> + <tr> + <td> +<code>document.author</code> <a id="s_document_author"></a> +</td> + <td> +<p>The author of the document.</p> +</td> + <td> + <code> +"" + </code> + </td> + </tr> + <tr> + <td> +<code>document.cover</code> <a id="s_document_cover"></a> +</td> + <td> +<p>The image used as the document cover (used only for e-book generation).</p> +</td> + <td> + <code> +false + </code> + </td> + </tr> + <tr> + <td> +<code>document.draft</code> <a id="s_document_draft"></a> +</td> + <td> +<p>If set to <code>true</code>, the document is considered a draft, so <a href="/glyph/book/macros/macros_inline.html#m_draftcomment">draft comments</a> and <a href="/glyph/book/macros/macros_inline.html#m_todo">todo items</a> will be displayed.</p> +</td> + <td> + <code> +false + </code> + </td> + </tr> + <tr> + <td> +<code>document.filename</code> <a id="s_document_filename"></a> +</td> + <td> +<p>The name of the output file.</p> +</td> + <td> + <code> +"" + </code> + </td> + </tr> + <tr> + <td> +<code>document.output</code> <a id="s_document_output"></a> +</td> + <td> +<p>The format of the output file. It can be set to:</p> +<ul> + <li><code>epub</code></li> + <li><code>html5</code></li> + <li><code>html</code></li> + <li><code>mobi</code></li> + <li><code>pdf</code></li> + <li><code>web5</code></li> + <li><code>web</code></li> +</ul> +</td> + <td> + <code> +"html" + </code> + </td> + </tr> + <tr> + <td> +<code>document.revision</code> <a id="s_document_revision"></a> +</td> + <td> +<p>The document’s revision.</p> +</td> + <td> + <code> +"" + </code> + </td> + </tr> + <tr> + <td> +<code>document.source</code> <a id="s_document_source"></a> +</td> + <td> +<p>The main source file to compile. It can be also be overridden by calling the <a href="/glyph/book/ref_commands.html#c_compile"><code>compile</code></a> command with the <code>-s</code> option.</p> +</td> + <td> + <code> +"document.glyph" + </code> + </td> + </tr> + <tr> + <td> +<code>document.styles</code> <a id="s_document_styles"></a> +</td> + <td> +<p>How to process stylesheets. It can be set to one of the following values:</p> +<ul> + <li><code>embed</code> — Embed stylesheets within the document.</li> + <li><code>link</code> — Link stylesheets.</li> + <li><code>import</code> — Import stylesheets using the <code>@import</code> <span class="caps">CSS</span> directive.</li> +</ul> +</td> + <td> + <code> +"embed" + </code> + </td> + </tr> + <tr> + <td> +<code>document.subtitle</code> <a id="s_document_subtitle"></a> +</td> + <td> +<p>The subtitle of the document, displayed using the <a href="/glyph/book/macros/macros_block.html#m_subtitle"><code>subtitle</code></a> macro.</p> +</td> + <td> + <code> +"" + </code> + </td> + </tr> + <tr> + <td> +<code>document.title</code> <a id="s_document_title"></a> +</td> + <td> +<p>The title of the document, displayed using the <a href="/glyph/book/macros/macros_block.html#m_title"><code>title</code></a> macro.</p> +</td> + <td> + <code> +"" + </code> + </td> + </tr> + <tr> + <td> +<code>document.isbn</code> <a id="s_document_isbn"></a> +</td> + <td> +<p>The <span class="caps">ISBN</span> of the document, for e-book generation.</p> +</td> + <td> + <code> +false + </code> + </td> + </tr> + </table> +<nav class="navigation"><a href="/glyph/book/macros/macros_structure.html">← Structure Macros</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/config/filters.html"><code>filters.*</code> →</a></nav>
A
contents/glyph/book/config/filters.html
@@ -0,0 +1,100 @@
+----- +title: "Glyph – <code>filters.*</code>" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/config/document.html">← <code>document.*</code></a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/config/options.html"><code>options.*</code> →</a></nav> +These settings are used to configure some special options related to output filters and highlighters. + +<table> + <tr> + <th>Name</th> + <th>Description</th> + <th>Default</th> + </tr> + <tr> + <td> +<code>filters.coderay.*</code> <a id="s_filters_coderay_"></a> +</td> + <td> +<p>Some <a href="http://coderay.rubychan.de/">Coderay</a>-specific <a href="http://coderay.rubychan.de/doc/classes/CodeRay/Encoders/HTML.html">options</a>.</p> +</td> + <td> + <code> +nil + </code> + </td> + </tr> + <tr> + <td> +<code>filters.highlighter</code> <a id="s_filters_highlighter"></a> +</td> + <td> +<p>The current highlighter to use. It can be set to <code>coderay</code> or <code>ultraviolet</code></p> +</td> + <td> + <code> +"coderay" + </code> + </td> + </tr> + <tr> + <td> +<code>filters.markdown.converter</code> <a id="s_filters_markdown_converter"></a> +</td> + <td> +<p>The name of the markdown converter to use with the <a href="/glyph/book/macros/macros_filters.html#m_markdown"><code>markdown</code></a> macro. It can be set to one of the following values:</p> +<ul> + <li>BlueCloth</li> + <li>RDiscount</li> + <li>Maruku</li> + <li>Kramdown</li> +</ul> +<p>If not set, Glyph tests for the presence of each gem in the same order, until one is found.</p> +</td> + <td> + <code> +"bluecloth" + </code> + </td> + </tr> + <tr> + <td> +<code>filters.redcloth.restrictions</code> <a id="s_filters_redcloth_restrictions"></a> +</td> + <td> +<p>An <code>Array</code> containing restrictions applied to RedCloth, used by the <a href="/glyph/book/macros/macros_filters.html#m_textile"><code>textile</code></a> macro (see <a href="http://redcloth.rubyforge.org/classes/RedCloth/TextileDoc.html">RedCloth Documentation</a> for more information).</p> +</td> + <td> + <code> +[] + </code> + </td> + </tr> + <tr> + <td> +<code>filters.ultraviolet.line_numbers</code> <a id="s_filters_ultraviolet_line_numbers"></a> +</td> + <td> +<p>Whether the <a href="http://ultraviolet.rubyforge.org/">Ultraviolet</a> highlighter should display line numbers or not.</p> +</td> + <td> + <code> +true + </code> + </td> + </tr> + <tr> + <td> +<code>filters.ultraviolet.theme</code> <a id="s_filters_ultraviolet_theme"></a> +</td> + <td> +<p>The theme used by the <a href="http://ultraviolet.rubyforge.org/">Ultraviolet</a> highlighter.</p> +</td> + <td> + <code> +"lazy" + </code> + </td> + </tr> + </table> +<nav class="navigation"><a href="/glyph/book/config/document.html">← <code>document.*</code></a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/config/options.html"><code>options.*</code> →</a></nav>
A
contents/glyph/book/config/options.html
@@ -0,0 +1,111 @@
+----- +title: "Glyph – <code>options.*</code>" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/config/filters.html">← <code>filters.*</code></a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/config/output.html"><code>output.*</code> →</a></nav> +The following configuration settings are used to enable or disable specific Glyph functionalities and behaviors. + +<table> + <tr> + <th>Name</th> + <th>Description</th> + <th>Default</th> + </tr> + <tr> + <td> +<code>options.filters_by_file_extension</code> <a id="s_options_filters_by_file_extension"></a> +</td> + <td> +<p>If set to <code>true</code>, a filter macro is applied to included files, based on their extensions (<span class="fmi">for more information on <mark>including files</mark>, see <a href="/glyph/book/text_editing/inclusions.html#incl">Content Reuse</a></span>).</p> +</td> + <td> + <code> +nil + </code> + </td> + </tr> + <tr> + <td> +<code>options.macro_set</code> <a id="s_options_macro_set"></a> +</td> + <td> +<p>Determines which macro set will be loaded. It can be set to:</p> +<ul> + <li>glyph — Loads core, filter, xml macros plus all macros necessary for the <a href="/glyph/book/config/document.html#s_document_output"><code>document.output</code></a> setting.</li> + <li>xml — Loads core and xml macros.</li> + <li>core — Loads core macros only.</li> +</ul> +</td> + <td> + <code> +"glyph" + </code> + </td> + </tr> + <tr> + <td> +<code>options.safe_mode</code> <a id="s_options_safe_mode"></a> +</td> + <td> +<p>Enables Safe Mode (<span class="fmi">for more information on <mark>Glyph modes</mark>, see <a href="/glyph/book/compiling/programmatic_usage.html#modes">Modes</a></span>).</p> +</td> + <td> + <code> +false + </code> + </td> + </tr> + <tr> + <td> +<code>options.url_validation</code> <a id="s_options_url_validation"></a> +</td> + <td> +<p>If set to <em>true_, every external link will be validated (see </em>editing/links.html#links">Links and Bookmarks</a>).</p> +</td> + <td> + <code> +false + </code> + </td> + </tr> + <tr> + <td> +<code>options.xml_blacklist</code> <a id="s_options_xml_blacklist"></a> +</td> + <td> +<p>The <span class="caps">XML</span> tags listed here cannot be generated using Glyph code.</p> +</td> + <td> + <code> +["applet", "base", "basefont", "embed", "frame", "frameset", "iframe", "isindex", "meta", "noframes", "noscript", "object", "param", "title"] + </code> + </td> + </tr> + <tr> + <td> +<code>options.xml_fallback</code> <a id="s_options_xml_fallback"></a> +</td> + <td> +<p>If set to true, any unknown macro name will considered an <span class="caps">XML</span> element (see <a href="/glyph/book/document.html#other_elements">Other <span class="caps">HTML</span> Elements</a>).</p> +</td> + <td> + <code> +true + </code> + </td> + </tr> + <tr> + <td> +<code>options.ebook.converter</code> <a id="s_options_ebook_converter"></a> +</td> + <td> +<p>The full path name of the ebook-convert command. Defaults to /usr/bin/ebook-convert.</p> +</td> + <td> + <code> +nil + </code> + </td> + </tr> + </table> +<nav class="navigation"><a href="/glyph/book/config/filters.html">← <code>filters.*</code></a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/config/output.html"><code>output.*</code> →</a></nav>
A
contents/glyph/book/config/output.html
@@ -0,0 +1,642 @@
+----- +title: "Glyph – <code>output.*</code>" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/config/options.html">← <code>options.*</code></a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/changelog.html">Changelog →</a></nav> + + + + + + + + + + +These settings are used to configure output-specific options. + + +<section class="section"> +<header><h1 id="h_290" class="toc">output.epub.*</h1></header> +<table> + <tr> + <th>Name</th> + <th>Description</th> + <th>Default</th> + </tr> + <tr> + <td> +<code>output.epub.extension</code> <a id="s_output_epub_extension"></a> +</td> + <td> +<p>The extension to use for the output file(s).</p> +</td> + <td> + <code> +".epub" + </code> + </td> + </tr> + <tr> + <td> +<code>output.epub.filter_target</code> <a id="s_output_epub_filter_target"></a> +</td> + <td> +<p>The output target for filters. It can be set to <code>html</code> (for RedCloth and MarkDown) or <code>latex</code> (RedCloth-only).</p> +</td> + <td> + <code> +"html" + </code> + </td> + </tr> + <tr> + <td> +<code>output.epub.generator</code> <a id="s_output_epub_generator"></a> +</td> + <td> +<p>The external program used to generate <span class="caps">EPUB</span> files. It must be set to <code>calibre</code>.</p> +</td> + <td> + <code> +"calibre" + </code> + </td> + </tr> + <tr> + <td> +<code>output.epub.calibre</code> <a id="s_output_epub_calibre"></a> +</td> + <td> +<p>An array of options to configure Calibre. See the <a href="http://calibre-ebook.com/user_manual/cli/ebook-convert-3.html">full list</a>.</p> +</td> + <td> + <code> +{"output-profile"=>"nook"} + </code> + </td> + </tr> + <tr> + <td> +<code>output.epub.macro_reps</code> <a id="s_output_epub_macro_reps"></a> +</td> + <td> +<p>The name of the representation file from which macro representation will be loaded.</p> +</td> + <td> + <code> +"html" + </code> + </td> + </tr> + <tr> + <td> +<code>output.epub.multifile</code> <a id="s_output_epub_multifile"></a> +</td> + <td> +<p>If set to <em>true_, the document will be rendered in multiple files, according to the specified </em>editing/topics.html#topics">topics</a>.</p> +</td> + <td> + <code> +false + </code> + </td> + </tr> + </table> + +</section> +<section class="section"> +<header><h1 id="h_291" class="toc">output.mobi.*</h1></header> +<table> + <tr> + <th>Name</th> + <th>Description</th> + <th>Default</th> + </tr> + <tr> + <td> +<code>output.mobi.extension</code> <a id="s_output_mobi_extension"></a> +</td> + <td> +<p>The extension to use for the output file(s).</p> +</td> + <td> + <code> +".mobi" + </code> + </td> + </tr> + <tr> + <td> +<code>output.mobi.filter_target</code> <a id="s_output_mobi_filter_target"></a> +</td> + <td> +<p>The output target for filters. It can be set to <code>html</code> (for RedCloth and MarkDown) or <code>latex</code> (RedCloth-only).</p> +</td> + <td> + <code> +"html" + </code> + </td> + </tr> + <tr> + <td> +<code>output.mobi.generator</code> <a id="s_output_mobi_generator"></a> +</td> + <td> +<p>The external program used to generate <span class="caps">MOBI</span> files. It must be set to <code>calibre</code>.</p> +</td> + <td> + <code> +"calibre" + </code> + </td> + </tr> + <tr> + <td> +<code>output.mobi.calibre</code> <a id="s_output_mobi_calibre"></a> +</td> + <td> +<p>An array of options to configure Calibre. See the <a href="http://calibre-ebook.com/user_manual/cli/ebook-convert-3.html">full list</a>.</p> +</td> + <td> + <code> +{"no-inline-toc"=>nil, "output-profile"=>"kindle"} + </code> + </td> + </tr> + <tr> + <td> +<code>output.mobi.macro_reps</code> <a id="s_output_mobi_macro_reps"></a> +</td> + <td> +<p>The name of the representation file from which macro representation will be loaded.</p> +</td> + <td> + <code> +"html" + </code> + </td> + </tr> + <tr> + <td> +<code>output.mobi.multifile</code> <a id="s_output_mobi_multifile"></a> +</td> + <td> +<p>If set to <em>true_, the document will be rendered in multiple files, according to the specified </em>editing/topics.html#topics">topics</a>.</p> +</td> + <td> + <code> +false + </code> + </td> + </tr> + </table> + +</section> +<section class="section"> +<header><h1 id="h_292" class="toc">output.pdf.*</h1></header> +<table> + <tr> + <th>Name</th> + <th>Description</th> + <th>Default</th> + </tr> + <tr> + <td> +<code>output.pdf.extension</code> <a id="s_output_pdf_extension"></a> +</td> + <td> +<p>The extension to use for the output file(s).</p> +</td> + <td> + <code> +".pdf" + </code> + </td> + </tr> + <tr> + <td> +<code>output.pdf.filter_target</code> <a id="s_output_pdf_filter_target"></a> +</td> + <td> +<p>The output target for filters. It can be set to <code>html</code> (for RedCloth and MarkDown) or <code>latex</code> (RedCloth-only).</p> +</td> + <td> + <code> +"html" + </code> + </td> + </tr> + <tr> + <td> +<code>output.pdf.through</code> <a id="s_output_pdf_through"></a> +</td> + <td> +<p>The intermediate format from which a <span class="caps">PDF</span> file is generated. It can be set to <code>html</code> or <code>html5</code>.</p> +</td> + <td> + <code> +"html" + </code> + </td> + </tr> + <tr> + <td> +<code>output.pdf.generator</code> <a id="s_output_pdf_generator"></a> +</td> + <td> +<p>The external program used to generate <span class="caps">PDF</span> files. It can be set to <code>prince</code> or <code>wkhtmltopdf</code>.</p> +</td> + <td> + <code> +"prince" + </code> + </td> + </tr> + <tr> + <td> +<code>output.pdf.macro_reps</code> <a id="s_output_pdf_macro_reps"></a> +</td> + <td> +<p>The name of the representation file from which macro representation will be loaded.</p> +</td> + <td> + <code> +"html" + </code> + </td> + </tr> + <tr> + <td> +<code>output.pdf.multifile</code> <a id="s_output_pdf_multifile"></a> +</td> + <td> +<p>If set to <em>true_, the document will be rendered in multiple files, according to the specified </em>editing/topics.html#topics">topics</a>.</p> +</td> + <td> + <code> +false + </code> + </td> + </tr> + </table> + +</section> +<section class="section"> +<header><h1 id="h_293" class="toc">output.html.*</h1></header> +<table> + <tr> + <th>Name</th> + <th>Description</th> + <th>Default</th> + </tr> + <tr> + <td> +<code>output.html.extension</code> <a id="s_output_html_extension"></a> +</td> + <td> +<p>The extension to use for the output file(s).</p> +</td> + <td> + <code> +".html" + </code> + </td> + </tr> + <tr> + <td> +<code>output.html.filter_target</code> <a id="s_output_html_filter_target"></a> +</td> + <td> +<p>The output target for filters. It can be set to <code>html</code> (for RedCloth and MarkDown) or <code>latex</code> (RedCloth-only).</p> +</td> + <td> + <code> +"html" + </code> + </td> + </tr> + <tr> + <td> +<code>output.html.macro_reps</code> <a id="s_output_html_macro_reps"></a> +</td> + <td> +<p>The name of the representation file from which macro representation will be loaded.</p> +</td> + <td> + <code> +"html" + </code> + </td> + </tr> + <tr> + <td> +<code>output.html.multifile</code> <a id="s_output_html_multifile"></a> +</td> + <td> +<p>If set to <em>true_, the document will be rendered in multiple files, according to the specified </em>editing/topics.html#topics">topics</a>.</p> +</td> + <td> + <code> +false + </code> + </td> + </tr> + </table> + +</section> +<section class="section"> +<header><h1 id="h_294" class="toc">output.html5.*</h1></header> +<table> + <tr> + <th>Name</th> + <th>Description</th> + <th>Default</th> + </tr> + <tr> + <td> +<code>output.html5.extension</code> <a id="s_output_html5_extension"></a> +</td> + <td> +<p>The extension to use for the output file(s).</p> +</td> + <td> + <code> +".html" + </code> + </td> + </tr> + <tr> + <td> +<code>output.html5.filter_target</code> <a id="s_output_html5_filter_target"></a> +</td> + <td> +<p>The output target for filters. It can be set to <code>html</code> (for RedCloth and MarkDown) or <code>latex</code> (RedCloth-only).</p> +</td> + <td> + <code> +"html" + </code> + </td> + </tr> + <tr> + <td> +<code>output.html5.macro_reps</code> <a id="s_output_html5_macro_reps"></a> +</td> + <td> +<p>The name of the representation file from which macro representation will be loaded.</p> +</td> + <td> + <code> +"html5" + </code> + </td> + </tr> + <tr> + <td> +<code>output.html5.multifile</code> <a id="s_output_html5_multifile"></a> +</td> + <td> +<p>If set to <em>true_, the document will be rendered in multiple files, according to the specified </em>editing/topics.html#topics">topics</a>.</p> +</td> + <td> + <code> +false + </code> + </td> + </tr> + </table> + +</section> +<section class="section"> +<header><h1 id="h_295" class="toc">output.web.*</h1></header> +<table> + <tr> + <th>Name</th> + <th>Description</th> + <th>Default</th> + </tr> + <tr> + <td> +<code>output.web.base</code> <a id="s_output_web_base"></a> +</td> + <td> +<p>The directory to use as root for all link paths.</p> +</td> + <td> + <code> +"/" + </code> + </td> + </tr> + <tr> + <td> +<code>output.web.extension</code> <a id="s_output_web_extension"></a> +</td> + <td> +<p>The extension to use for the output file(s).</p> +</td> + <td> + <code> +".html" + </code> + </td> + </tr> + <tr> + <td> +<code>output.web.filter_target</code> <a id="s_output_web_filter_target"></a> +</td> + <td> +<p>The output target for filters. It can be set to <code>html</code> (for RedCloth and MarkDown) or <code>latex</code> (RedCloth-only).</p> +</td> + <td> + <code> +"html" + </code> + </td> + </tr> + <tr> + <td> +<code>output.web.layout_dirs</code> <a id="s_output_web_layout_dirs"></a> +</td> + <td> +<p>The directories from which layout macros will be loaded (both in Glyph’s home and the current project directory).</p> +</td> + <td> + <code> +nil + </code> + </td> + </tr> + <tr> + <td> +<code>output.web.layouts.index</code> <a id="s_output_web_layouts_index"></a> +</td> + <td> +<p>The name of the layout to use to render the document index file.</p> +</td> + <td> + <code> +"index" + </code> + </td> + </tr> + <tr> + <td> +<code>output.web.layouts.topic</code> <a id="s_output_web_layouts_topic"></a> +</td> + <td> +<p>The name of the layout to use to render topic files.</p> +</td> + <td> + <code> +"topic" + </code> + </td> + </tr> + <tr> + <td> +<code>output.web.macro_reps</code> <a id="s_output_web_macro_reps"></a> +</td> + <td> +<p>The name of the representation file from which macro representation will be loaded.</p> +</td> + <td> + <code> +"html" + </code> + </td> + </tr> + <tr> + <td> +<code>output.web.multifile</code> <a id="s_output_web_multifile"></a> +</td> + <td> +<p>If set to <em>true_, the document will be rendered in multiple files, according to the specified </em>editing/topics.html#topics">topics</a>.</p> +</td> + <td> + <code> +true + </code> + </td> + </tr> + </table> + +</section> +<section class="section"> +<header><h1 id="h_296" class="toc">output.web5.*</h1></header> +<table> + <tr> + <th>Name</th> + <th>Description</th> + <th>Default</th> + </tr> + <tr> + <td> +<code>output.web5.base</code> <a id="s_output_web5_base"></a> +</td> + <td> +<p>The directory to use as root for all link paths.</p> +</td> + <td> + <code> +"/" + </code> + </td> + </tr> + <tr> + <td> +<code>output.web5.extension</code> <a id="s_output_web5_extension"></a> +</td> + <td> +<p>The extension to use for the output file(s).</p> +</td> + <td> + <code> +".html" + </code> + </td> + </tr> + <tr> + <td> +<code>output.web5.filter_target</code> <a id="s_output_web5_filter_target"></a> +</td> + <td> +<p>The output target for filters. It can be set to <code>html</code> (for RedCloth and MarkDown) or <code>latex</code> (RedCloth-only).</p> +</td> + <td> + <code> +"html" + </code> + </td> + </tr> + <tr> + <td> +<code>output.web5.layout_dirs</code> <a id="s_output_web5_layout_dirs"></a> +</td> + <td> +<p>The directories from which layout macros will be loaded (both in Glyph’s home and the current project directory).</p> +</td> + <td> + <code> +nil + </code> + </td> + </tr> + <tr> + <td> +<code>output.web5.layouts.index</code> <a id="s_output_web5_layouts_index"></a> +</td> + <td> +<p>The name of the layout to use to render the document index file.</p> +</td> + <td> + <code> +"index" + </code> + </td> + </tr> + <tr> + <td> +<code>output.web5.layouts.topic</code> <a id="s_output_web5_layouts_topic"></a> +</td> + <td> +<p>The name of the layout to use to render topic files.</p> +</td> + <td> + <code> +"topic" + </code> + </td> + </tr> + <tr> + <td> +<code>output.web5.macro_reps</code> <a id="s_output_web5_macro_reps"></a> +</td> + <td> +<p>The name of the representation file from which macro representation will be loaded.</p> +</td> + <td> + <code> +"html5" + </code> + </td> + </tr> + <tr> + <td> +<code>output.web5.multifile</code> <a id="s_output_web5_multifile"></a> +</td> + <td> +<p>If set to <em>true_, the document will be rendered in multiple files, according to the specified </em>editing/topics.html#topics">topics</a>.</p> +</td> + <td> + <code> +true + </code> + </td> + </tr> + </table> + +</section> +<nav class="navigation"><a href="/glyph/book/config/options.html">← <code>options.*</code></a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/changelog.html">Changelog →</a></nav>
A
contents/glyph/book/extending/bookmarks_headers.html
@@ -0,0 +1,21 @@
+----- +title: "Glyph – Bookmarks and Headers" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/extending/params_attrs.html">← Parameters and Attributes</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/placeholders.html">Using Placeholders →</a></nav> + <p>The <a href="http://rubydoc.info/gems/glyph/Macro"><code>Glyph::Macro</code></a> class also includes a few methods to check and store bookmarks and headers. Consider for example the following source code for the <a href="/glyph/book/macros/macros_inline.html#m_anchor"><code>anchor</code></a> macro:</p> + + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>macro <span class="symbol">:anchor</span> <span class="keyword">do</span> +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> min_parameters <span class="integer">1</span> +<span class="line-numbers"><a href="#n3" name="n3">3</a></span> max_parameters <span class="integer">2</span> +<span class="line-numbers"><a href="#n4" name="n4">4</a></span> bookmark <span class="symbol">:id</span> => param(<span class="integer">0</span>), <span class="symbol">:title</span> => param(<span class="integer">1</span>), <span class="symbol">:file</span> => <span class="instance-variable">@source_file</span> +<span class="line-numbers"><a href="#n5" name="n5">5</a></span> <span class="instance-variable">@data</span>[<span class="symbol">:id</span>] = param <span class="integer">0</span> +<span class="line-numbers"><a href="#n6" name="n6">6</a></span> <span class="instance-variable">@data</span>[<span class="symbol">:title</span>] = param <span class="integer">1</span> +<span class="line-numbers"><a href="#n7" name="n7">7</a></span> render +<span class="line-numbers"><a href="#n8" name="n8">8</a></span><span class="keyword">end</span></pre></div> +</div> + + + <p>The <code>bookmark?</code> method can be used to check the existance of a particular ID within the whole document, while the <code>bookmark</code> method is used to store bookmark IDs and titles. In a similar way, you can use <code>header?</code> and <code>header</code> methods to check the existance of headers within the documents or store new ones.</p> +<nav class="navigation"><a href="/glyph/book/extending/params_attrs.html">← Parameters and Attributes</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/placeholders.html">Using Placeholders →</a></nav>
A
contents/glyph/book/extending/command.html
@@ -0,0 +1,57 @@
+----- +title: "Glyph – Defining Custom Commands" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/extending/output_format.html">← Custom Output Formats</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/troubleshooting/errors_generic.html">Generic Errors →</a></nav> +<p>Glyph relies on <a href="http://davetron5000.github.com/gli/"><span class="caps">GLI</span></a> for defining commands. This useful library provides a high-level framework for creating command-line interface similar to <a href="http://git-scm.com/">Git</a>, its <span class="caps">DSL</span> takes care of pretty much everything, from managing command line arguments and options to providing an interactive help system.</p> +<section class="section"> +<header><h1 id="h_108" class="toc">Creating a 'glyph generate' command</h1></header> +<p>Consider the custom task defined in <a href="/glyph/book/extending/task.html#custom_generate_task">Creating a ‘custom:generate’ task</a>. Creating a custom command to call it is fairly straightforward.</p> +<p>First of all, create a <code>lib/commands</code> folder in your project directory. Then, create a <code>.rb</code> file within it, e.g. <code>commands.rake</code>.</p> +<p>Finally, here’s the source of the command:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span><span class="constant">GLI</span>.desc <span class="string"><span class="delimiter">'</span><span class="content">Generates a specific file required for Glyph releases</span><span class="delimiter">'</span></span> +<span class="line-numbers"> <a href="#n2" name="n2">2</a></span>arg_name <span class="string"><span class="delimiter">"</span><span class="content">file_name</span><span class="delimiter">"</span></span> +<span class="line-numbers"> <a href="#n3" name="n3">3</a></span>command <span class="symbol">:generate</span> <span class="keyword">do</span> |c| +<span class="line-numbers"> <a href="#n4" name="n4">4</a></span> c.action <span class="keyword">do</span> |global_options,options,args| +<span class="line-numbers"> <a href="#n5" name="n5">5</a></span> <span class="keyword">if</span> args.blank? <span class="keyword">then</span> +<span class="line-numbers"> <a href="#n6" name="n6">6</a></span> raise <span class="constant">RuntimeError</span>, <span class="string"><span class="delimiter">"</span><span class="content">You must specify a file to generate</span><span class="delimiter">"</span></span> +<span class="line-numbers"> <a href="#n7" name="n7">7</a></span> <span class="keyword">else</span> +<span class="line-numbers"> <a href="#n8" name="n8">8</a></span> <span class="constant">Glyph</span>.run <span class="string"><span class="delimiter">'</span><span class="content">custom:generate</span><span class="delimiter">'</span></span>, args[<span class="integer">0</span>] +<span class="line-numbers"> <a href="#n9" name="n9">9</a></span> <span class="keyword">end</span> +<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span> <span class="keyword">end</span> +<span class="line-numbers"><a href="#n11" name="n11">11</a></span><span class="keyword">end</span></pre></div> +</div> + + <p>That’s it. If you try to run <code>glyph help</code> within your project directory, notice that there’s a new entry for the generate command:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span>$ glyph help +<span class="line-numbers"> <a href="#n2" name="n2">2</a></span>===================================== +<span class="line-numbers"> <a href="#n3" name="n3">3</a></span>Glyph v/0.5.3.1 +<span class="line-numbers"> <a href="#n4" name="n4">4</a></span>===================================== +<span class="line-numbers"> <a href="#n5" name="n5">5</a></span>usage: glyph command [options] +<span class="line-numbers"> <a href="#n6" name="n6">6</a></span> +<span class="line-numbers"> <a href="#n7" name="n7">7</a></span>Options: +<span class="line-numbers"> <a href="#n8" name="n8">8</a></span> -d, --debug - Enable debugging +<span class="line-numbers"> <a href="#n9" name="n9">9</a></span> +<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span>Commands: +<span class="line-numbers"><a href="#n11" name="n11">11</a></span> add - Add a new text file to the project +<span class="line-numbers"><a href="#n12" name="n12">12</a></span> compile - Compile the project +<span class="line-numbers"><a href="#n13" name="n13">13</a></span> config - Get/set configuration settings +<span class="line-numbers"><a href="#n14" name="n14">14</a></span> generate - Generates a specific file required for Glyph releases +<span class="line-numbers"><a href="#n15" name="n15">15</a></span> help - Shows list of commands or help for one command +<span class="line-numbers"><a href="#n16" name="n16">16</a></span> init - Create a new Glyph project +<span class="line-numbers"><a href="#n17" name="n17">17</a></span> outline - Display the document outline +<span class="line-numbers"><a href="#n18" name="n18">18</a></span> stats - Display statistics +<span class="line-numbers"><a href="#n19" name="n19">19</a></span> todo - Display all project TODO items</pre></div> +</div> + + <p>You can now run the Glyph command as expected:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>$ glyph -d generate changelog +<span class="line-numbers"><a href="#n2" name="n2">2</a></span>-- Generating CHANGELOG... +<span class="line-numbers"><a href="#n3" name="n3">3</a></span>-- Done.</pre></div> +</div> + +</section> +<nav class="navigation"><a href="/glyph/book/extending/output_format.html">← Custom Output Formats</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/troubleshooting/errors_generic.html">Generic Errors →</a></nav>
A
contents/glyph/book/extending/commands_tasks.html
@@ -0,0 +1,43 @@
+----- +title: "Glyph – Defining Custom Commands and Tasks" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/extending/further_reading.html">← Further Reading</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/task.html">Defining Custom Tasks →</a></nav> +<p>In most cases, you can extend Glyph just by creating your own <a href="/glyph/book/extending/macro_def.html#macro_def">custom macros</a>. In some cases though, you may want to further customize Glyph to fit the needs of your project, in terms of creating <a href="/glyph/book/extending/command.html#custom_command">custom commands</a> and <a href="/glyph/book/extending/task.html#custom_task">custom tasks</a>.</p> +<p>Glyph’s modular architecture (and the Ruby language itself) lets you to add <em>arbitrary</em> functionality to its core, simply by creating a few Ruby files and putting them in the right places.</p> +<section class="section"> +<header><h1 id="cmd_tasks_arch" class="toc">How Commands and Tasks work</h1></header> +<p>Before creating custom Glyph commands and tasks, you should have a basic understanding on how they work, and which commands — or better, which tasks — are already available.</p> +<p>The following diagram outlines the relationships between the default commands and some tasks:</p> + <figure><img src="/glyph/book/images/glyph/commands_tasks.png" /><figcaption>Some of Glyph default commands and tasks</figcaption></figure> + <p>As you can see:</p> +<ul> + <li>All commands call at at least one task.</li> + <li>There are several task inter-dependencies spanning across three main Rake namespaces: + <ul> + <li><code>project:</code> — used for tasks affecting only the physical structure of the Glyph project.</li> + <li><code>load:</code> — used to load all kinds of files.</li> + <li><code>generate:</code> — used to generate files or copy files from source to output directories</li> + </ul></li> +</ul> + <aside class="box"> +<div class="box-title">Example</div> +<p>Suppose you want to generate a <span class="caps">PDF</span> file by issuing the <code>glyph compile -f pdf</code> command. Under the hood, Glyph calls the following tasks:</p> +<ol> + <li><code>load:config</code> — Load the configuration files</li> + <li><code>load:tasks</code> — Load custom tasks (if any)</li> + <li><code>load:commands</code> — Load custom commands (if any)</li> + <li><code>load:snippets</code> — Load snippets from the <code>snippet.yml</code> file</li> + <li><code>load:macros</code> — Load macros</li> + <li><code>load:all</code> — Dummy task used to call the previous ones</li> + <li><code>generate:document</code> — Parse, analyze and finalize the Glyph document</li> + <li><code>generate:images</code> — Copy images to the output directory (if any)</li> + <li><code>generate:styles</code> — Copy stylesheets to the output directory (if necessary)</li> + <li><code>generate:html</code> — Generate a standalone <span class="caps">HTML</span> file</li> + <li><code>generate:pdf</code> — Generate a <span class="caps">PDF</span> file from a standalone <span class="caps">HTML</span> file</li> +</ol> + +</aside> + +</section> +<nav class="navigation"><a href="/glyph/book/extending/further_reading.html">← Further Reading</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/task.html">Defining Custom Tasks →</a></nav>
A
contents/glyph/book/extending/further_reading.html
@@ -0,0 +1,15 @@
+----- +title: "Glyph – Further Reading" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/extending/layouts.html">← Layouts</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/commands_tasks.html">Defining Custom Commands and Tasks →</a></nav> + <p>For more examples on how to create more complex macros, have a look at the <a href="http://github.com/h3rald/glyph/tree/master/macros/">source code</a> of the existing ones.</p> +<p>To gain a deeper understanding on how macros are executed, have a look at the following Glyph classes:</p> +<ul> + <li><a href="http://rubydoc.info/gems/glyph/Glyph/Parser"><code>Glyph::Parser</code></a></li> + <li><a href="http://rubydoc.info/gems/glyph/Glyph/SyntaxNode"><code>Glyph::SyntaxNode</code></a></li> + <li><a href="http://rubydoc.info/gems/glyph/Glyph/Interpreter"><code>Glyph::Interpreter</code></a></li> + <li><a href="http://rubydoc.info/gems/glyph/Glyph/Document"><code>Glyph::Document</code></a></li> + <li><a href="http://rubydoc.info/gems/glyph/Glyph/Macro"><code>Glyph::Macro</code></a></li> +</ul> +<nav class="navigation"><a href="/glyph/book/extending/layouts.html">← Layouts</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/commands_tasks.html">Defining Custom Commands and Tasks →</a></nav>
A
contents/glyph/book/extending/internals.html
@@ -0,0 +1,88 @@
+----- +title: "Glyph – A quick look at Glyph's internals" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/stats/links.html">← Link Statistics</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/macro_def.html">Defining Custom Macros →</a></nav> + <p>If you plan on extending Glyph, knowing how it works inside helps. It is not mandatory by any means, but it definitely helps, especially when creating complex macros.</p> + <p>What happens behind the scenes when you call <code>glyph compile</code>? Glyph's code is parsed, analyzed and then translated into text, and here's how:</p> + <figure><img src="/glyph/book/images/glyph/document_generation.png" /><figcaption>A sequence diagram for document generation</figcaption></figure> + <p>From the diagram, it is possible to divide the document generation process into three phases:</p> +<ul> + <li>The <em>Parsing Phase</em> starts when a chunk of Glyph code is passed (by the <code>generate:document</code> Rake task, for example) to a <a href="http://rubydoc.info/gems/glyph/Glyph/Interpreter"><code>Glyph::Interpreter</code></a>. The interpreter initializes a <a href="http://rubydoc.info/gems/glyph/Glyph/Parser"><code>Glyph::Parser</code></a> that parses the code and returns an <em>Abstract Syntax Tree</em> (<span class="caps">AST</span>) of <a href="http://rubydoc.info/gems/glyph/Glyph/SyntaxNode"><code>Glyph::SyntaxNode</code></a> objects.</li> + <li>The <em>Analysis Phase</em> (Processing) starts when the interpreter method calls the <code>analyze</code> method, instantiating a new <a href="http://rubydoc.info/gems/glyph/Glyph/Document"><code>Glyph::Document</code></a>. The <code>Glyph::Document</code> object evaluates the <span class="caps">AST</span> expanding all macro nodesth (that’s when macros are executed) and generates string.</li> + <li>The <em>Finalization Phase</em> (Post-Processing) starts when the interpreter calls the <code>finalyze</code> method, causing the <code>Glyph::Document</code> object to perform a series of finalizations on the string obtained after analysis, i.e. it replaces escape sequences and placeholders.</li> +</ul> + <section class="section"> +<header><h1 id="h_83" class="toc">Example: A short note</h1></header> +<p>As an example, consider the following Glyph code:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>fmi[something|#test] +<span class="line-numbers"><a href="#n2" name="n2">2</a></span>... +<span class="line-numbers"><a href="#n3" name="n3">3</a></span>section[ +<span class="line-numbers"><a href="#n4" name="n4">4</a></span> @title[Test Section] +<span class="line-numbers"><a href="#n5" name="n5">5</a></span> @id[test] +<span class="line-numbers"><a href="#n6" name="n6">6</a></span>... +<span class="line-numbers"><a href="#n7" name="n7">7</a></span>]</pre></div> +</div> + + <p>This simple snippet uses the <a href="/glyph/book/macros/macros_inline.html#m_fmi"><code>fmi</code></a> macro to link to a section later on in the document. When parsed, the produced AST is the following:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span>{<span class="symbol">:name</span>=><span class="symbol"><span class="symbol">:</span><span class="delimiter">"</span><span class="content">--</span><span class="delimiter">"</span></span>} +<span class="line-numbers"> <a href="#n2" name="n2">2</a></span> {<span class="symbol">:name</span>=><span class="symbol">:fmi</span>, <span class="symbol">:escape</span>=><span class="predefined-constant">false</span>} +<span class="line-numbers"> <a href="#n3" name="n3">3</a></span> {<span class="symbol">:name</span>=><span class="symbol"><span class="symbol">:</span><span class="delimiter">"</span><span class="content">0</span><span class="delimiter">"</span></span>} +<span class="line-numbers"> <a href="#n4" name="n4">4</a></span> {<span class="symbol">:value</span>=><span class="string"><span class="delimiter">"</span><span class="content">something</span><span class="delimiter">"</span></span>} +<span class="line-numbers"> <a href="#n5" name="n5">5</a></span> {<span class="symbol">:name</span>=><span class="symbol"><span class="symbol">:</span><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span>} +<span class="line-numbers"> <a href="#n6" name="n6">6</a></span> {<span class="symbol">:value</span>=><span class="string"><span class="delimiter">"</span><span class="content">#test</span><span class="delimiter">"</span></span>} +<span class="line-numbers"> <a href="#n7" name="n7">7</a></span> {<span class="symbol">:value</span>=><span class="string"><span class="delimiter">"</span><span class="char">\n</span><span class="delimiter">"</span></span>} +<span class="line-numbers"> <a href="#n8" name="n8">8</a></span> {<span class="symbol">:value</span>=><span class="string"><span class="delimiter">"</span><span class="char">\</span><span class="content">[</span><span class="delimiter">"</span></span>, <span class="symbol">:escaped</span>=><span class="predefined-constant">true</span>} +<span class="line-numbers"> <a href="#n9" name="n9">9</a></span> {<span class="symbol">:value</span>=><span class="string"><span class="delimiter">"</span><span class="content">...</span><span class="delimiter">"</span></span>} +<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span> {<span class="symbol">:value</span>=><span class="string"><span class="delimiter">"</span><span class="char">\</span><span class="content">]</span><span class="delimiter">"</span></span>, <span class="symbol">:escaped</span>=><span class="predefined-constant">true</span>} +<span class="line-numbers"><a href="#n11" name="n11">11</a></span> {<span class="symbol">:value</span>=><span class="string"><span class="delimiter">"</span><span class="char">\n</span><span class="delimiter">"</span></span>} +<span class="line-numbers"><a href="#n12" name="n12">12</a></span> {<span class="symbol">:name</span>=><span class="symbol">:section</span>, <span class="symbol">:escape</span>=><span class="predefined-constant">false</span>} +<span class="line-numbers"><a href="#n13" name="n13">13</a></span> {<span class="symbol">:name</span>=><span class="symbol"><span class="symbol">:</span><span class="delimiter">"</span><span class="content">0</span><span class="delimiter">"</span></span>} +<span class="line-numbers"><a href="#n14" name="n14">14</a></span> {<span class="symbol">:value</span>=><span class="string"><span class="delimiter">"</span><span class="char">\n</span><span class="char">\t</span><span class="delimiter">"</span></span>} +<span class="line-numbers"><a href="#n15" name="n15">15</a></span> {<span class="symbol">:value</span>=><span class="string"><span class="delimiter">"</span><span class="char">\n</span><span class="char">\t</span><span class="delimiter">"</span></span>} +<span class="line-numbers"><a href="#n16" name="n16">16</a></span> {<span class="symbol">:value</span>=><span class="string"><span class="delimiter">"</span><span class="char">\n</span><span class="delimiter">"</span></span>} +<span class="line-numbers"><a href="#n17" name="n17">17</a></span> {<span class="symbol">:value</span>=><span class="string"><span class="delimiter">"</span><span class="char">\</span><span class="content">[</span><span class="delimiter">"</span></span>, <span class="symbol">:escaped</span>=><span class="predefined-constant">true</span>} +<span class="line-numbers"><a href="#n18" name="n18">18</a></span> {<span class="symbol">:value</span>=><span class="string"><span class="delimiter">"</span><span class="content">...</span><span class="delimiter">"</span></span>} +<span class="line-numbers"><a href="#n19" name="n19">19</a></span> {<span class="symbol">:value</span>=><span class="string"><span class="delimiter">"</span><span class="char">\</span><span class="content">]</span><span class="delimiter">"</span></span>, <span class="symbol">:escaped</span>=><span class="predefined-constant">true</span>} +<span class="line-numbers"><strong><a href="#n20" name="n20">20</a></strong></span> {<span class="symbol">:value</span>=><span class="string"><span class="delimiter">"</span><span class="char">\n</span><span class="delimiter">"</span></span>} +<span class="line-numbers"><a href="#n21" name="n21">21</a></span> {<span class="symbol">:name</span>=><span class="symbol">:title</span>, <span class="symbol">:escape</span>=><span class="predefined-constant">false</span>} +<span class="line-numbers"><a href="#n22" name="n22">22</a></span> {<span class="symbol">:value</span>=><span class="string"><span class="delimiter">"</span><span class="content">Test Section</span><span class="delimiter">"</span></span>} +<span class="line-numbers"><a href="#n23" name="n23">23</a></span> {<span class="symbol">:name</span>=><span class="symbol">:id</span>, <span class="symbol">:escape</span>=><span class="predefined-constant">false</span>} +<span class="line-numbers"><a href="#n24" name="n24">24</a></span> {<span class="symbol">:value</span>=><span class="string"><span class="delimiter">"</span><span class="content">test</span><span class="delimiter">"</span></span>}</pre></div> +</div> + + <p>This output is produced by calling the <code>inspect</code> method on the AST. Each <a href="http://rubydoc.info/gems/glyph/Glyph/SyntaxNode"><code>Glyph::SyntaxNode</code></a> object in the tree is basically an ordinary Glyph Hash with a parent and 0 or more chidren, so the code snippets above shows how the syntax nodes are nested.</p> + <p>The AST contains information about macro, parameter and attribute names, and escaping, and raw text values (the nodes without a <code>:name</code> key), but nothing more.</p> + <p>When the AST is analyzed, the resulting textual output is the following:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span><span class="tag"><span</span> <span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">fmi</span><span class="delimiter">"</span></span><span class="tag">></span>for more information on something, see ‡‡‡‡‡PLACEHOLDER ¤ 1‡‡‡‡‡ +<span class="line-numbers"><a href="#n2" name="n2">2</a></span><span class="tag"></span></span> +<span class="line-numbers"><a href="#n3" name="n3">3</a></span>\/[...\/] +<span class="line-numbers"><a href="#n4" name="n4">4</a></span><span class="tag"><div</span> <span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">section</span><span class="delimiter">"</span></span><span class="tag">></span> +<span class="line-numbers"><a href="#n5" name="n5">5</a></span><span class="tag"><h2</span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">test</span><span class="delimiter">"</span></span><span class="tag">></span>Test Section<span class="tag"></h2></span> +<span class="line-numbers"><a href="#n6" name="n6">6</a></span>\/[...\/] +<span class="line-numbers"><a href="#n7" name="n7">7</a></span> +<span class="line-numbers"><a href="#n8" name="n8">8</a></span><span class="tag"></div></span></pre></div> +</div> + + <p>This looks almost perfect, except that:</p> + <ul> + <li>There's a nasty placeholder instead of a link: this is due to the fact that when the link is processed, there is no <code>#text</code> anchor in the document, but there may be one afterwards (and there will be).</li> + <li>There are some escaped brackets.</li> + </ul> + <p>Finally, when the document is finalized, placeholders and escape sequences are removed and the final result is the following:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span><span class="tag"><span</span> <span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">fmi</span><span class="delimiter">"</span></span><span class="tag">></span>for more information on something, +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> see <span class="tag"><a</span> <span class="attribute-name">href</span>=<span class="string"><span class="delimiter">"</span><span class="content">#test</span><span class="delimiter">"</span></span><span class="tag">></span>Test Section<span class="tag"></a></span><span class="tag"></span></span> +<span class="line-numbers"><a href="#n3" name="n3">3</a></span>[...] +<span class="line-numbers"><a href="#n4" name="n4">4</a></span><span class="tag"><div</span> <span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">section</span><span class="delimiter">"</span></span><span class="tag">></span> +<span class="line-numbers"><a href="#n5" name="n5">5</a></span><span class="tag"><h2</span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">test</span><span class="delimiter">"</span></span><span class="tag">></span>Test Section<span class="tag"></h2></span> +<span class="line-numbers"><a href="#n6" name="n6">6</a></span>[...] +<span class="line-numbers"><a href="#n7" name="n7">7</a></span> +<span class="line-numbers"><a href="#n8" name="n8">8</a></span><span class="tag"></div></span></pre></div> +</div> + +</section> +<nav class="navigation"><a href="/glyph/book/stats/links.html">← Link Statistics</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/macro_def.html">Defining Custom Macros →</a></nav>
A
contents/glyph/book/extending/interpreting.html
@@ -0,0 +1,91 @@
+----- +title: "Glyph – Interpreting Glyph Code" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/extending/validators.html">← Using Validators</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/layouts.html">Layouts →</a></nav> + + <p>What if you need to evaluate some Glyph code <em>within</em> a macro? Say for example you want to transform a parameter in a link, and you want to make sure that link gets validated exactly like the others, in this case, you can use the <code>interpret</code> method, as follows:</p> + + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>macro <span class="symbol">:fmi</span> <span class="keyword">do</span> +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> topic, href = <span class="instance-variable">@params</span> +<span class="line-numbers"><a href="#n3" name="n3">3</a></span> link = placeholder <span class="keyword">do</span> |document| +<span class="line-numbers"><a href="#n4" name="n4">4</a></span> interpret <span class="string"><span class="delimiter">"</span><span class="content">link[</span><span class="inline"><span class="inline-delimiter">#{</span>href<span class="inline-delimiter">}</span></span><span class="content">]</span><span class="delimiter">"</span></span> +<span class="line-numbers"><a href="#n5" name="n5">5</a></span> <span class="keyword">end</span> +<span class="line-numbers"><a href="#n6" name="n6">6</a></span> <span class="string"><span class="delimiter">%{</span><span class="content"><span class="fmi">for more information on </span><span class="inline"><span class="inline-delimiter">#{</span>topic<span class="inline-delimiter">}</span></span><span class="content">, see </span><span class="inline"><span class="inline-delimiter">#{</span>link<span class="inline-delimiter">}</span></span><span class="content"></span></span><span class="delimiter">}</span></span> +<span class="line-numbers"><a href="#n7" name="n7">7</a></span><span class="keyword">end</span></pre></div> +</div> + + + <p>When the <code>interpret</code> method is called, the following happens:</p> +<ol> + <li>A new Glyph document is created from the <code>String</code> passed to the method.</li> + <li>Document-specific objects (bookmarks, headers, snippet, fragments, placeholders, etc.) are passed from the main document to the new one. Because they are stored in arrays and hashes, they are passed by reference, so for example any new bookmark stored in the new document will also become available in the main document.</li> + <li>Any macro included in the <code>String</code> is evaluated, and the resulting text is returned by the method. Note that this new document does not get finalized: in other words, placeholders will be left as they are, and they’ll eventually be replaced when <em>the main document</em> is finalized.</li> +</ol> + + <section class="section"> +<header><h1 id="h_93" class="toc">Dispatching</h1></header> +<p><a href="/glyph/book/text_editing/macro_composition.html#composition">Macro Composition</a> can be useful to remove nesting, but you can also use it to create your own macro <em>dispatchers</em>. What is a macro dispatcher? The easies way to understand this is by looking at the source code of one of them, the <a href="/glyph/book/macros/macros_core.html#m_s"><code>s</code></a> macro:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span>macro <span class="symbol">:s</span> <span class="keyword">do</span> +<span class="line-numbers"> <a href="#n2" name="n2">2</a></span> dispatch <span class="keyword">do</span> |node| +<span class="line-numbers"> <a href="#n3" name="n3">3</a></span> forbidden = [<span class="symbol">:each</span>, <span class="symbol">:each_line</span>, <span class="symbol">:each_byte</span>, <span class="symbol">:upto</span>, <span class="symbol">:intern</span>, <span class="symbol">:to_sym</span>, <span class="symbol">:to_f</span>] +<span class="line-numbers"> <a href="#n4" name="n4">4</a></span> meth = node[<span class="symbol">:name</span>] +<span class="line-numbers"> <a href="#n5" name="n5">5</a></span> infer_type = lambda <span class="keyword">do</span> |str| +<span class="line-numbers"> <a href="#n6" name="n6">6</a></span> <span class="comment"># Code omitted...</span> +<span class="line-numbers"> <a href="#n7" name="n7">7</a></span> <span class="keyword">end</span> +<span class="line-numbers"> <a href="#n8" name="n8">8</a></span> macro_error <span class="string"><span class="delimiter">"</span><span class="content">Macro 's/</span><span class="inline"><span class="inline-delimiter">#{</span>meth<span class="inline-delimiter">}</span></span><span class="content">' takes at least one parameter</span><span class="delimiter">"</span></span> <span class="keyword">unless</span> node.params.length > <span class="integer">0</span> +<span class="line-numbers"> <a href="#n9" name="n9">9</a></span> macro_error <span class="string"><span class="delimiter">"</span><span class="content">String method '</span><span class="inline"><span class="inline-delimiter">#{</span>meth<span class="inline-delimiter">}</span></span><span class="content">' is not supported</span><span class="delimiter">"</span></span> <span class="keyword">if</span> meth.in?(forbidden) || meth.to_s.match(<span class="regexp"><span class="delimiter">/</span><span class="content">!$</span><span class="delimiter">/</span></span>) +<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span> str = node.param(<span class="integer">0</span>).evaluate(node, <span class="symbol">:params</span> => <span class="predefined-constant">true</span>) +<span class="line-numbers"><a href="#n11" name="n11">11</a></span> <span class="keyword">begin</span> +<span class="line-numbers"><a href="#n12" name="n12">12</a></span> <span class="keyword">if</span> node.param(<span class="integer">1</span>) <span class="keyword">then</span> +<span class="line-numbers"><a href="#n13" name="n13">13</a></span> meth_params = node.params[<span class="integer">1</span>..node.params.length-<span class="integer">1</span>].map <span class="keyword">do</span> |p| +<span class="line-numbers"><a href="#n14" name="n14">14</a></span> infer_type.call(p.evaluate(node, <span class="symbol">:params</span> => <span class="predefined-constant">true</span>)) +<span class="line-numbers"><a href="#n15" name="n15">15</a></span> <span class="keyword">end</span> +<span class="line-numbers"><a href="#n16" name="n16">16</a></span> str.send(meth, *meth_params).to_s +<span class="line-numbers"><a href="#n17" name="n17">17</a></span> <span class="keyword">else</span> +<span class="line-numbers"><a href="#n18" name="n18">18</a></span> str.send(meth).to_s +<span class="line-numbers"><a href="#n19" name="n19">19</a></span> <span class="keyword">end</span> +<span class="line-numbers"><strong><a href="#n20" name="n20">20</a></strong></span> <span class="keyword">rescue</span> <span class="constant">Exception</span> => e +<span class="line-numbers"><a href="#n21" name="n21">21</a></span> <span class="comment"># Code omittted</span> +<span class="line-numbers"><a href="#n22" name="n22">22</a></span> <span class="keyword">end</span> +<span class="line-numbers"><a href="#n23" name="n23">23</a></span> <span class="keyword">end</span> +<span class="line-numbers"><a href="#n24" name="n24">24</a></span><span class="keyword">end</span></pre></div> +</div> + + <p>See the <code>dispatch</code> method at the very beginning? This method takes a block with a <code>node</code> parameter, corresponding to the MacroNode of the macro which is being composed with <code>s</code>. So, for example, if you write <code>s/sub[my string|/my/|your]</code> the node of a macro called <code>sub</code> will be passed to the block. Of course there’s no <code>sub</code> macro defined in Glyph, but it doesn’t matter: its name will be interpreted as the name of a method of the Ruby String class in this case, so no worries.</p> +<p>Got it? Tricky, but damn useful to create your own “dynamic” macros.</p> + +</section> + + <section class="section"> +<header><h1 id="rewriting" class="toc">Defining macros using Glyph</h1></header> +<p>While the <code>interpret</code> method is useful to evaluate Glyph code in a macro while performing other actions (storing a bookmark, checking for the presence of an anchor, etc.), in some cases it may not be necessary. If you simply want your macro to be converted into existing Glyph macro without performing any action excepting parameter substitution, you can just use the <a href="/glyph/book/macros/macros_core.html#m_define_"><code>define:</code></a> macro within your Glyph document</p> + <p>Consider the following macro definition:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>macro <span class="symbol">:issue</span> <span class="keyword">do</span> +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> interpret <span class="string"><span class="delimiter">%{</span><span class="content"></span></span> +<span class="line-numbers"><a href="#n3" name="n3">3</a></span><span class="string"><span class="content"> tr[</span></span> +<span class="line-numbers"><a href="#n4" name="n4">4</a></span><span class="string"><span class="content"> td[/=>[http://github.com/h3rald/glyph/issues/closed#issue/</span><span class="inline"><span class="inline-delimiter">#{</span>param[<span class="integer">0</span>]<span class="inline-delimiter">}</span></span><span class="content">|#</span><span class="inline"><span class="inline-delimiter">#{</span>param(<span class="integer">0</span>)<span class="inline-delimiter">}</span></span><span class="content">]]</span></span> +<span class="line-numbers"><a href="#n5" name="n5">5</a></span><span class="string"><span class="content"> td[txt[</span><span class="inline"><span class="inline-delimiter">#{</span>param(<span class="integer">1</span>)<span class="inline-delimiter">}</span></span><span class="content">]]</span></span> +<span class="line-numbers"><a href="#n6" name="n6">6</a></span><span class="string"><span class="content"> ]</span></span> +<span class="line-numbers"><a href="#n7" name="n7">7</a></span><span class="string"><span class="content"> </span><span class="delimiter">}</span></span> +<span class="line-numbers"><a href="#n8" name="n8">8</a></span><span class="keyword">end</span></pre></div> +</div> + + <p>The <code>issue</code> macro is only rewriting existing Glyph code around the two parameters provided. In this case, it is possible to do exactly the same thing using the <a href="/glyph/book/macros/macros_core.html#m_define_"><code>define:</code></a> macro (aliased by @def:@):</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>define:[issue| +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> tr[ +<span class="line-numbers"><a href="#n3" name="n3">3</a></span> td[/=>[http://github.com/h3rald/glyph/issues/closed#issue/{{0}}|#{{0}}]] +<span class="line-numbers"><a href="#n4" name="n4">4</a></span> td[txt[{{1}}]] +<span class="line-numbers"><a href="#n5" name="n5">5</a></span> ] +<span class="line-numbers"><a href="#n6" name="n6">6</a></span>]</pre></div> +</div> + + <p>Within the <a href="/glyph/book/macros/macros_core.html#m_define_"><code>define:</code></a> macro, it is possible to use a special syntax to call the <code>raw_attr</code> or <code>raw_param</code> methods: <br /> + <code>{{</code><em>parameter_number</em> or <em>attribute_name</em><code>}}</code></p> + +</section> +<nav class="navigation"><a href="/glyph/book/extending/validators.html">← Using Validators</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/layouts.html">Layouts →</a></nav>
A
contents/glyph/book/extending/layouts.html
@@ -0,0 +1,81 @@
+----- +title: "Glyph – Layouts" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/extending/interpreting.html">← Interpreting Glyph Code</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/further_reading.html">Further Reading →</a></nav> +<p>When generating <a href="/glyph/book/text_editing/topics.html#topics">topic</a>-based outputs, Glyph uses <em>layouts</em> to render topics as standalone documents. By default, the following two layout are used:</p> +<ul> + <li><code>topic</code> — used to render standard topics.</li> + <li><code>index</code> — used to render the index page of your document.</li> +</ul> +<p>Layouts are nothing more than “fancy” Glyph macros defined using the Glyph language (i.e. by using <a href="/glyph/book/extending/interpreting.html#rewriting">macro rewriting</a>) within a single <code>.glyph</code> file.</p> +<section class="section"> +<header><h1 id="h_96" class="toc">Topic Layout</h1></header> +<p>The default layout used to render all web topics (the layout used for web5 topics is very similar) is defined as follows:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span>document[ +<span class="line-numbers"> <a href="#n2" name="n2">2</a></span> head[ +<span class="line-numbers"> <a href="#n3" name="n3">3</a></span> style[default.css] +<span class="line-numbers"> <a href="#n4" name="n4">4</a></span> ] +<span class="line-numbers"> <a href="#n5" name="n5">5</a></span> body[ +<span class="line-numbers"> <a href="#n6" name="n6">6</a></span> @class[topic] +<span class="line-numbers"> <a href="#n7" name="n7">7</a></span> section[ +<span class="line-numbers"> <a href="#n8" name="n8">8</a></span> @title[{{title}}] +<span class="line-numbers"> <a href="#n9" name="n9">9</a></span> @id[{{id}}] +<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span> navigation[{{id}}] +<span class="line-numbers"><a href="#n11" name="n11">11</a></span>{{contents}} +<span class="line-numbers"><a href="#n12" name="n12">12</a></span> navigation[{{id}}] +<span class="line-numbers"><a href="#n13" name="n13">13</a></span> ] +<span class="line-numbers"><a href="#n14" name="n14">14</a></span> ] +<span class="line-numbers"><a href="#n15" name="n15">15</a></span>]</pre></div> +</div> + + <p>Note that it takes the following attributes, passed automatically by Glyph when processing each topic:</p> +<ul> + <li><code>title</code> — the title of the topic.</li> + <li><code>id</code> — the ID of the topic.</li> + <li><code>contents</code> — the body of the topic.</li> +</ul> + +</section> +<section class="section"> +<header><h1 id="index_layout" class="toc">Index Layout</h1></header> +<p>The default layout used to render the web index page (the layout used for the web5 index is very similar) is defined as follows:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span>document[ +<span class="line-numbers"> <a href="#n2" name="n2">2</a></span> head[ +<span class="line-numbers"> <a href="#n3" name="n3">3</a></span> style[default.css] +<span class="line-numbers"> <a href="#n4" name="n4">4</a></span> ] +<span class="line-numbers"> <a href="#n5" name="n5">5</a></span> body[ +<span class="line-numbers"> <a href="#n6" name="n6">6</a></span> @class[topic] +<span class="line-numbers"> <a href="#n7" name="n7">7</a></span> halftitlepage[ +<span class="line-numbers"> <a href="#n8" name="n8">8</a></span> title[] +<span class="line-numbers"> <a href="#n9" name="n9">9</a></span> subtitle[] +<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span> author[] +<span class="line-numbers"><a href="#n11" name="n11">11</a></span> ] +<span class="line-numbers"><a href="#n12" name="n12">12</a></span> frontmatter[ +<span class="line-numbers"><a href="#n13" name="n13">13</a></span> toc[] +<span class="line-numbers"><a href="#n14" name="n14">14</a></span> ] +<span class="line-numbers"><a href="#n15" name="n15">15</a></span> ] +<span class="line-numbers"><a href="#n16" name="n16">16</a></span>]</pre></div> +</div> + + <p>Index layouts do not take any attribute or parameter (basically because they are used to produce only one page).</p> + +</section> +<section class="section"> +<header><h1 id="h_98" class="toc">Creating a Custom Layout</h1></header> +<p>To create a custom layout, proceed as follows:</p> +<ul> + <li>Create a <code>.glyph</code> file in the <code>lib/layouts</code> directory, within your project, e.g. <code>mytopic.glyph</code></li> + <li>Add the layout code, making sure (for topic layouts) that all the attributes (<code>title</code>, <code>id</code>, <code>contents</code>) are specified correctly.</li> + <li>Set the <code>output.*.layouts.topic</code> setting to the name of the new layout (<code>mytopic</code>).</li> +</ul> + <aside class="tip"> +<span class="note-title">Tip</span>You can override which layout to use on a specific topic by specifying it in a <code>@layout</code> attribute. + +</aside> + +</section> + +<nav class="navigation"><a href="/glyph/book/extending/interpreting.html">← Interpreting Glyph Code</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/further_reading.html">Further Reading →</a></nav>
A
contents/glyph/book/extending/macro_def.html
@@ -0,0 +1,115 @@
+----- +title: "Glyph – Defining Custom Macros" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/extending/internals.html">← A quick look at Glyph's internals</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/params_attrs.html">Parameters and Attributes →</a></nav> + <p>Glyph was created wih extensibility in mind. You can freely extend Glyph Language by creating or overriding macros, to do whatever you like. Macro definitions are written in pure Ruby code and placed in <code>.rb</code> files within the <code>lib/macros/</code> folder of your project.</p> +<aside class="box"> +<div class="box-title">Alternative Ways to Define Macros</div> +<p>You can also define macros:</p> +<ul> + <li>inside your document, using the <a href="/glyph/book/macros/macros_core.html#m_macro_"><code>macro:</code></a> macro.</li> + <li>Using the <a href="/glyph/book/macros/macros_core.html#m_include"><code>include</code></a> macro specifying the path to an <code>.rb</code> file containing macro definitions stored in the <code>lib/</code> directory (useful especially when <a href="/glyph/book/compiling/lite_mode.html#lite_mode">compiling single Glyph files</a>).</li> +</ul> +</aside> +<p>This is the source code of a fairly simple macro used to format a note:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>macro <span class="symbol">:note</span> <span class="keyword">do</span> +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> <span class="string"><span class="delimiter">%{</span><span class="content"><div class="</span><span class="inline"><span class="inline-delimiter">#{</span><span class="instance-variable">@name</span><span class="inline-delimiter">}</span></span><span class="content">"><span class="note-title"></span><span class="inline"><span class="inline-delimiter">#{</span><span class="instance-variable">@name</span>.to_s.capitalize<span class="inline-delimiter">}</span></span><span class="content"></span></span></span> +<span class="line-numbers"><a href="#n3" name="n3">3</a></span><span class="string"><span class="content"> </span><span class="inline"><span class="inline-delimiter">#{</span><span class="instance-variable">@value</span><span class="inline-delimiter">}</span></span><span class="content"></span></span> +<span class="line-numbers"><a href="#n4" name="n4">4</a></span><span class="string"><span class="content"></span></span> +<span class="line-numbers"><a href="#n5" name="n5">5</a></span><span class="string"><span class="content"> </div></span><span class="delimiter">}</span></span> +<span class="line-numbers"><a href="#n6" name="n6">6</a></span><span class="keyword">end</span></pre></div> +</div> + + <p>The <code>macro</code> method takes a single <code>Symbol</code> or <code>String</code> parameter, corresponding to the name of the macro. In this case, the entire block (or <em>body</em> of the macro) is a <code>String</code> corresponding to what we want the macro to evaluate to: a <code><div></code> tag containing a note.</p> +<p>The body of the macro is evaluated in the context of the <a href="http://rubydoc.info/gems/glyph/Glyph/Macro"><code>Glyph::Macro</code></a> class, therefore its instance variables (like <code>@name</code> or <code>@value</code>) can be used directly.</p> +<aside class="box"> +<div class="box-title">Why using <code>@name</code> instead of just “note”?</div> +<p>For the <code>note</code> macro, it absolutely makes no difference. However, by using <code>@name</code> it is possible to re-use the same code for the <code>tip</code>, <code>important</code> and <code>caution</code> macros as well, which are in fact only aliases of the <code>note</code> macro.</p> +</aside> +<p>The following table lists all the instance variables that can be used inside macros:</p> + <table> + <tr> + <th>Variable</th> + <th>Description</th> + </tr> + <tr> + <td> +<code>@node</code> +</td> + <td> + <p>A <a href="http://rubydoc.info/gems/glyph/Glyph/MacroNode"><code>Glyph::MacroNode</code></a> containing information about the macro. Useful for accessing parent and child macros, and the current <a href="http://rubydoc.info/gems/glyph/Glyph/Document"><code>Glyph::Document</code></a>. Normally, instances of the <code>MacroNode</code> class contain the following keys:</p> +<ul> + <li><code>:name</code>, the name of the macro.</li> + <li><code>:source</code>, a <code>String</code> identifying the source of the macro (a file, a snippet, etc.)</li> + <li><code>:value</code>, the value of the macro (populated after the document has been parsed and analyzed).</li> + <li><code>:escape</code>, whether the macro is a <a href="/glyph/book/text_editing/esc_quot.html#esc_quot">quoting macro</a> or not.</li> + <li><code>:document</code>, the instance of <code>Document</code> the macro is contained in (populated after the document has been parsed and analyzed).</li> +</ul> +<p>Note that the first two keys can also be accessed via instance variables.</p> + </td> + </tr> + <tr> + <td> +<code>@name</code> +</td> + <td>The name of the macro.</td> + </tr> + <tr> + <td> +<code>@source_name</code> +</td> + <td>A <code>String</code> identifying the source of the macro (a file, a snippet, etc.).</td> + </tr> + <tr> + <td> +<code>@source_topic</code> +</td> + <td>A <code>String</code> identifying the source topic of the macro.</td> + </tr> + <tr> + <td> +<code>@source_file</code> +</td> + <td>A <code>String</code> identifying the source file of the macro.</td> + </tr> + </table> + <section class="section"> +<header><h1 id="h_85" class="toc">Representations</h1></header> +<p>There’s a small problem with the code used to define the <code>note</code> macro in the previous section: what if I want to format notes using HTML5 instead of <span class="caps">HTML</span>, or another output format?</p> +<p>Glyph supports different output formats, therefore macros must be format-independent! In fact, this is the actual source of the <code>note</code> macro:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>macro <span class="symbol">:note</span> <span class="keyword">do</span> +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> <span class="instance-variable">@data</span>[<span class="symbol">:name</span>] = <span class="instance-variable">@name</span> +<span class="line-numbers"><a href="#n3" name="n3">3</a></span> <span class="instance-variable">@data</span>[<span class="symbol">:text</span>] = value +<span class="line-numbers"><a href="#n4" name="n4">4</a></span> render +<span class="line-numbers"><a href="#n5" name="n5">5</a></span><span class="keyword">end</span></pre></div> +</div> + + <p>The <span class="caps">HTML</span> representation of the note macro is defined in the <code>macros/reps/html.rb</code> file as follows:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>rep <span class="symbol">:note</span> <span class="keyword">do</span> |data| +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> css_class = data[<span class="symbol">:name</span>].to_s.match(<span class="regexp"><span class="delimiter">/</span><span class="content">[a-z0-9_-]</span><span class="delimiter">/</span><span class="modifier">i</span></span>) ? data[<span class="symbol">:name</span>] : <span class="string"><span class="delimiter">"</span><span class="content">note</span><span class="delimiter">"</span></span> +<span class="line-numbers"><a href="#n3" name="n3">3</a></span> <span class="string"><span class="delimiter">%{</span><span class="content"><div class="</span><span class="inline"><span class="inline-delimiter">#{</span>css_class<span class="inline-delimiter">}</span></span><span class="content">"></span></span> +<span class="line-numbers"><a href="#n4" name="n4">4</a></span><span class="string"><span class="content"><span class="note-title"></span><span class="inline"><span class="inline-delimiter">#{</span>data[<span class="symbol">:name</span>].to_s.capitalize<span class="inline-delimiter">}</span></span><span class="content"></span></span><span class="inline"><span class="inline-delimiter">#{</span>data[<span class="symbol">:text</span>]<span class="inline-delimiter">}</span></span><span class="content"></span></span> +<span class="line-numbers"><a href="#n5" name="n5">5</a></span><span class="string"><span class="content"></span></span> +<span class="line-numbers"><a href="#n6" name="n6">6</a></span><span class="string"><span class="content"></div></span><span class="delimiter">}</span></span> +<span class="line-numbers"><a href="#n7" name="n7">7</a></span><span class="keyword">end</span></pre></div> +</div> + + <p>The HTML5 representation of the note macro, on the other hand, is defined in the <code>macros/reps/html5.rb</code> file as follows:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>rep <span class="symbol">:note</span> <span class="keyword">do</span> |data| +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> css_class = data[<span class="symbol">:name</span>].to_s.match(<span class="regexp"><span class="delimiter">/</span><span class="content">[a-z0-9_-]</span><span class="delimiter">/</span><span class="modifier">i</span></span>) ? data[<span class="symbol">:name</span>] : <span class="string"><span class="delimiter">"</span><span class="content">note</span><span class="delimiter">"</span></span> +<span class="line-numbers"><a href="#n3" name="n3">3</a></span> <span class="string"><span class="delimiter">%{</span><span class="content"><aside class="</span><span class="inline"><span class="inline-delimiter">#{</span>css_class<span class="inline-delimiter">}</span></span><span class="content">"></span></span> +<span class="line-numbers"><a href="#n4" name="n4">4</a></span><span class="string"><span class="content"><span class="note-title"></span><span class="inline"><span class="inline-delimiter">#{</span>data[<span class="symbol">:name</span>].to_s.capitalize<span class="inline-delimiter">}</span></span><span class="content"></span></span><span class="inline"><span class="inline-delimiter">#{</span>data[<span class="symbol">:text</span>]<span class="inline-delimiter">}</span></span><span class="content"></span></span> +<span class="line-numbers"><a href="#n5" name="n5">5</a></span><span class="string"><span class="content"></span></span> +<span class="line-numbers"><a href="#n6" name="n6">6</a></span><span class="string"><span class="content"></aside></span><span class="delimiter">}</span></span> +<span class="line-numbers"><a href="#n7" name="n7">7</a></span><span class="keyword">end</span></pre></div> +</div> + +Note the different tags used to render the note. + +</section> +<nav class="navigation"><a href="/glyph/book/extending/internals.html">← A quick look at Glyph's internals</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/params_attrs.html">Parameters and Attributes →</a></nav>
A
contents/glyph/book/extending/output_format.html
@@ -0,0 +1,77 @@
+----- +title: "Glyph – Custom Output Formats" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/extending/task.html">← Defining Custom Tasks</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/command.html">Defining Custom Commands →</a></nav> +<p>As shown in <a href="/glyph/book/extending/commands_tasks.html#cmd_tasks_arch">How Commands and Tasks work</a>, the <a href="/glyph/book/ref_commands.html#c_compile"><code>compile</code></a> command command calls specific tasks defined in the <code>generate:</code> Rake namespace to generate output files in a particular format.</p> +<p>More specifically, when a <code>--format</code> option is specified, the command looks for a task with the same name within the <code>generate:</code> namespace. This makes adding new output formats to Glyph a fairly easy task, without the need to specify custom commands or similar.</p> +<p>The following sections explain how the <code>h3rald</code> output format was created to integrate this book into the <a href="http://www.h3rald.com">H3RALD.com</a> website.</p> +<section class="section"> +<header><h1 id="h_105" class="toc">Output Configuration</h1></header> +<p>The first step required to add a new output format to Glyph is extending Glyph’s configuration by adding the appropriate output hash, as follows:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span><span class="symbol">:output</span>: +<span class="line-numbers"> <a href="#n2" name="n2">2</a></span> <span class="symbol">:h3rald</span>: +<span class="line-numbers"> <a href="#n3" name="n3">3</a></span> <span class="symbol">:multifile</span>: <span class="error">true</span> +<span class="line-numbers"> <a href="#n4" name="n4">4</a></span> <span class="symbol">:extension</span>: <span class="error">'.html'</span> +<span class="line-numbers"> <a href="#n5" name="n5">5</a></span> <span class="symbol">:filter_target</span>: <span class="error">'html'</span> +<span class="line-numbers"> <a href="#n6" name="n6">6</a></span> <span class="symbol">:base</span>: <span class="error">'/glyph/book/'</span> +<span class="line-numbers"> <a href="#n7" name="n7">7</a></span> <span class="symbol">:macro_dirs</span>: [<span class="error">'html', 'html5']</span> +<span class="line-numbers"> <a href="#n8" name="n8">8</a></span> <span class="symbol">:layout_dirs</span>: [<span class="error">'web5']</span> +<span class="line-numbers"> <a href="#n9" name="n9">9</a></span> <span class="symbol">:layouts</span>: +<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span> <span class="symbol">:topic</span>: <span class="error">bookpage</span> +<span class="line-numbers"><a href="#n11" name="n11">11</a></span> <span class="symbol">:index</span>: <span class="error">bookindex</span></pre></div> +</div> + + <p>In particular, the following keys are mandatory:</p> +<ul> + <li>multifile</li> + <li>extension</li> + <li>filter_target</li> + <li>base</li> + <li>macro_dirs</li> + <li>layout_dirs</li> +</ul> + +</section> +<section class="section"> +<header><h1 id="h_106" class="toc">Creating a 'generate:h3rald' task</h1></header> +<p>The next (and final) step involves creating a custom <code>h3rald</code> task within the <code>generate:</code> namespace. This task can be placed in any <code>.rake</code> file within the <code>lib/tasks</code> directory:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span>namespace <span class="symbol">:generate</span> <span class="keyword">do</span> +<span class="line-numbers"> <a href="#n2" name="n2">2</a></span> desc <span class="string"><span class="delimiter">"</span><span class="content">Create output for h3rald.com integration</span><span class="delimiter">"</span></span> +<span class="line-numbers"> <a href="#n3" name="n3">3</a></span> task <span class="symbol">:h3rald</span> => [<span class="symbol">:web5</span>] <span class="keyword">do</span> +<span class="line-numbers"> <a href="#n4" name="n4">4</a></span> dir = <span class="constant">Glyph</span>::<span class="constant">PROJECT</span>/<span class="string"><span class="delimiter">'</span><span class="content">output/h3rald</span><span class="delimiter">'</span></span> +<span class="line-numbers"> <a href="#n5" name="n5">5</a></span> (dir/<span class="string"><span class="delimiter">"</span><span class="content">glyph/book</span><span class="delimiter">"</span></span>).mkpath +<span class="line-numbers"> <a href="#n6" name="n6">6</a></span> <span class="comment"># Copy files in subdir</span> +<span class="line-numbers"> <a href="#n7" name="n7">7</a></span> (dir).find <span class="keyword">do</span> |i| +<span class="line-numbers"> <a href="#n8" name="n8">8</a></span> <span class="keyword">if</span> i.file? <span class="keyword">then</span> +<span class="line-numbers"> <a href="#n9" name="n9">9</a></span> <span class="keyword">next</span> <span class="keyword">if</span> i.to_s.match(<span class="constant">Regexp</span>.escape(dir/<span class="string"><span class="delimiter">'</span><span class="content">glyph</span><span class="delimiter">'</span></span>)) +<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span> dest = dir/<span class="string"><span class="delimiter">"</span><span class="content">glyph/book/</span><span class="inline"><span class="inline-delimiter">#{</span>i.relative_path_from(<span class="constant">Glyph</span>::<span class="constant">PROJECT</span>/dir)<span class="inline-delimiter">}</span></span><span class="delimiter">"</span></span> +<span class="line-numbers"><a href="#n11" name="n11">11</a></span> src = i.to_s +<span class="line-numbers"><a href="#n12" name="n12">12</a></span> <span class="constant">Pathname</span>.new(dest).parent.mkpath +<span class="line-numbers"><a href="#n13" name="n13">13</a></span> file_copy src, dest +<span class="line-numbers"><a href="#n14" name="n14">14</a></span> <span class="keyword">end</span> +<span class="line-numbers"><a href="#n15" name="n15">15</a></span> <span class="keyword">end</span> +<span class="line-numbers"><a href="#n16" name="n16">16</a></span> <span class="comment"># Remove files from output dir</span> +<span class="line-numbers"><a href="#n17" name="n17">17</a></span> dir.children.each <span class="keyword">do</span> |c| +<span class="line-numbers"><a href="#n18" name="n18">18</a></span> <span class="keyword">unless</span> c == dir/<span class="string"><span class="delimiter">'</span><span class="content">glyph</span><span class="delimiter">'</span></span> <span class="keyword">then</span> +<span class="line-numbers"><a href="#n19" name="n19">19</a></span> c.directory? ? c.rmtree : c.unlink +<span class="line-numbers"><strong><a href="#n20" name="n20">20</a></strong></span> <span class="keyword">end</span> +<span class="line-numbers"><a href="#n21" name="n21">21</a></span> <span class="keyword">end</span> +<span class="line-numbers"><a href="#n22" name="n22">22</a></span> (dir/<span class="string"><span class="delimiter">'</span><span class="content">glyph/book/images/glyph/glyph.eps</span><span class="delimiter">'</span></span>).unlink +<span class="line-numbers"><a href="#n23" name="n23">23</a></span> (dir/<span class="string"><span class="delimiter">'</span><span class="content">glyph/book/images/glyph/glyph.svg</span><span class="delimiter">'</span></span>).unlink +<span class="line-numbers"><a href="#n24" name="n24">24</a></span> <span class="comment"># Create project page</span> +<span class="line-numbers"><a href="#n25" name="n25">25</a></span> project = <span class="constant">Glyph</span>.filter <span class="string"><span class="delimiter">%{</span><span class="content">layout:project[</span></span> +<span class="line-numbers"><a href="#n26" name="n26">26</a></span><span class="string"><span class="content"> @contents[</span><span class="inline"><span class="inline-delimiter">#{</span>file_load(<span class="constant">Glyph</span>::<span class="constant">PROJECT</span>/<span class="string"><span class="delimiter">'</span><span class="content">text/introduction.glyph</span><span class="delimiter">'</span></span>)<span class="inline-delimiter">}</span></span><span class="content">]</span></span> +<span class="line-numbers"><a href="#n27" name="n27">27</a></span><span class="string"><span class="content"> ]</span><span class="delimiter">}</span></span> +<span class="line-numbers"><a href="#n28" name="n28">28</a></span> file_write dir/<span class="string"><span class="delimiter">"</span><span class="content">glyph.textile</span><span class="delimiter">"</span></span>, project +<span class="line-numbers"><a href="#n29" name="n29">29</a></span> <span class="keyword">end</span> +<span class="line-numbers"><strong><a href="#n30" name="n30">30</a></strong></span><span class="keyword">end</span></pre></div> +</div> + + <p>In this case, this task does not actually renders files in a different format, it just moves the files generated by the @generate:web5@ task in different subdirectories.</p> + <p>Additionally, it also generates the <a href="http://www.h3rald.com/glyph/">Glyph project page</a> from the book's introduction (note the usage of a raw custom layout macro).</p> + +</section> +<nav class="navigation"><a href="/glyph/book/extending/task.html">← Defining Custom Tasks</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/command.html">Defining Custom Commands →</a></nav>
A
contents/glyph/book/extending/params_attrs.html
@@ -0,0 +1,74 @@
+----- +title: "Glyph – Parameters and Attributes" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/extending/macro_def.html">← Defining Custom Macros</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/bookmarks_headers.html">Bookmarks and Headers →</a></nav> + <p>Perhaps the most common things to do in a macro definition is accessing parameters and attributes. When doing so, it is important to consider whether we want to retrieve the <em>raw value</em> of and attribute or parameter or its <em>expanded value</em>. The difference between the two will become clearer in the following sections and also in the <a href="/glyph/book/extending/interpreting.html#interpreting">Interpreting Glyph Code</a> section.</p> + <section class="section"> +<header><h1 id="expanded_values" class="toc">Accessing Expanded Values</h1></header> +<p>Normally, you just want to get the value of an attribute or parameter and use it in the macro. This means, in other words, its <em>expanded</em> value, i.e. the value resulting from the expansion of the macros (if any) within the attribute or parameter.</p> + <p>To access expanded values, use the following methods:</p> +<ul> + <li><code>parameter</code> (or <code>param</code>): Returns the expanded value of the parameter specified by number. Other parameters are not expanded.</li> + <li><code>value</code>: Returns the expanded value of the first parameter (i.e. like <code>parameter(0)</code>).</li> + <li><code>attribute</code> (or <code>attr</code>): Returns the expanded value of the attribute specified by name. Other attributes are not expanded.</li> + <li><code>parameters</code> (or <code>params</code>): Returns an array of expanded parameters.</li> + <li><code>attributes</code> (or <code>attrs</code>): Returns a hash of expanded attributes.</li> +</ul> + +</section> + <section class="section"> +<header><h1 id="h_88" class="toc">Accessing Raw Values</h1></header> +<p>While accessing expanded values is simple and immediate, in some cases it may not produce the desired results. Consider the following macro definition:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span>macro <span class="symbol">:nest_section</span> <span class="keyword">do</span> +<span class="line-numbers"> <a href="#n2" name="n2">2</a></span> interpret <span class="string"><span class="delimiter">%{</span><span class="content">section[</span></span> +<span class="line-numbers"> <a href="#n3" name="n3">3</a></span><span class="string"><span class="content"> @title[A]</span></span> +<span class="line-numbers"> <a href="#n4" name="n4">4</a></span><span class="string"><span class="content"> section[</span></span> +<span class="line-numbers"> <a href="#n5" name="n5">5</a></span><span class="string"><span class="content"> @title[B]</span></span> +<span class="line-numbers"> <a href="#n6" name="n6">6</a></span><span class="string"><span class="content"> </span><span class="inline"><span class="inline-delimiter">#{</span>value<span class="inline-delimiter">}</span></span><span class="content"></span></span> +<span class="line-numbers"> <a href="#n7" name="n7">7</a></span><span class="string"><span class="content"> ]</span></span> +<span class="line-numbers"> <a href="#n8" name="n8">8</a></span><span class="string"><span class="content"> ]</span><span class="delimiter">}</span></span> +<span class="line-numbers"> <a href="#n9" name="n9">9</a></span><span class="keyword">end</span></pre></div> +</div> + + <p>And suppose to use it as follows:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>nest_section[ +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> section[ +<span class="line-numbers"><a href="#n3" name="n3">3</a></span> <span class="instance-variable">@title</span>[<span class="constant">Inner</span> <span class="constant">Section</span>] +<span class="line-numbers"><a href="#n4" name="n4">4</a></span> ... +<span class="line-numbers"><a href="#n5" name="n5">5</a></span> ] +<span class="line-numbers"><a href="#n6" name="n6">6</a></span>]</pre></div> +</div> + + <p>It produces the following HTML code:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span><span class="tag"><div</span> <span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">section</span><span class="delimiter">"</span></span><span class="tag">></span> +<span class="line-numbers"> <a href="#n2" name="n2">2</a></span> <span class="tag"><h2</span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">h_2</span><span class="delimiter">"</span></span><span class="tag">></span>A<span class="tag"></h2></span> +<span class="line-numbers"> <a href="#n3" name="n3">3</a></span> <span class="tag"><div</span> <span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">section</span><span class="delimiter">"</span></span><span class="tag">></span> +<span class="line-numbers"> <a href="#n4" name="n4">4</a></span> <span class="tag"><h3</span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">h_3</span><span class="delimiter">"</span></span><span class="tag">></span>B<span class="tag"></h3></span> +<span class="line-numbers"> <a href="#n5" name="n5">5</a></span> <span class="tag"><div</span> <span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">section</span><span class="delimiter">"</span></span><span class="tag">></span> +<span class="line-numbers"> <a href="#n6" name="n6">6</a></span> <span class="tag"><h2</span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">h_1</span><span class="delimiter">"</span></span><span class="tag">></span>Inner Section<span class="tag"></h2></span> +<span class="line-numbers"> <a href="#n7" name="n7">7</a></span>... +<span class="line-numbers"> <a href="#n8" name="n8">8</a></span> <span class="tag"></div></span> +<span class="line-numbers"> <a href="#n9" name="n9">9</a></span> <span class="tag"></div></span> +<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span><span class="tag"></div></span></pre></div> +</div> + + <p>Everything is fine <em>except</em> for the header level: the heading "Inner Section" is of level 2, but it should be level 4!</p> + <p>This happens because the inner section is evaluated <em>before</em> the <code>nest_section</code> macro: after all, we ask for it ourselves when we call the <code>value</code> method inside the macro definition. When the value is expanded, there are no outer sections <em>yet</em>.</p> + <p>To avoid this unwanted behavior, we can use the <code>raw_value</code> method instead, that returns the first parameter converted back to a Glyph code string.</p> + <aside class="tip"> +<span class="note-title">Tip</span>To be on the safe side, always use <code>raw_*</code> methods when interpreting. + +</aside> + <p>To access raw values, use the following methods:</p> +<ul> + <li><code>raw_parameter</code> (or <code>raw_param</code>): Returns the raw parameter value of the parameter specified by number.</li> + <li><code>raw_value</code>: Returns the first raw parameter value (i.e. like <code>raw_parameter(0)</code>).</li> + <li><code>raw_attribute</code> (or <code>raw_attr</code>): Returns the attribute value of the attribute specified by name.</li> +</ul> + +</section> +<nav class="navigation"><a href="/glyph/book/extending/macro_def.html">← Defining Custom Macros</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/bookmarks_headers.html">Bookmarks and Headers →</a></nav>
A
contents/glyph/book/extending/placeholders.html
@@ -0,0 +1,43 @@
+----- +title: "Glyph – Using Placeholders" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/extending/bookmarks_headers.html">← Bookmarks and Headers</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/validators.html">Using Validators →</a></nav> + <p>Sometimes you may need to access some data that will not be available until the entire document has been fully parsed and analyzed. For example, in order to be able to validate internal links, it is necessary to know in advance if the bookmark ID referenced in the link exists or not, either before (that’s easy) or even <em>after</em> the link.</p> +<p>Here’s the source code of the <a href="/glyph/book/macros/macros_inline.html#m_link"><code>link</code></a> macro:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span>macro <span class="symbol">:link</span> <span class="keyword">do</span> +<span class="line-numbers"> <a href="#n2" name="n2">2</a></span> min_parameters <span class="integer">1</span> +<span class="line-numbers"> <a href="#n3" name="n3">3</a></span> max_parameters <span class="integer">2</span> +<span class="line-numbers"> <a href="#n4" name="n4">4</a></span> target = param <span class="integer">0</span> +<span class="line-numbers"> <a href="#n5" name="n5">5</a></span> title = param <span class="integer">1</span> +<span class="line-numbers"> <a href="#n6" name="n6">6</a></span> <span class="keyword">if</span> target.match <span class="regexp"><span class="delimiter">/</span><span class="content">^#</span><span class="delimiter">/</span></span> <span class="keyword">then</span> +<span class="line-numbers"> <a href="#n7" name="n7">7</a></span> <span class="instance-variable">@node</span>[<span class="symbol">:document</span>].links << target +<span class="line-numbers"> <a href="#n8" name="n8">8</a></span> anchor = target.gsub <span class="regexp"><span class="delimiter">/</span><span class="content">^#</span><span class="delimiter">/</span></span>, <span class="string"><span class="delimiter">'</span><span class="delimiter">'</span></span> +<span class="line-numbers"> <a href="#n9" name="n9">9</a></span> bmk = bookmark? anchor +<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span> <span class="keyword">if</span> !bmk <span class="keyword">then</span> +<span class="line-numbers"><a href="#n11" name="n11">11</a></span> placeholder <span class="keyword">do</span> |document| +<span class="line-numbers"><a href="#n12" name="n12">12</a></span> bmk = document.bookmark?(anchor) +<span class="line-numbers"><a href="#n13" name="n13">13</a></span> macro_error <span class="string"><span class="delimiter">"</span><span class="content">Bookmark '</span><span class="inline"><span class="inline-delimiter">#{</span>anchor<span class="inline-delimiter">}</span></span><span class="content">' does not exist</span><span class="delimiter">"</span></span> <span class="keyword">unless</span> bmk +<span class="line-numbers"><a href="#n14" name="n14">14</a></span> bmk_title = title +<span class="line-numbers"><a href="#n15" name="n15">15</a></span> bmk_title = bmk.title <span class="keyword">if</span> bmk_title.blank? +<span class="line-numbers"><a href="#n16" name="n16">16</a></span> <span class="instance-variable">@data</span>[<span class="symbol">:target</span>] = bmk.link(<span class="instance-variable">@source_file</span>) +<span class="line-numbers"><a href="#n17" name="n17">17</a></span> <span class="instance-variable">@data</span>[<span class="symbol">:title</span>] = bmk_title +<span class="line-numbers"><a href="#n18" name="n18">18</a></span> render +<span class="line-numbers"><a href="#n19" name="n19">19</a></span> <span class="keyword">end</span> +<span class="line-numbers"><strong><a href="#n20" name="n20">20</a></strong></span> <span class="keyword">else</span> +<span class="line-numbers"><a href="#n21" name="n21">21</a></span> bmk_title = title +<span class="line-numbers"><a href="#n22" name="n22">22</a></span> bmk_title = bmk.title <span class="keyword">if</span> bmk_title.blank? +<span class="line-numbers"><a href="#n23" name="n23">23</a></span> <span class="instance-variable">@data</span>[<span class="symbol">:target</span>] = bmk.link(<span class="instance-variable">@source_file</span>) +<span class="line-numbers"><a href="#n24" name="n24">24</a></span> <span class="instance-variable">@data</span>[<span class="symbol">:title</span>] = bmk_title +<span class="line-numbers"><a href="#n25" name="n25">25</a></span> render +<span class="line-numbers"><a href="#n26" name="n26">26</a></span> <span class="keyword">end</span> +<span class="line-numbers"><a href="#n27" name="n27">27</a></span> <span class="keyword">else</span> +<span class="line-numbers"><a href="#n28" name="n28">28</a></span> <span class="comment"># Code omitted...</span> +<span class="line-numbers"><a href="#n29" name="n29">29</a></span> <span class="keyword">end</span> +<span class="line-numbers"><strong><a href="#n30" name="n30">30</a></strong></span><span class="keyword">end</span></pre></div> +</div> + + <p>If there’s already a bookmark stored in the current document, then it is possible to retrieve its title and use it as link text. Otherwise, it is necessary to wait until the entire document has been fully processed and then check if the bookmark exists. To do so, use the <code>placeholder</code> method. When called, this method returns an unique placeholder, which is then substituted with the value of the block, right before the document is finalized.</p> +<p>Within the <code>placeholder</code> block, the <code>document</code> parameter is, by all means, the fully analyzed document.</p> +<nav class="navigation"><a href="/glyph/book/extending/bookmarks_headers.html">← Bookmarks and Headers</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/validators.html">Using Validators →</a></nav>
A
contents/glyph/book/extending/task.html
@@ -0,0 +1,46 @@
+----- +title: "Glyph – Defining Custom Tasks" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/extending/commands_tasks.html">← Defining Custom Commands and Tasks</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/output_format.html">Custom Output Formats →</a></nav> +<p>Glyph relies on <a href="http://rake.rubyforge.org/">Rake</a> to perform most of its core operations. Typically, Rake tasks are used do define the high level logic that is used by Glyph commands to, for example, compile a project or load configuration files.</p> +<p>Furthermore, Rake provides an easy mechanism to create dependencies among tasks: for example, to make sure that Glyph’s configuration files are loaded before everything else happens.</p> +<section class="section"> +<header><h1 id="custom_generate_task" class="toc">Creating a 'custom:generate' task</h1></header> +<p>A custom task has been defined for the Glyph project used to produce this document. This custom task is used to compile a few of the documents files into standalone files, deployed in Glyph’s root folder:</p> +<ul> + <li><code>book/text/introduction.glyph</code> → <code>README.textile</code></li> + <li><code>book/text/changelog.glyph</code> → <code>CHANGELOG.textile</code></li> + <li><code>book/text/license.glyph</code> → <code>LICENSE.textile</code></li> + <li><code>book/text/acknowledgement.glyph</code> → <code>AUTHORS.textile</code></li> +</ul> +<p>First of all, create a <code>lib/tasks</code> folder in your project directory. Then, create a <code>.rake</code> file within it, e.g. <code>tasks.rake</code>.</p> +<p>Finally, here’s the source of the task:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span>namespace <span class="symbol">:custom</span> <span class="keyword">do</span> +<span class="line-numbers"> <a href="#n2" name="n2">2</a></span> task <span class="symbol">:generate</span>, [<span class="symbol">:file</span>] <span class="keyword">do</span> |t, args| +<span class="line-numbers"> <a href="#n3" name="n3">3</a></span> generate = lambda <span class="keyword">do</span> |source, destination| +<span class="line-numbers"> <a href="#n4" name="n4">4</a></span> <span class="constant">Glyph</span>.info <span class="string"><span class="delimiter">"</span><span class="content">Generating </span><span class="inline"><span class="inline-delimiter">#{</span>destination<span class="inline-delimiter">}</span></span><span class="content">...</span><span class="delimiter">"</span></span> +<span class="line-numbers"> <a href="#n5" name="n5">5</a></span> <span class="constant">Glyph</span>.compile <span class="constant">Glyph</span>::<span class="constant">PROJECT</span>/<span class="string"><span class="delimiter">"</span><span class="content">text/</span><span class="inline"><span class="inline-delimiter">#{</span>source<span class="inline-delimiter">}</span></span><span class="content">.glyph</span><span class="delimiter">"</span></span>, +<span class="line-numbers"> <a href="#n6" name="n6">6</a></span> <span class="constant">Glyph</span>::<span class="constant">PROJECT</span>/<span class="string"><span class="delimiter">"</span><span class="content">../</span><span class="inline"><span class="inline-delimiter">#{</span>destination<span class="inline-delimiter">}</span></span><span class="content">.textile</span><span class="delimiter">"</span></span> +<span class="line-numbers"> <a href="#n7" name="n7">7</a></span> <span class="keyword">end</span> +<span class="line-numbers"> <a href="#n8" name="n8">8</a></span> files = { +<span class="line-numbers"> <a href="#n9" name="n9">9</a></span> <span class="symbol">:AUTHORS</span> => <span class="symbol">:acknowledgements</span>, +<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span> <span class="symbol">:CHANGELOG</span> => <span class="symbol">:changelog</span>, +<span class="line-numbers"><a href="#n11" name="n11">11</a></span> <span class="symbol">:LICENSE</span> => <span class="symbol">:license</span>, +<span class="line-numbers"><a href="#n12" name="n12">12</a></span> <span class="symbol">:README</span> => <span class="symbol">:introduction</span> +<span class="line-numbers"><a href="#n13" name="n13">13</a></span> } +<span class="line-numbers"><a href="#n14" name="n14">14</a></span> arg = args[<span class="symbol">:file</span>].upcase.to_sym +<span class="line-numbers"><a href="#n15" name="n15">15</a></span> raise <span class="constant">RuntimeError</span>, <span class="string"><span class="delimiter">"</span><span class="content">Unknown file '</span><span class="inline"><span class="inline-delimiter">#{</span>arg<span class="inline-delimiter">}</span></span><span class="content">.glyph'</span><span class="delimiter">"</span></span> +<span class="line-numbers"><a href="#n16" name="n16">16</a></span> <span class="keyword">unless</span> files.keys.include? arg +<span class="line-numbers"><a href="#n17" name="n17">17</a></span> generate.call files[arg], arg +<span class="line-numbers"><a href="#n18" name="n18">18</a></span> <span class="constant">Glyph</span>.info <span class="string"><span class="delimiter">"</span><span class="content">Done.</span><span class="delimiter">"</span></span> +<span class="line-numbers"><a href="#n19" name="n19">19</a></span> <span class="keyword">end</span> +<span class="line-numbers"><strong><a href="#n20" name="n20">20</a></strong></span><span class="keyword">end</span></pre></div> +</div> + + <p>That’s it. Note that this task is pretty useless without a command that calls it, and it won’t even show up if you run <code>rake -T</code> within your project directory. <span class="fmi">for more information on <mark>creating custom commands</mark>, see <a href="/glyph/book/extending/command.html#custom_command">Defining Custom Commands</a></span>.</p> + +</section> + +<nav class="navigation"><a href="/glyph/book/extending/commands_tasks.html">← Defining Custom Commands and Tasks</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/output_format.html">Custom Output Formats →</a></nav>
A
contents/glyph/book/extending/validators.html
@@ -0,0 +1,20 @@
+----- +title: "Glyph – Using Validators" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/extending/placeholders.html">← Using Placeholders</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/interpreting.html">Interpreting Glyph Code →</a></nav> + <p>If you need to make sure that a macro is used properly, consider using <a href="http://rubydoc.info/gems/glyph/Glyph/Macro/Validators">validators</a>. These methods can be used anywhere within the macro code to check whether certain conditions are met or not. Some default validators are provided to check the number of parameters of a macro, and they are actually used in some system macros.</p> + <p>If you want to create your own validators, you can call the generic <code>validate</code> method which takes the message to display in case of error, a Hash of options and a block containing the validation to perform.</p> + <aside class="box"> +<div class="box-title">Validating macro placement</div> +<p>You can, of course, create your own validators to check whether a macro is used directly within another. While this may seem a good idea to enforce constraints into the way documents are created, it has one major drawback: if you define a macro with such validation, you’re effectively limiting its usage, so for example you won’t be able to use within snippets or other custom macros.</p> +<p>Suppose, for example, that the <a href="/glyph/book/macros/macros_block.html#m_box"><code>box</code></a> macro is only allowed directly under a <code>section</code> macro. This means that, for example:</p> +<ul> + <li>the macro cannot be used within <code>chapter</code> or <code>appendix</code> macros.</li> + <li>the macro cannot be used in snippets</li> +</ul> +<p>Even if you consider all the possibilities within the scope of the default macros provided with Glyph, this could still make the <code>box</code> macro unusable within custom macros.</p> +<p>For the specific cases where a macro does not make sense unless is within another (e.g. the <a href="/glyph/book/macros/macros_core.html#m_eq"><code>eq</code></a> macro), a <code>within</code> validator is used. Note though, that this validator only checks that the macro is used within another, but it is not necessarily its child.</p> + +</aside> +<nav class="navigation"><a href="/glyph/book/extending/placeholders.html">← Using Placeholders</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/interpreting.html">Interpreting Glyph Code →</a></nav>
A
contents/glyph/book/getting_started/configuration.html
@@ -0,0 +1,44 @@
+----- +title: "Glyph – Project Configuration" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/getting_started/structure.html">← Document Structure</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/glyph_files.html"><code>.glyph</code> files →</a></nav> + + <p>Glyph stores configuration settings in the following <span class="caps">YAML</span> files:</p> +<ol> + <li>Your <em>Project Configuration</em> is stored in the <code>config.yml</code> file, included in each Glyph Project.</li> + <li>Your <em>Global Configuration</em> is stored in a <code>.glyphrc</code> file in your <code>$HOME</code> (or <code>%HOMEPATH%</code> on Windows) directory (not created by default).</li> + <li>The <em>System Configuration</em> is stored in the source directory of Glyph itself.</li> +</ol> +<p>When compiling, Glyph loads all these configuration files and merges them according to the following rules:</p> +<ul> + <li>A setting configured in the <em>Project Configuration</em> overrides the same setting in both Global and System configuration.</li> + <li>A setting configured in the <em>Global Configuration</em> overrides the same setting in the <em>System Configuration</em>.</li> +</ul> +<p>Typically, you should use the <em>Project Configuration</em> for all project-specific settings and the <em>Global Configuration</em> for settings affecting all your projects (for example, you may want to set the <a href="/glyph/book/config/document.html#s_document_author"><code>document.author</code></a> setting in the Global Configuration instead of setting it in the Project Configuration of all your Glyph projects). The <em>System Configuration</em> is best left untouched.</p> +<p>Instead of editing your configuration settings directly, you can use the <a href="/glyph/book/ref_commands.html#c_config"><code>config</code></a> command, as follows:</p> +<p><code>glyph config</code> <em>setting</em> <em>[value]</em></p> +<p>If no <em>value</em> is specified, Glyph prints the value of the configuration setting, so typing <code>glyph config document.author</code> right after creating a project (assuming you didn’t set this in the Global Configuration) will print nothing, because this setting is blank by default.</p> +<p>To change the value of a configuration setting, specify a value right after the setting, like this:</p> +<p><code>glyph config document.author "John Smith"</code></p> +<aside class="tip"> +<p><span class="note-title">Tip</span>It is also possible to change configuration settings inside your document, using the <a href="/glyph/book/macros/macros_core.html#m_config_"><code>config:</code></a> macro.</p> +</aside> +<p>In this way, the document author will be set to <em>John Smith</em> for the current project. To save this setting globally, add a <code>-g</code> option, like this:</p> +<p><code>glyph config -g document.author "John Smith"</code></p> +<aside class="box"> +<div class="box-title">Regarding configuration values and data types…</div> +<p>Glyph attempts to “guess” the data type of a configuration value by evaluation (<code>Kernel#instance_eval</code>) if the value:</p> +<ul> + <li>is wrapped in quotes (<code>"</code> or <code>'</code>) → <code>String</code></li> + <li>starts with a colon (<code>:</code>) → <code>Symbol</code></li> + <li>is wrapped in square brackets (<code>[</code> and <code>]</code>) → <code>Array</code></li> + <li>is wrapped in curly brackets (<code>{</code> and <code>}</code>) → <code>Hash</code></li> + <li>is <em>true</em> or <em>false</em> → <code>Boolean</code></li> + <li>is <em>nil</em> → <code>NilClass</code></li> +</ul> +<p>Note that this guessing is far from being foolproof: If you type something like <em>{:test, 2}</em>, for example, you’ll get an error.</p> +</aside> +<p>There are plenty of configuration settings that can be modified, but most of them are best if left alone (and in the System Configuration file).</p> +<p>For a complete reference, see <a href="/glyph/book/document.html#cfg_ref">Configuration Reference</a>. For everyday use, you may just want to change the settings defined in the <a href="/glyph/book/config/document.html#cfg_document"><code>document.*</code></a> namespace.</p> +<nav class="navigation"><a href="/glyph/book/getting_started/structure.html">← Document Structure</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/glyph_files.html"><code>.glyph</code> files →</a></nav>
A
contents/glyph/book/getting_started/create_project.html
@@ -0,0 +1,41 @@
+----- +title: "Glyph – Creating your first Glyph Project" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/acknowledgements.html">← Acknowledgements</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/getting_started/structure.html">Document Structure →</a></nav> +<p>To install Glyph, simply run <code>gem install glyph</code>, like with any other Ruby gem. Then, create a new directory and initialize a new Glyph project, like so:</p> +<p><code>mkdir</code> <em>test_document</em></p> +<p><code>cd</code> <em>test_document</em></p> +<p><code>glyph init</code></p> +<p>That’s it. You just created a new Glyph project in the <code>test_document</code> directory.</p> +<aside class="box"> +<div class="box-title">Glyph’s dependencies</div> +<p>Glyph requires the following gems:</p> +<ul> + <li>extlib</li> + <li>gli</li> + <li>rake</li> +</ul> +<p>Additionally, some Glyph macros may require additional gems, such as:</p> +<ul> + <li>RedCloth (<a href="/glyph/book/macros/macros_filters.html#m_textile"><code>textile</code></a> macro)</li> + <li>BlueCloth <em>or</em> RDiscount <em>or</em> Maruku <em>or</em> Kramdown (<a href="/glyph/book/macros/macros_filters.html#m_markdown"><code>markdown</code></a> macro)</li> + <li>Sass (if you want to load .sass files with the <a href="/glyph/book/macros/macros_structure.html#m_style"><code>style</code></a> macro)</li> + <li>CodeRay <em>or</em> UltraViolet (<a href="/glyph/book/macros/macros_filters.html#m_highlight"><code>highlight</code></a> macro)</li> + <li>directory_watcher (to use auto-regeneration with the <a href="/glyph/book/ref_commands.html#c_compile"><code>compile</code></a> command)</li> +</ul> +</aside> +<p>Every Glyph project is comprised of the following directories:</p> +<ul> + <li><code>images/</code> — used to store the image files used in your document.</li> + <li><code>lib/</code> — used to store your custom Glyph macros and Rake tasks.</li> + <li><code>output/</code> — used to store your generated output files.</li> + <li><code>styles/</code> — used to store your stylesheets.</li> + <li><code>text/</code> — used to store your source text files.</li> +</ul> +<p>Additionally, the following files are also created at top level:</p> +<ul> + <li><code>config.yml</code> — containing your <a href="/glyph/book/getting_started/configuration.html#cfg">Project Configuration</a>.</li> + <li><code>document.glyph</code> — containing the <a href="/glyph/book/getting_started/structure.html#struct">structure</a> of your document.</li> +</ul> +<nav class="navigation"><a href="/glyph/book/acknowledgements.html">← Acknowledgements</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/getting_started/structure.html">Document Structure →</a></nav>
A
contents/glyph/book/getting_started/structure.html
@@ -0,0 +1,57 @@
+----- +title: "Glyph – Document Structure" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/getting_started/create_project.html">← Creating your first Glyph Project</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/getting_started/configuration.html">Project Configuration →</a></nav> + + <p>Every Glyph project contains a <code>document.glyph</code> file that is typically used to define the document structure. The default <code>document.glyph</code> generated automatically when creating a new project is the following:</p> + + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span>book[ +<span class="line-numbers"> <a href="#n2" name="n2">2</a></span> @frontmatter[ +<span class="line-numbers"> <a href="#n3" name="n3">3</a></span> toc[] +<span class="line-numbers"> <a href="#n4" name="n4">4</a></span> preface[ +<span class="line-numbers"> <a href="#n5" name="n5">5</a></span> @title[Preface] +<span class="line-numbers"> <a href="#n6" name="n6">6</a></span> todo[Write the preface] +<span class="line-numbers"> <a href="#n7" name="n7">7</a></span> include[preface] +<span class="line-numbers"> <a href="#n8" name="n8">8</a></span> ] +<span class="line-numbers"> <a href="#n9" name="n9">9</a></span> ] +<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span> @bodymatter[ +<span class="line-numbers"><a href="#n11" name="n11">11</a></span> chapter[ +<span class="line-numbers"><a href="#n12" name="n12">12</a></span> @title[Chapter 1] +<span class="line-numbers"><a href="#n13" name="n13">13</a></span> todo[Write chapter 1] +<span class="line-numbers"><a href="#n14" name="n14">14</a></span> include[chapter_1] +<span class="line-numbers"><a href="#n15" name="n15">15</a></span> ] +<span class="line-numbers"><a href="#n16" name="n16">16</a></span> chapter[ +<span class="line-numbers"><a href="#n17" name="n17">17</a></span> @title[Chapter 2] +<span class="line-numbers"><a href="#n18" name="n18">18</a></span> todo[Write chapter 2] +<span class="line-numbers"><a href="#n19" name="n19">19</a></span> include[chapter_2] +<span class="line-numbers"><strong><a href="#n20" name="n20">20</a></strong></span> ] +<span class="line-numbers"><a href="#n21" name="n21">21</a></span> ] +<span class="line-numbers"><a href="#n22" name="n22">22</a></span> @backmatter[ +<span class="line-numbers"><a href="#n23" name="n23">23</a></span> appendix[ +<span class="line-numbers"><a href="#n24" name="n24">24</a></span> @title[Appendix A] +<span class="line-numbers"><a href="#n25" name="n25">25</a></span> todo[Write appendix A] +<span class="line-numbers"><a href="#n26" name="n26">26</a></span> include[appendix_a] +<span class="line-numbers"><a href="#n27" name="n27">27</a></span> ] +<span class="line-numbers"><a href="#n28" name="n28">28</a></span> ] +<span class="line-numbers"><a href="#n29" name="n29">29</a></span>]</pre></div> +</div> + + + <p>Even without knowing anything about Glyph Language, you can easily figure out that this file defines a document with a Table of Contents, a Preface some Chapters and an Appendix.</p> +<p>As you can see, Glyph wraps portions of text within square brackets preceded by an identifier. These identifiers are used for <em><a href="/glyph/book/text_editing/macro_intro.html#macro_intro">macros</a></em> and <em><a href="/glyph/book/text_editing/attribute_intro.html#attribute_intro">attributes</a></em>. The only syntactic difference between macros and attributes is that attributes are preceded by a <code>@</code>.</p> +<p>For now, think about a macro as something that performs a certain action and — generally — produces some text output or manipulation of the text inside it. In this way, it becomes easy to understand that the <code>chapter</code> macro creates a chapter and the <a href="/glyph/book/macros/macros_core.html#m_include"><code>include</code></a> macro includes an external file, for example.<br /> +Attributes “belong” to the macro they’re in, so in this case the <a href="/glyph/book/macros/macros_structure.html#m_book"><code>book</code></a> macro has the following attributes:</p> +<ul> + <li><code>@frontmatter</code></li> + <li><code>@bodymatter</code></li> + <li><code>@backmatter</code></li> +</ul> +<p>More specifically, in this <code>document.glyph</code> file:</p> +<ul> + <li>The <a href="/glyph/book/macros/macros_structure.html#m_book"><code>book</code></a> macro wraps every other macro and is used to create the document header and default title page.</li> + <li>Then, the <code>@frontmatter</code>, <code>@bodymatter</code>, and <code>@backmatter</code> attributes are used to divide the portions of your document according to the rules of <a href="http://en.wikipedia.org/wiki/Book_design">book design</a>. They are not mandatory, but they can be used, for example, to number your appendixes with letters instead of numbers and similar.</li> + <li><code>preface</code>, <code>chapter</code>, <code>appendix</code> are just a way to wrap content in <code><div></code> tags, from an <span class="caps">HTML</span> point of view (or <code><section></code> tags, in HTML5), but they are also necessary to nest the content of your document and generate the Table of Contents automatically, together through <code>@title</code> attributes.</li> +</ul> +<nav class="navigation"><a href="/glyph/book/getting_started/create_project.html">← Creating your first Glyph Project</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/getting_started/configuration.html">Project Configuration →</a></nav>
A
contents/glyph/book/index.html
@@ -0,0 +1,24 @@
+----- +title: "Glyph Documentation" +content-type: page +----- +<nav class="contents"> +<h1 class="toc-header" id="toc">Table of Contents</h1> +<ol class="toc"> + <li class="frontmatter introduction"><a href="/glyph/book/introduction.html#h_1">Introduction</a></li><li><ol><li class="frontmatter section"><a href="/glyph/book/license.html#h_12">License</a></li><li class="frontmatter section">Resources</li></ol></li> +<li class="frontmatter acknowledgement"><a href="/glyph/book/acknowledgements.html#h_13">Acknowledgements</a></li><li class="bodymatter chapter">Getting Started</li><li><ol><li class="bodymatter section"><a href="/glyph/book/getting_started/create_project.html#h_15">Creating your first Glyph Project</a></li><li class="bodymatter section"><a href="/glyph/book/getting_started/structure.html#struct">Document Structure</a></li><li class="bodymatter section"><a href="/glyph/book/getting_started/configuration.html#cfg">Project Configuration</a></li></ol></li> +<li class="bodymatter chapter">Authoring Documents</li><li><ol><li class="bodymatter section"><a href="/glyph/book/text_editing/glyph_files.html#h_19"><code>.glyph</code> files</a></li><li class="bodymatter section"><a href="/glyph/book/text_editing/macro_intro.html#macro_intro">Introducing Glyph Macros</a></li><li class="bodymatter section"><a href="/glyph/book/text_editing/attribute_intro.html#attribute_intro">Macro attributes</a></li><li class="bodymatter section"><a href="/glyph/book/text_editing/macro_composition.html#composition">Macro Composition</a></li><li class="bodymatter section"><a href="/glyph/book/text_editing/esc_quot.html#esc_quot">Escaping and Quoting</a></li><li class="bodymatter section"><a href="/glyph/book/text_editing/sections.html#sec_head">Sections and Headers</a></li><li><ol><li class="bodymatter section"><a href="/glyph/book/text_editing/section_aliases.html#h_26">Section Aliases</a></li><li class="bodymatter section"><a href="/glyph/book/text_editing/topics.html#topics">Topics</a></li></ol></li> +<li class="bodymatter section"><a href="/glyph/book/text_editing/links.html#links">Links and Bookmarks</a></li><li class="bodymatter section"><a href="/glyph/book/text_editing/images.html#img_fig">Images and Figures</a></li><li class="bodymatter section"><a href="/glyph/book/text_editing/code.html#source_code">Source Code</a></li><li class="bodymatter section">Other HTML Elements</li><li><ol><li class="bodymatter section"><a href="/glyph/book/text_editing/raw_html.html#h_32">Textile or Markdown</a></li><li class="bodymatter section"><a href="/glyph/book/text_editing/xml_fallback.html#h_33">XML Fallback</a></li></ol></li> +<li class="bodymatter section"><a href="/glyph/book/text_editing/stylesheets.html#stylesheets">Adding Stylesheets</a></li><li class="bodymatter section"><a href="/glyph/book/text_editing/inclusions.html#incl">Content Reuse</a></li><li class="bodymatter section"><a href="/glyph/book/text_editing/conditionals.html#cond_macros">Conditional Macros</a></li><li class="bodymatter section"><a href="/glyph/book/text_editing/evaluation.html#h_43">Simple Programming and Code Evaluation</a></li><li><ol><li class="bodymatter section">Turing-completeness</li><li class="bodymatter section">Lexically-scoped attribute assignment</li><li class="bodymatter section">Evaluating Ruby code</li></ol></li> +</ol></li> +<li class="bodymatter chapter">Generating Output Files</li><li><ol><li class="bodymatter section"><a href="/glyph/book/compiling/compiling.html#compile">Compiling a project</a></li><li class="bodymatter section"><a href="/glyph/book/compiling/lite_mode.html#lite_mode">Compiling single Glyph files</a></li><li class="bodymatter section"><a href="/glyph/book/compiling/programmatic_usage.html#h_57">Using Glyph programmatically</a></li></ol></li> +<li class="bodymatter chapter">Document Statistics</li><li><ol><li class="bodymatter section"><a href="/glyph/book/stats/stats.html#h_60">Using the stats command</a></li><li class="bodymatter section"><a href="/glyph/book/stats/macros.html#stats_macros">Macro Statistics</a></li><li class="bodymatter section"><a href="/glyph/book/stats/snippets.html#stats_snippets">Snippet Statistics</a></li><li class="bodymatter section"><a href="/glyph/book/stats/bookmarks.html#stats_bookmarks">Bookmark Statistics</a></li><li class="bodymatter section"><a href="/glyph/book/stats/links.html#stats_links">Link Statistics</a></li></ol></li> +<li class="bodymatter chapter">Extending Glyph</li><li><ol><li class="bodymatter section"><a href="/glyph/book/extending/internals.html#h_82">A quick look at Glyph's internals</a></li><li class="bodymatter section"><a href="/glyph/book/extending/macro_def.html#macro_def">Defining Custom Macros</a></li><li><ol><li class="bodymatter section"><a href="/glyph/book/extending/params_attrs.html#h_86">Parameters and Attributes</a></li><li class="bodymatter section"><a href="/glyph/book/extending/bookmarks_headers.html#h_89">Bookmarks and Headers</a></li><li class="bodymatter section"><a href="/glyph/book/extending/placeholders.html#h_90">Using Placeholders</a></li><li class="bodymatter section"><a href="/glyph/book/extending/validators.html#h_91">Using Validators</a></li><li class="bodymatter section"><a href="/glyph/book/extending/interpreting.html#interpreting">Interpreting Glyph Code</a></li><li class="bodymatter section"><a href="/glyph/book/extending/layouts.html#layouts">Layouts</a></li><li class="bodymatter section"><a href="/glyph/book/extending/further_reading.html#h_99">Further Reading</a></li></ol></li> +<li class="bodymatter section"><a href="/glyph/book/extending/commands_tasks.html#h_100">Defining Custom Commands and Tasks</a></li><li><ol><li class="bodymatter section"><a href="/glyph/book/extending/task.html#custom_task">Defining Custom Tasks</a></li><li class="bodymatter section"><a href="/glyph/book/extending/command.html#custom_command">Defining Custom Commands</a></li></ol></li> +</ol></li> +<li class="bodymatter chapter">Troubleshooting</li><li><ol><li class="bodymatter section"><a href="/glyph/book/troubleshooting/errors_generic.html#h_110">Generic Errors</a></li><li class="bodymatter section"><a href="/glyph/book/troubleshooting/errors_parser.html#h_111">Parsing Errors</a></li><li class="bodymatter section"><a href="/glyph/book/troubleshooting/errors_command.html#h_112">Command Errors</a></li><li class="bodymatter section"><a href="/glyph/book/troubleshooting/errors_macro.html#h_113">Macro Errors</a></li></ol></li> +<li class="backmatter appendix"><a href="/glyph/book/ref_commands.html#cmd_ref">Command Reference</a></li><li class="backmatter appendix">Macro Reference</li><li><ol><li class="appendix section"><a href="/glyph/book/macros/macros_core.html#h_139">Core Macros</a></li><li class="appendix section"><a href="/glyph/book/macros/macros_block.html#h_215">Block Macros</a></li><li class="appendix section"><a href="/glyph/book/macros/macros_inline.html#h_240">Inline Macros</a></li><li class="appendix section"><a href="/glyph/book/macros/macros_filters.html#f_macros">Filter Macros</a></li><li class="appendix section"><a href="/glyph/book/macros/macros_structure.html#h_266">Structure Macros</a></li></ol></li> +<li class="backmatter appendix">Configuration Reference</li><li><ol><li class="appendix section"><a href="/glyph/book/config/document.html#cfg_document"><code>document.*</code></a></li><li class="appendix section"><a href="/glyph/book/config/filters.html#cfg_filters"><code>filters.*</code></a></li><li class="appendix section"><a href="/glyph/book/config/options.html#cfg_options"><code>options.*</code></a></li><li class="appendix section"><a href="/glyph/book/config/output.html#cfg_output"><code>output.*</code></a></li></ol></li> +<li class="backmatter appendix"><a href="/glyph/book/changelog.html#h_297">Changelog</a></li> +</ol> +</nav>
A
contents/glyph/book/introduction.html
@@ -0,0 +1,152 @@
+----- +title: "Glyph – Introduction" +content-type: page +----- +<nav class="navigation"> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/license.html">License →</a></nav> +<section class="section"> +<p>Glyph is a <em>Rapid Document Authoring Framework</em>.</p> +<p>With Glyph, creating and maintaining any kind of document becomes as easy as… <em>programming</em>. Glyph enables you to minimize text duplication, focus on content rather than presentation, manage references seamlessly and automate tedious tasks through a simple but effective macro language, specifically geared towards customization and extensibility.</p> + + <section class="section"> +<header><h1 id="h_2" class="toc">Main Features</h1></header> +<section class="section"> +<header><h1 id="h_3" class="toc">Command Line Interface</h1></header> +<p>Glyph is 100% command line. Its interface resambles <a href="http://git-scm.com/">Git’s</a> for its simplicity and power (thanks to the <a href="http://github.com/davetron5000/gli">gli</a> gem). Here are some example commands:</p> +<ul> + <li><code>glyph init</code> — to initialize a new Glyph project in the current (empty) directory.</li> + <li><code>glyph add introduction.textile</code> — to create a new file called <em>introduction.textile</em>.</li> + <li><code>glyph compile</code> — to compile the current document into a single <span class="caps">HTML</span> file.</li> + <li><code>glyph compile --auto</code> — to keep recompiling the current document every time a file is changed.</li> + <li><code>glyph compile -f pdf</code> — to compile the current document into <span class="caps">HTML</span> and then transform it into <span class="caps">PDF</span>.</li> + <li><code>glyph compile readme.glyph</code> — to compile a <em>readme.glyph</em> located in the current directory into a single <span class="caps">HTML</span> file.</li> + <li><code>glyph outline -l 2</code> — Display the document outline, up to second-level headers.</li> + <li><code>glyph stats</code> — Display project statistics.</li> +</ul> + +</section> + + <section class="section"> +<header><h1 id="h_4" class="toc">Minimalist Syntax</h1></header> +<p>Glyph syntax rules can be explained using Glyph itself:</p> + + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span>section[ +<span class="line-numbers"> <a href="#n2" name="n2">2</a></span> @title[Something about Glyph] +<span class="line-numbers"> <a href="#n3" name="n3">3</a></span> txt[ +<span class="line-numbers"> <a href="#n4" name="n4">4</a></span>You can use Glyph macros in conjunction +<span class="line-numbers"> <a href="#n5" name="n5">5</a></span>with _Textile_ or _Markdown_ to +<span class="line-numbers"> <a href="#n6" name="n6">6</a></span>produce HTML files effortlessly. +<span class="line-numbers"> <a href="#n7" name="n7">7</a></span> ] +<span class="line-numbers"> <a href="#n8" name="n8">8</a></span> p[Alternatively, you can just use em[Glyph itself] to generate HTML tags.] +<span class="line-numbers"> <a href="#n9" name="n9">9</a></span> section[ +<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span> @title[What about PDFs?] +<span class="line-numbers"><a href="#n11" name="n11">11</a></span> @id[pdf] +<span class="line-numbers"><a href="#n12" name="n12">12</a></span> p[ +<span class="line-numbers"><a href="#n13" name="n13">13</a></span>Once you have a single, well-formatted HTML +<span class="line-numbers"><a href="#n14" name="n14">14</a></span>file, converting it to PDF is +<span class="line-numbers"><a href="#n15" name="n15">15</a></span>extremely easy with a free 3rd-party +<span class="line-numbers"><a href="#n16" name="n16">16</a></span>renderer like =>[http://www.princexml.com|Prince] +<span class="line-numbers"><a href="#n17" name="n17">17</a></span>or =>[http://code.google.com/p/wkhtmltopdf/|wkhtmltopdf]. +<span class="line-numbers"><a href="#n18" name="n18">18</a></span> ] +<span class="line-numbers"><a href="#n19" name="n19">19</a></span> ] +<span class="line-numbers"><strong><a href="#n20" name="n20">20</a></strong></span>]</pre></div> +</div> + +<p>The Glyph code above corresponds to the following HTML code:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span><span class="tag"><div</span> <span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">section</span><span class="delimiter">"</span></span><span class="tag">></span> +<span class="line-numbers"> <a href="#n2" name="n2">2</a></span> <span class="tag"><h2</span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">h_10</span><span class="delimiter">"</span></span><span class="tag">></span>Something about Glyph<span class="tag"></h2></span> +<span class="line-numbers"> <a href="#n3" name="n3">3</a></span> <span class="tag"><p></span> +<span class="line-numbers"> <a href="#n4" name="n4">4</a></span> You can use Glyph macros in conjunction with +<span class="line-numbers"> <a href="#n5" name="n5">5</a></span> <span class="tag"><em></span>Textile<span class="tag"></em></span> or <span class="tag"><em></span>Markdown<span class="tag"></em></span> to +<span class="line-numbers"> <a href="#n6" name="n6">6</a></span> produce HTML files effortlessly. +<span class="line-numbers"> <a href="#n7" name="n7">7</a></span> <span class="tag"></p></span> +<span class="line-numbers"> <a href="#n8" name="n8">8</a></span> <span class="tag"><p></span> +<span class="line-numbers"> <a href="#n9" name="n9">9</a></span> Alternatively, you can just use <span class="tag"><em></span>Glyph itself<span class="tag"></em></span> +<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span> to generate HTML tags. +<span class="line-numbers"><a href="#n11" name="n11">11</a></span> <span class="tag"></p></span> +<span class="line-numbers"><a href="#n12" name="n12">12</a></span> <span class="tag"><div</span> <span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">section</span><span class="delimiter">"</span></span><span class="tag">></span> +<span class="line-numbers"><a href="#n13" name="n13">13</a></span> <span class="tag"><h3</span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">pdf</span><span class="delimiter">"</span></span><span class="tag">></span>What about PDFs?<span class="tag"></h3></span> +<span class="line-numbers"><a href="#n14" name="n14">14</a></span> <span class="tag"><p></span> +<span class="line-numbers"><a href="#n15" name="n15">15</a></span> Once you have a single, well-formatted HTML +<span class="line-numbers"><a href="#n16" name="n16">16</a></span> file, converting it to PDF is +<span class="line-numbers"><a href="#n17" name="n17">17</a></span> extremely easy with a free 3rd-party renderer +<span class="line-numbers"><a href="#n18" name="n18">18</a></span> like <span class="tag"><a</span> <span class="attribute-name">href</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://www.princexml.com</span><span class="delimiter">"</span></span><span class="tag">></span>Prince<span class="tag"></a></span> +<span class="line-numbers"><a href="#n19" name="n19">19</a></span> or <span class="tag"><a</span> <span class="attribute-name">href</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://code.google.com/p/wkhtmltopdf/</span><span class="delimiter">"</span></span><span class="tag">></span>wkhtmltopdf<span class="tag"></a></span>. +<span class="line-numbers"><strong><a href="#n20" name="n20">20</a></strong></span> <span class="tag"></p></span> +<span class="line-numbers"><a href="#n21" name="n21">21</a></span> <span class="tag"></div></span> +<span class="line-numbers"><a href="#n22" name="n22">22</a></span><span class="tag"></div></span></pre></div> +</div> + +</section> + + <section class="section"> +<header><h1 id="h_5" class="toc">Content Reuse</h1></header> +<p>Finding yourself repeating the same sentence over an over? Glyph allows you to create snippets. Within snippets. Within other snippets (and so on, for a long long time…) as long as you don’t define a snippet by defining itself, which would be kinda nasty (and Glyph would complain!):</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>snippet:[entities|snippets and macros] +<span class="line-numbers"><a href="#n2" name="n2">2</a></span>snippet:[custom_definitions| +<span class="line-numbers"><a href="#n3" name="n3">3</a></span> p[Glyph allows you to define your own &[entities].] +<span class="line-numbers"><a href="#n4" name="n4">4</a></span>] +<span class="line-numbers"><a href="#n5" name="n5">5</a></span>&[custom_definitions]</pre></div> +</div> + + <p>...which results in:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span><span class="tag"><p></span>Glyph allows you to define your own snippets and macros.<span class="tag"></p></span></pre></div> +</div> + + <p>If yourself dreaming about <em>parametric</em> snippets, just create your own macros (see the <a href="http://github.com/h3rald/glyph/blob/master/book/text/changelog.glyph">source</a> of Glyph’s changelog, just to have an idea).</p> + +</section> + <section class="section"> +<header><h1 id="h_6" class="toc">Automation of Common Tasks</h1></header> +<p>If you’re writing a book, you shouldn’t have to worry about pagination, headers, footers, table of contents, section numbering or similar. Glyph understands you, and will take care of everything for you (with a little help from CSS3, sometimes).</p> + +</section> + <section class="section"> +<header><h1 id="h_7" class="toc">Reference Validation</h1></header> +<p>Feel free to add plenty of links, snippets, bookmarks, … if Glyph doesn’t find something, it will definitely complain. Broken references are a thing on the past, and you don’t need to worry about it.</p> + +</section> + <section class="section"> +<header><h1 id="h_8" class="toc">Extreme Extensibility</h1></header> +<ul> + <li>You miss a <code>!!!</code> macro to format really, <em>really</em> important things? Create it. In under 3 seconds, in Ruby or Glyph itself. And yes, you can use special characters, too.</li> + <li>You want your own, very special special <code>glyph create --everything</code> command to create all <em>you</em> need in a Glyph project? You can do it. Using your own Rake tasks, too.</li> + <li>You want Glyph to output <span class="caps">ODF</span> files? You can do it, and you’ll be able to run <code>glyph generate -f odf</code>. This would probably require a little more time, but it’s trivial, from a technical point of view.</li> +</ul> + +</section> + <section class="section"> +<header><h1 id="h_9" class="toc">Convention over Configuration</h1></header> +<p>Put your text files in <code>/text</code>, your images in <code>/images</code>, add custom macros in a <code>macro</code> folder within your <code>/lib</code> folder… you get the picture: Glyph has its special places.</p> +<p>Nonetheless, you also have 1 (<em>one</em>) configuration file to customize to your heart’s content (with smart defaults).</p> + +</section> + <section class="section"> +<header><h1 id="h_10" class="toc">Free and Open Source</h1></header> +<p>Glyph is 100% Open Source Software, developed using the Ruby Programming Language and licensed under the very permissive terms of the <a href="http://www.opensource.org/licenses/mit-license.php"><span class="caps">MIT</span> License</a>.</p> +<p>If you have Ruby installed, just run <code>gem install glyph</code>. That’s all it takes.</p> + +</section> + +</section> + <section class="section"> +<header><h1 id="h_11" class="toc">Resources</h1></header> +<ul> + <li>Home Page: <a href="http://www.h3rald.com/glyph/">http://www.h3rald.com/glyph/</a></li> + <li>Repository: <a href="http://www.github.com/h3rald/glyph/">http://www.github.com/h3rald/glyph/</a></li> + <li>Bug Tracking: <a href="http://www.github.com/h3rald/glyph/issues">http://www.github.com/h3rald/glyph/issues</a></li> + <li>Development Wiki <a href="http://wiki.github.com/h3rald/glyph">http://wiki.github.com/h3rald/glyph</a></li> + <li>RubyGem Download <a href="http://www.rubygems.org/gems/glyph">http://www.rubygems.org/gems/glyph</a></li> + <li>Book (<span class="caps">PDF</span>): <a href="http://github.com/downloads/h3rald/glyph/glyph.pdf">http://github.com/downloads/h3rald/glyph/glyph.pdf</a></li> + <li>Book (Web): <a href="http://www.h3rald.com/glyph/book/">http://www.h3rald.com/glyph/book/</a></li> + <li>Reference Documentation: <a href="http://rubydoc.info/gems/glyph/">http://rubydoc.info/gems/glyph/</a></li> + <li>User Group: <a href="http://groups.google.com/group/glyph-framework">http://groups.google.com/group/glyph-framework</a></li> +</ul> + +</section> + +</section> +<nav class="navigation"> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/license.html">License →</a></nav>
A
contents/glyph/book/license.html
@@ -0,0 +1,23 @@
+----- +title: "Glyph – License" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/introduction.html">← Introduction</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/acknowledgements.html">Acknowledgements →</a></nav> +<p>Copyright © 2010-2012 <strong>Fabio Cevasco</strong>, <a href="http://www.h3rald.com">http://www.h3rald.com</a></p> +<p>Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions:</p> +<p>The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software.</p> +<p>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. +</p> +<nav class="navigation"><a href="/glyph/book/introduction.html">← Introduction</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/acknowledgements.html">Acknowledgements →</a></nav>
A
contents/glyph/book/macros/macros_block.html
@@ -0,0 +1,320 @@
+----- +title: "Glyph – Block Macros" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/macros/macros_core.html">← Core Macros</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/macros/macros_inline.html">Inline Macros →</a></nav> + + <section class="section"> +<header><h1 id="m_box" class="toc"><code>box</code></h1></header> +<p>Creates a titled box (<code><div></code> tag).</p> + + + + <section class="section"> +<header><h1 id="h_217" class="notoc">Example</h1></header> +<div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>box[Why boxes?| +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> Boxes can be used to make a section of text stand out from the rest of the document. +<span class="line-numbers"><a href="#n3" name="n3">3</a></span>]</pre></div> +</div> + +</section> + + + + <section class="section"> +<header><h1 id="h_218" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The box title.</td> + </tr> + + + <tr> + <td>1</td> + <td>The box text.</td> + </tr> + </table> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_codeblock" class="toc"><code>codeblock</code></h1></header> +<p>Used to render a block of code within <code><pre></code> and <code><code></code> tags.</p> + + + + <section class="section"> +<header><h1 id="h_220" class="notoc">Example</h1></header> +<div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>code[ +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> def hello +<span class="line-numbers"><a href="#n3" name="n3">3</a></span> puts "Hello World" +<span class="line-numbers"><a href="#n4" name="n4">4</a></span> end +<span class="line-numbers"><a href="#n5" name="n5">5</a></span>]</pre></div> +</div> + +</section> + + + + <section class="section"> +<header><h1 id="h_221" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The code to be formatted.</td> + </tr> + </table> + +</section> + + +<section class="section"> +<header><h1 id="h_222" class="notoc">Remarks</h1></header> +<p>For code highlighting, see the <a href="/glyph/book/macros/macros_filters.html#m_highlight"><code>highlight</code></a> macro.</p> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_figure" class="toc"><code>figure</code></h1></header> +<p>Includes an image in the document, with an optional caption (see <a href="/glyph/book/text_editing/images.html#img_fig">Images and Figures</a>).</p> + + + + <section class="section"> +<header><h1 id="h_224" class="notoc">Example</h1></header> +<div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>figure[ +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> graph.png|Monthly Pageviews +<span class="line-numbers"><a href="#n3" name="n3">3</a></span> @width[90%] +<span class="line-numbers"><a href="#n4" name="n4">4</a></span>]</pre></div> +</div> + +</section> + + + + <section class="section"> +<header><h1 id="h_225" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The name of the image file (relative to the <code>images/</code> folder).</td> + </tr> + + + <tr> + <td>1</td> + <td>The image caption <em>(optional)</em>.</td> + </tr> + </table> + +</section> + + + <section class="section"> +<header><h1 id="h_226" class="notoc">Attributes</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Attribute</th> + <th>Description</th> + </tr> +<tr> + <td>*</td> + <td>Any attribute supported by the <a href="http://www.w3schools.com/tags/tag_IMG.asp">img tag</a>.</td> + </tr> + </table> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_image" class="toc"><code>image</code></h1></header> +<p>Includes an image in the document</p> + + + + <section class="section"> +<header><h1 id="h_228" class="notoc">Example</h1></header> +<div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>img[ +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> holidays/landscape.jpg +<span class="line-numbers"><a href="#n3" name="n3">3</a></span> @class[photo] +<span class="line-numbers"><a href="#n4" name="n4">4</a></span> @style[border: 1px solid black;] +<span class="line-numbers"><a href="#n5" name="n5">5</a></span>]</pre></div> +</div> + +</section> + + + + <section class="section"> +<header><h1 id="h_229" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The name of the image file (relative to the <code>images/</code> folder).</td> + </tr> + </table> + +</section> + + + <section class="section"> +<header><h1 id="h_230" class="notoc">Attributes</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Attribute</th> + <th>Description</th> + </tr> +<tr> + <td>*</td> + <td>Any attribute supported by the <a href="http://www.w3schools.com/tags/tag_IMG.asp">img tag</a>.</td> + </tr> + </table> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_navigation" class="toc"><code>navigation</code></h1></header> +<p>Displays links to the document’s <span class="caps">TOC</span> and the previous/next topic (used only in <a href="/glyph/book/extending/layouts.html#layouts">layouts</a>).</p> + + + + + + <section class="section"> +<header><h1 id="h_232" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The ID of the current topic.</td> + </tr> + </table> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_note" class="toc"><code>note</code></h1></header> +<p>Creates a note <code>div</code> containing the value.</p> +<strong>Aliases:</strong> <code>important, caution, tip</code> +<p><strong>Example:</strong> <code>note[This is a note.]</code></p> + + + + <section class="section"> +<header><h1 id="h_234" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The text of the note.</td> + </tr> + </table> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_pubdate" class="toc"><code>pubdate</code></h1></header> +<p>Evaluates to a date string (in the format: <em>current_month</em> <em>current_year</em>; i.e. <em>%B</em> <em>%Y</em>), within a <code><div></code> tag. If a parameter is supplied, its value is used instead of the current date.</p> + +<p><strong>Example:</strong> <code>pubdate[]</code></p> + + + + <section class="section"> +<header><h1 id="h_236" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>An alternative content for the _pubdate_ @div@.</td> + </tr> + </table> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_revision" class="toc"><code>revision</code></h1></header> +<p>Renders the revision of the document (based on the <a href="/glyph/book/config/document.html#s_document_revision"><code>document.revision</code></a> setting) within a <code><div></code> tag.</p> + +<p><strong>Example:</strong> <code>revision[]</code></p> + +</section> + + + + <section class="section"> +<header><h1 id="m_subtitle" class="toc"><code>subtitle</code></h1></header> +<p>Renders the subtitle of the document (based on the <a href="/glyph/book/config/document.html#s_document_subtitle"><code>document.subtitle</code></a> setting) within a <code><h2></code> tag.</p> + +<p><strong>Example:</strong> <code>subtitle[]</code></p> + +</section> + + + + <section class="section"> +<header><h1 id="m_title" class="toc"><code>title</code></h1></header> +<p>Renders the title of the document (based on the <a href="/glyph/book/config/document.html#s_document_title"><code>document.title</code></a> setting) within a <code><h1></code> tag.</p> + +<p><strong>Example:</strong> <code>title[]</code></p> + +</section> + +<nav class="navigation"><a href="/glyph/book/macros/macros_core.html">← Core Macros</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/macros/macros_inline.html">Inline Macros →</a></nav>
A
contents/glyph/book/macros/macros_core.html
@@ -0,0 +1,1097 @@
+----- +title: "Glyph – Core Macros" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/ref_commands.html">← Command Reference</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/macros/macros_block.html">Block Macros →</a></nav> + + + <section class="section"> +<header><h1 id="m_add" class="toc"><code>add</code></h1></header> +<p>Adds two or more integers together.</p> + +<p><strong>Example:</strong> <code>add[2|5|7]</code></p> + +</section> + + + + <section class="section"> +<header><h1 id="m_alias" class="toc"><code>alias</code></h1></header> +<p>Creates a macro alias.</p> + +<p><strong>Example:</strong> <code>alias[s|section]</code></p> + + + + <section class="section"> +<header><h1 id="h_142" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The name of the alias.</td> + </tr> + + + <tr> + <td>1</td> + <td>The name of an existing macro.</td> + </tr> + </table> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_and" class="toc"><code>and</code></h1></header> +<p>Conditional <code>and</code> operator, to be used with the <a href="#m_condition"><code>condition</code></a> macro.</p> + +<p><strong>Example:</strong> <code>?[and[true|false]|This is never displayed.]</code></p> + + + + <section class="section"> +<header><h1 id="h_144" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The first expression to test</td> + </tr> + + <tr> + <td>1</td> + <td>The second expression to test</td> + </tr> + </table> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_attribute" class="toc"><code>attribute</code></h1></header> +<p>Returns the value of the specified attribute. For a more complete example, see the <a href="#m_let"><code>let</code></a> macro.</p> +<strong>Aliases:</strong> <code>@</code> +<p><strong>Example:</strong> <code>@[title]</code></p> + + + + <section class="section"> +<header><h1 id="h_146" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The name of the attribute to retrieve.</td> + </tr> + </table> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_attribute_" class="toc"><code>attribute:</code></h1></header> +<p>Sets the value of the specified attribute. For a more complete example, see the ‡‡‡‡‡PLACEHOLDER¤277‡‡‡‡‡ macro.</p> +<strong>Aliases:</strong> <code>@:</code> +<p><strong>Example:</strong> <code>@:[title|Test Title]</code></p> + + + + <section class="section"> +<header><h1 id="h_148" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The name of the attribute to set.</td> + </tr> + + + <tr> + <td>1</td> + <td>The value of the attribute.</td> + </tr> + </table> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_comment" class="toc"><code>comment</code></h1></header> +<p>Evaluates to nothing. Used to add comments in a Glyph document that will not be displayed in output files.</p> +<strong>Aliases:</strong> <code>--</code> +<p><strong>Example:</strong> <code>--[=>[#link|This link will not be evaluated]]</code></p> + + + + <section class="section"> +<header><h1 id="h_150" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The contents to comment out</td> + </tr> + </table> + +</section> + + +<section class="section"> +<header><h1 id="h_151" class="notoc">Remarks</h1></header> +<p>Macros are not expanded within comments.</p> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_condition" class="toc"><code>condition</code></h1></header> +<p>Tests a conditional expression. For more information, see <a href="/glyph/book/text_editing/conditionals.html#cond_macros">Conditional Macros</a>.</p> +<strong>Aliases:</strong> <code>?</code> + + + + + <section class="section"> +<header><h1 id="h_153" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The condition to test</td> + </tr> + + + <tr> + <td>1</td> + <td>The contents to expand if the condition is satisfied.</td> + </tr> + </table> + +</section> + + +<section class="section"> +<header><h1 id="h_154" class="notoc">Remarks</h1></header> +<p>For examples see any of the following:</p> +<ul> + <li><a href="#m_and"><code>and</code></a> macro</li> + <li><a href="#m_or"><code>or</code></a> macro</li> + <li><a href="#m_not"><code>not</code></a> macro</li> + <li><a href="#m_match"><code>match</code></a> macro</li> + <li><a href="#m_eq"><code>eq</code></a> macro</li> +</ul> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_config" class="toc"><code>config</code></h1></header> +<p>Returns the value of a configuration setting.</p> +<strong>Aliases:</strong> <code>$</code> +<p><strong>Example:</strong> <code>$[document.author]</code></p> + + + + <section class="section"> +<header><h1 id="h_156" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The full name of a configuration setting.</td> + </tr> + </table> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_config_" class="toc"><code>config:</code></h1></header> +<p>Sets the value of a configuration setting.</p> +<strong>Aliases:</strong> <code>$:</code> +<p><strong>Example:</strong> <code>$:[document.draft|true]</code></p> + + + + <section class="section"> +<header><h1 id="h_158" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The full name of a configuration setting.</td> + </tr> + + + <tr> + <td>1</td> + <td>The new value of the configuration setting</td> + </tr> + </table> + +</section> + + +<section class="section"> +<header><h1 id="h_159" class="notoc">Remarks</h1></header> +<p>This macro cannot be used in <a href="/glyph/book/compiling/programmatic_usage.html#modes">safe mode</a>.</p> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_eq" class="toc"><code>eq</code></h1></header> +<p>Conditional equality operator, to be used with the <a href="#m_condition"><code>condition</code></a> macro.</p> + +<p><strong>Example:</strong> <code>?[eq[$[document.draft]|true]|This is displayed only in draft documents.]</code></p> + + + + <section class="section"> +<header><h1 id="h_161" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The first expression to test</td> + </tr> + + <tr> + <td>1</td> + <td>The second expression to test</td> + </tr> + </table> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_escape" class="toc"><code>escape</code></h1></header> +<p>Evaluates to its value. Commonly used with the escaping delimiters <code>[=</code> and <code>=]</code>.</p> +<strong>Aliases:</strong> <code>.</code> +<p><strong>Example:</strong> <code>.[=Macros are escaped here =>[#test].=]</code></p> + + + + <section class="section"> +<header><h1 id="h_163" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The contents to escape.</td> + </tr> + </table> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_fragment" class="toc"><code>fragment</code></h1></header> +<p>Delimits a fragment of text that can be embedded using the <a href="#m_embed"><code>embed</code></a> macro.</p> +<strong>Aliases:</strong> <code>##</code> +<p><strong>Example:</strong> <code>##[test_fragment|This is an embeddable fragment]</code></p> + + + + <section class="section"> +<header><h1 id="h_165" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The ID of the fragment.</td> + </tr> + + + <tr> + <td>1</td> + <td>The contents of the fragment.</td> + </tr> + </table> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_embed" class="toc"><code>embed</code></h1></header> +<p>Embeds text previously-delimited using the <a href="#m_fragment"><code>fragment</code></a> macro.</p> +<strong>Aliases:</strong> <code>&=</code> +<p><strong>Example:</strong> <code>&=[test_fragment]</code></p> + + + + <section class="section"> +<header><h1 id="h_167" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The ID of the fragment.</td> + </tr> + </table> + +</section> + +</section> + + + + + + + <section class="section"> +<header><h1 id="m_gt" class="toc"><code>gt</code></h1></header> +<p>Returns <em>true</em> if the first parameter is gt the second one.</p> + +<p><strong>Example:</strong> <code>greater than[5|2]</code></p> + + + + <section class="section"> +<header><h1 id="h_169" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The first integer to compare.</td> + </tr> + + + <tr> + <td>1</td> + <td>The second integer to compare.</td> + </tr> + </table> + +</section> + +</section> + + + + + + <section class="section"> +<header><h1 id="m_gte" class="toc"><code>gte</code></h1></header> +<p>Returns <em>true</em> if the first parameter is gte the second one.</p> + +<p><strong>Example:</strong> <code>greater than or equal to[5|2]</code></p> + + + + <section class="section"> +<header><h1 id="h_171" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The first integer to compare.</td> + </tr> + + + <tr> + <td>1</td> + <td>The second integer to compare.</td> + </tr> + </table> + +</section> + +</section> + + + + + <section class="section"> +<header><h1 id="m_include" class="toc"><code>include</code></h1></header> +<p>Evaluates to the contents of a text file stored in the <code>text/</code> directory referenced by its relative path. If the <a href="/glyph/book/config/options.html#s_options_filters_by_file_extension"><code>options.filters_by_file_extension</code></a> setting is <code>true</code>, filters the contents of the file using the <a href="/glyph/book/macros/macros_filters.html#f_macros">filter macro</a> corresponding to the file extension.</p> +<strong>Aliases:</strong> <code>@</code> +<p><strong>Example:</strong> <code>include[frontmatter/introduction]</code></p> + + + + <section class="section"> +<header><h1 id="h_173" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The file to include.</td> + </tr> + </table> + +</section> + + +<section class="section"> +<header><h1 id="h_174" class="notoc">Remarks</h1></header> +<ul> +<li> +<p>This macro cannot be used in <a href="/glyph/book/compiling/programmatic_usage.html#modes">safe mode</a>.</p> +</li> + <li><code>.glyph</code> is assumed if no file extension is specified.</li> +<li> +<p>This macro can also be used to include <code>.rb</code> ruby files within the <code>lib</code> directory. File contents are evaluated in the context of the <a href="http://rubydoc.info/gems/glyph/Glyph">Glyph</a> module.</p> +</li> +</ul> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_let" class="toc"><code>let</code></h1></header> +<p>Used to bind one or more attributes via the <a href="#m_attribute"><code>attribute</code></a> macro. Actually, you can use <a href="#m_attribute"><code>attribute</code></a> macro inside any other macro, but it looks tidier in this way.</p> + + + + <section class="section"> +<header><h1 id="h_176" class="notoc">Example</h1></header> +<div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>let[ +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> @:[a|2] +<span class="line-numbers"><a href="#n3" name="n3">3</a></span> @:[b|3] +<span class="line-numbers"><a href="#n4" name="n4">4</a></span> section[ +<span class="line-numbers"><a href="#n5" name="n5">5</a></span> @title[Testing] +<span class="line-numbers"><a href="#n6" name="n6">6</a></span> @[title]: @[a] * @[b] = multiply[@[a]|@[b]] --[Outputs: Testing: 2 * 3 = 6] +<span class="line-numbers"><a href="#n7" name="n7">7</a></span> ] +<span class="line-numbers"><a href="#n8" name="n8">8</a></span>]</pre></div> +</div> + +</section> + + + + <section class="section"> +<header><h1 id="h_177" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>Any content.</td> + </tr> + </table> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_load" class="toc"><code>load</code></h1></header> +<p>Embeds the contents of a file.</p> + +<p><strong>Example:</strong> <code>load[my_samples.rb]</code></p> + + + + <section class="section"> +<header><h1 id="h_179" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The file to embed, relative to the Glyph project folder.</td> + </tr> + </table> + +</section> + +</section> + + + + + <section class="section"> +<header><h1 id="m_lt" class="toc"><code>lt</code></h1></header> +<p>Returns <em>true</em> if the first parameter is lt the second one.</p> + +<p><strong>Example:</strong> <code>less than[5|2]</code></p> + + + + <section class="section"> +<header><h1 id="h_181" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The first integer to compare.</td> + </tr> + + + <tr> + <td>1</td> + <td>The second integer to compare.</td> + </tr> + </table> + +</section> + +</section> + + + + + + <section class="section"> +<header><h1 id="m_lte" class="toc"><code>lte</code></h1></header> +<p>Returns <em>true</em> if the first parameter is lte the second one.</p> + +<p><strong>Example:</strong> <code>less than or equal to[5|2]</code></p> + + + + <section class="section"> +<header><h1 id="h_183" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The first integer to compare.</td> + </tr> + + + <tr> + <td>1</td> + <td>The second integer to compare.</td> + </tr> + </table> + +</section> + +</section> + + + + + <section class="section"> +<header><h1 id="m_match" class="toc"><code>match</code></h1></header> +<p>Checks a string against a regular expression.</p> + +<p><strong>Example:</strong> <code>?[match[Hello!|/^hell/i]|This is always displayed]</code></p> + + + + <section class="section"> +<header><h1 id="h_185" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The string to check.</td> + </tr> + + + <tr> + <td>1</td> + <td>The regular expression to match against the string.</td> + </tr> + + + <tr> + <td>2</td> + <td>The contents to expand if the string matches.</td> + </tr> + </table> + +</section> + + +<section class="section"> +<header><h1 id="h_186" class="notoc">Remarks</h1></header> +<p>This macro must be used with the <a href="#m_condition"><code>condition</code></a> macro.</p> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_macro_" class="toc"><code>macro:</code></h1></header> +<p>Defines a macro.</p> +<strong>Aliases:</strong> <code>%:</code> +<p><strong>Example:</strong> <code>%:[test|"<em>test: #{value}</em>"]</code></p> + + + + <section class="section"> +<header><h1 id="h_188" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The name of the new macro.</td> + </tr> + + + <tr> + <td>1</td> + <td>The macro definition (Ruby code).</td> + </tr> + </table> + +</section> + + +<section class="section"> +<header><h1 id="h_189" class="notoc">Remarks</h1></header> +<ul> +<li> +<p>This macro cannot be used in <a href="/glyph/book/compiling/programmatic_usage.html#modes">safe mode</a>.</p> +</li> + <li>The new macro can only be used <em>after</em> its declaration.</li> +</ul> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_multiply" class="toc"><code>multiply</code></h1></header> +<p>Multiplies two or more integers together.</p> + +<p><strong>Example:</strong> <code>add[3|5|9]</code></p> + +</section> + + + + <section class="section"> +<header><h1 id="m_not" class="toc"><code>not</code></h1></header> +<p>Conditional <code>not</code> operator, to be used with the <a href="#m_condition"><code>condition</code></a> macro.</p> + +<p><strong>Example:</strong> <code>?[not[false]|This is always displayed.]</code></p> + + + + <section class="section"> +<header><h1 id="h_192" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The expression to negate</td> + </tr> + </table> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_output_" class="toc"><code>output?</code></h1></header> +<p>Evaluates to true if Glyph is generating output in the specified format(s).</p> + +<p><strong>Example:</strong> <code>?[output?[web|web5]|This text is printed only when generating web or web5 output.]</code></p> + + + + <section class="section"> +<header><h1 id="h_194" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0, ...</td> + <td>a valid output target.</td> + </tr> + </table> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_or" class="toc"><code>or</code></h1></header> +<p>Conditional <code>or</code> operator, to be used with the <a href="#m_condition"><code>condition</code></a> macro.</p> + +<p><strong>Example:</strong> <code>?[or[true|false]|This is always displayed.]</code></p> + + + + <section class="section"> +<header><h1 id="h_196" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The first expression to test</td> + </tr> + + <tr> + <td>1</td> + <td>The second expression to test</td> + </tr> + </table> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_define_" class="toc"><code>define:</code></h1></header> +<p>Defines a new macro in Glyph code (for more information, see <a href="/glyph/book/extending/interpreting.html#rewriting">Defining macros using Glyph</a>)</p> +<strong>Aliases:</strong> <code>def:</code> + + + <section class="section"> +<header><h1 id="h_198" class="notoc">Example</h1></header> +<div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span>def:[factorial| +<span class="line-numbers"> <a href="#n2" name="n2">2</a></span> ?[ +<span class="line-numbers"> <a href="#n3" name="n3">3</a></span> eq[{{0}}|0]|1| +<span class="line-numbers"> <a href="#n4" name="n4">4</a></span> multiply[ +<span class="line-numbers"> <a href="#n5" name="n5">5</a></span> {{0}} | factorial[subtract[{{0}}|1]] +<span class="line-numbers"> <a href="#n6" name="n6">6</a></span> ] +<span class="line-numbers"> <a href="#n7" name="n7">7</a></span> ] +<span class="line-numbers"> <a href="#n8" name="n8">8</a></span>] +<span class="line-numbers"> <a href="#n9" name="n9">9</a></span>factorial[5]</pre></div> +</div> + +</section> + + + + <section class="section"> +<header><h1 id="h_199" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The name of the new macro.</td> + </tr> + + + <tr> + <td>0</td> + <td>The macro definition (Glyph code).</td> + </tr> + </table> + +</section> + + +<section class="section"> +<header><h1 id="h_200" class="notoc">Remarks</h1></header> +<ul> + <li>The new macro can only be used <em>after</em> its declaration.</li> +<li> +<p>This macro cannot be used in <a href="/glyph/book/compiling/programmatic_usage.html#modes">safe mode</a>.</p> +</li> +</ul> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_ruby" class="toc"><code>ruby</code></h1></header> +<p>Evaluates its value as Ruby code within the context of the <a href="http://rubydoc.info/gems/glyph/Glyph">Glyph</a> module.</p> +<strong>Aliases:</strong> <code>%</code> + + +<examples> +%[Time.now] +%[Glyph::VERSION] +</examples> + + <section class="section"> +<header><h1 id="h_202" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The Ruby code to evaluate.</td> + </tr> + </table> + +</section> + + +<section class="section"> +<header><h1 id="h_203" class="notoc">Remarks</h1></header> +<p>This macro cannot be used in <a href="/glyph/book/compiling/programmatic_usage.html#modes">safe mode</a>.</p> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_s" class="toc"><code>s</code></h1></header> +<p>Can be used to dispatch almost any instance method of the ruby <a href="http://rubydoc.info/stdlib/core/1.9.2/String">String</a> class.</p> + + + +<examples> +s/match[This is a test string|/test/] +s/sub[This is a test string|/a test/|another test] +</examples> + +</section> + + + + <section class="section"> +<header><h1 id="m_snippet" class="toc"><code>snippet</code></h1></header> +<p>Returns the value of a snippet.</p> +<strong>Aliases:</strong> <code>&</code> +<p><strong>Example:</strong> <code>&[glang]</code></p> + + + + <section class="section"> +<header><h1 id="h_206" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The ID of the snippet to retrieve.</td> + </tr> + </table> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_snippet_" class="toc"><code>snippet:</code></h1></header> +<p>Defines a snippet.</p> +<strong>Aliases:</strong> <code>&:</code> +<p><strong>Example:</strong> <code>&:[test|This is a test]</code></p> + + + + <section class="section"> +<header><h1 id="h_208" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The ID of the new snippet.</td> + </tr> + + + <tr> + <td>1</td> + <td>The contents of the new snippet.</td> + </tr> + </table> + +</section> + + +<section class="section"> +<header><h1 id="h_209" class="notoc">Remarks</h1></header> +<p>The new snippet can only be used <em>after</em> its declaration.</p> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_subtract" class="toc"><code>subtract</code></h1></header> +<p>Subtracts two or more integers together.</p> + +<p><strong>Example:</strong> <code>add[10|5|2]</code></p> + +</section> + + + + <section class="section"> +<header><h1 id="m_xml" class="toc"><code>xml</code></h1></header> +<p>When used composed with another macro, it can be used to render arbitrary raw <span class="caps">XML</span> tags.</p> + +<p><strong>Example:</strong> <code>xml/img[@src[test.png]@alt[A Test image]]</code></p> + +</section> + + + + <section class="section"> +<header><h1 id="m_while" class="toc"><code>while</code></h1></header> +<p>Keeps evaluating the second parameter while a condition is satisfied.</p> + + + + <section class="section"> +<header><h1 id="h_213" class="notoc">Example</h1></header> +<div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span>let[ +<span class="line-numbers"> <a href="#n2" name="n2">2</a></span> @count[5] +<span class="line-numbers"> <a href="#n3" name="n3">3</a></span> @text[-] +<span class="line-numbers"> <a href="#n4" name="n4">4</a></span> while[gt[@[count]|0]| +<span class="line-numbers"> <a href="#n5" name="n5">5</a></span> @:[text|s/concat[@[text]|@[count]-]] +<span class="line-numbers"> <a href="#n6" name="n6">6</a></span> @:[count|subtract[@[count]|1]] +<span class="line-numbers"> <a href="#n7" name="n7">7</a></span> ] +<span class="line-numbers"> <a href="#n8" name="n8">8</a></span> @[text] --[Outputs: -5-4-3-2-1-] +<span class="line-numbers"> <a href="#n9" name="n9">9</a></span>]</pre></div> +</div> + +</section> + + + + <section class="section"> +<header><h1 id="h_214" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The condition to check.</td> + </tr> + + + <tr> + <td>1</td> + <td>The code to evaluate while the condition is satisfied.</td> + </tr> + </table> + +</section> + +</section> + +<nav class="navigation"><a href="/glyph/book/ref_commands.html">← Command Reference</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/macros/macros_block.html">Block Macros →</a></nav>
A
contents/glyph/book/macros/macros_filters.html
@@ -0,0 +1,243 @@
+----- +title: "Glyph – Filter Macros" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/macros/macros_inline.html">← Inline Macros</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/macros/macros_structure.html">Structure Macros →</a></nav> + + + <section class="section"> +<header><h1 id="m_markdown" class="toc"><code>markdown</code></h1></header> +<p>Uses a Markdown converter (BlueCloth, RDiscount, Maruku or Kramdown) to transform the value into <span class="caps">HTML</span> if the <a href="/glyph/book/config/output.html#cfg_output"><code>output.*.filter_target</code></a> setting is set to <code>html</code>.</p> +<p>If the <a href="/glyph/book/config/options.html#s_options_filters_by_file_extension"><code>options.filters_by_file_extension</code></a> setting is <code>true</code>, this macro is called automatically on <a href="/glyph/book/macros/macros_core.html#m_include">included</a> files with a <code>.markdown</code> or a <code>.md</code> extension.</p> +<strong>Aliases:</strong> <code>md</code> +<p><strong>Example:</strong> <code>markdown[This is *emphasized* text.]</code></p> + + + + <section class="section"> +<header><h1 id="h_252" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The Markdown text to filter.</td> + </tr> + </table> + +</section> + +</section> + + + + + <section class="section"> +<header><h1 id="m_markdown_section" class="toc"><code>markdown_section</code></h1></header> +<p>Creates a section (see <a href="/glyph/book/macros/macros_structure.html#m_section"><code>section</code></a> macro) whose content can be formatted with markdown markup.</p> +<strong>Aliases:</strong> <code>§md, md_section</code> + + + <section class="section"> +<header><h1 id="h_254" class="notoc">Example</h1></header> +<div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>markdown_section[ +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> @title[Test Section] +<span class="line-numbers"><a href="#n3" name="n3">3</a></span> @id[test] +<span class="line-numbers"><a href="#n4" name="n4">4</a></span>Some *markdown* text. +<span class="line-numbers"><a href="#n5" name="n5">5</a></span>]</pre></div> +</div> + +</section> + + + + <section class="section"> +<header><h1 id="h_255" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The text of the section</td> + </tr> + </table> + +</section> + + + <section class="section"> +<header><h1 id="h_256" class="notoc">Attributes</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Attribute</th> + <th>Description</th> + </tr> +<tr> + <td>title</td> + <td>The title of the section <em>(optional)</em></td> + </tr> + + + <tr> + <td>id</td> + <td>The ID of the section <em>(optional)</em></td> + </tr> + + + <tr> + <td>notoc</td> + <td>If not blank, the header will not appear in the Table of Contents. <em>(optional)</em></td> + </tr> + </table> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_textile" class="toc"><code>textile</code></h1></header> +<p>Uses the RedCloth gem to transform the value into <span class="caps">HTML</span> or LaTeX, depending on the value of the <a href="/glyph/book/config/output.html#cfg_output"><code>output.*.filter_target</code></a>.</p> +<p>If the <a href="/glyph/book/config/options.html#s_options_filters_by_file_extension"><code>options.filters_by_file_extension</code></a> setting is <code>true</code>, this macro is called automatically on <a href="/glyph/book/macros/macros_core.html#m_include">included</a> files with a <code>.textile</code> or a <code>.txt</code> extension.</p> +<strong>Aliases:</strong> <code>txt</code> +<p><strong>Example:</strong> <code>textile[This is a *strong emphasis*.]</code></p> + + + + <section class="section"> +<header><h1 id="h_258" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The Textile text to filter.</td> + </tr> + </table> + +</section> + +</section> + + + + + <section class="section"> +<header><h1 id="m_textile_section" class="toc"><code>textile_section</code></h1></header> +<p>Creates a section (see <a href="/glyph/book/macros/macros_structure.html#m_section"><code>section</code></a> macro) whose content can be formatted with textile markup.</p> +<strong>Aliases:</strong> <code>§txt, txt_section</code> + + + <section class="section"> +<header><h1 id="h_260" class="notoc">Example</h1></header> +<div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>textile_section[ +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> @title[Test Section] +<span class="line-numbers"><a href="#n3" name="n3">3</a></span> @id[test] +<span class="line-numbers"><a href="#n4" name="n4">4</a></span>Some *textile* text. +<span class="line-numbers"><a href="#n5" name="n5">5</a></span>]</pre></div> +</div> + +</section> + + + + <section class="section"> +<header><h1 id="h_261" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The text of the section</td> + </tr> + </table> + +</section> + + + <section class="section"> +<header><h1 id="h_262" class="notoc">Attributes</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Attribute</th> + <th>Description</th> + </tr> +<tr> + <td>title</td> + <td>The title of the section <em>(optional)</em></td> + </tr> + + + <tr> + <td>id</td> + <td>The ID of the section <em>(optional)</em></td> + </tr> + + + <tr> + <td>notoc</td> + <td>If not blank, the header will not appear in the Table of Contents. <em>(optional)</em></td> + </tr> + </table> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_highlight" class="toc"><code>highlight</code></h1></header> +<p>Highlights a piece of source code according to the specified language. <span class="fmi">for more information on <mark>code highligting</mark>, see <a href="/glyph/book/text_editing/code.html#source_code">Source Code</a></span>.</p> + + + + <section class="section"> +<header><h1 id="h_264" class="notoc">Example</h1></header> +<div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>highlight[ruby| +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> def hello +<span class="line-numbers"><a href="#n3" name="n3">3</a></span> puts "Hello World" +<span class="line-numbers"><a href="#n4" name="n4">4</a></span> end +<span class="line-numbers"><a href="#n5" name="n5">5</a></span>]</pre></div> +</div> + +</section> + + + + <section class="section"> +<header><h1 id="h_265" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>A programming language supported by the underlying highlighter.</td> + </tr> + + + <tr> + <td>1</td> + <td>The code to highlight.</td> + </tr> + </table> + +</section> + +</section> + +<nav class="navigation"><a href="/glyph/book/macros/macros_inline.html">← Inline Macros</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/macros/macros_structure.html">Structure Macros →</a></nav>
A
contents/glyph/book/macros/macros_inline.html
@@ -0,0 +1,141 @@
+----- +title: "Glyph – Inline Macros" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/macros/macros_block.html">← Block Macros</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/macros/macros_filters.html">Filter Macros →</a></nav> + + <section class="section"> +<header><h1 id="m_anchor" class="toc"><code>anchor</code></h1></header> +<p>Creates a named anchor (or bookmark).</p> +<strong>Aliases:</strong> <code>bookmark, #</code> +<p><strong>Example:</strong> <code>#[test|Test Bookmark]</code></p> + + + + <section class="section"> +<header><h1 id="h_242" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The identifier of the bookmark</td> + </tr> + + + <tr> + <td>1</td> + <td>The contents of the bookmark <em>(optional)</em></td> + </tr> + </table> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_draftcomment" class="toc"><code>draftcomment</code></h1></header> +<p>If the <a href="/glyph/book/config/document.html#s_document_draft"><code>document.draft</code></a> setting is set to <code>true</code>, displays a draft comment within the document.</p> +<strong>Aliases:</strong> <code>dc</code> +<p><strong>Example:</strong> <code>dc[This is printed only in draft documents.]</code></p> + + + + <section class="section"> +<header><h1 id="h_244" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The text of the comment.</td> + </tr> + </table> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_fmi" class="toc"><code>fmi</code></h1></header> +<p>Creates a <em>For More Information</em> link (for an example usage, see the <a href="#m_link"><code>link</code></a> macro).</p> + +<p><strong>Example:</strong> <code>fmi[creating links|#links]</code></p> + + + + <section class="section"> +<header><h1 id="h_246" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The object that needs additional explanation.</td> + </tr> + + + <tr> + <td>1</td> + <td>A valid bookmark within the document.</td> + </tr> + </table> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_link" class="toc"><code>link</code></h1></header> +<p>Creates an hyperlink (<span class="fmi">for more information on <mark>creating links</mark>, see <a href="/glyph/book/text_editing/links.html#links">Links and Bookmarks</a></span>).</p> +<strong>Aliases:</strong> <code>=></code> +<p><strong>Example:</strong> <code>=>[http://www.h3rald.com|H3RALD.com]</code></p> + + + + <section class="section"> +<header><h1 id="h_248" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>A valid bookmark within the document or an URL.</td> + </tr> + + + <tr> + <td>1</td> + <td>The text of the link <em>(optional)</em>.</td> + </tr> + </table> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_todo" class="toc"><code>todo</code></h1></header> +<p>Saves the value as a <span class="caps">TODO</span> item, which can be printed using the <a href="/glyph/book/ref_commands.html#c_todo"><code>todo</code></a> command and included in the document if the <a href="/glyph/book/config/document.html#s_document_draft"><code>document.draft</code></a> setting is set to <code>true</code>.</p> +<strong>Aliases:</strong> <code>!</code> +<p><strong>Example:</strong> <code>todo[Remember to do this.]</code></p> + +</section> + +<nav class="navigation"><a href="/glyph/book/macros/macros_block.html">← Block Macros</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/macros/macros_filters.html">Filter Macros →</a></nav>
A
contents/glyph/book/macros/macros_structure.html
@@ -0,0 +1,371 @@
+----- +title: "Glyph – Structure Macros" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/macros/macros_filters.html">← Filter Macros</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/config/document.html"><code>document.*</code> →</a></nav> + + <section class="section"> +<header><h1 id="m_article" class="toc"><code>article</code></h1></header> +<p>Used to create a simple article. By default, it includes the following macros:</p> +<ul> + <li><code>document</code> + <ul> + <li><code>head</code> + <ul> + <li><code>style[default.css]</code></li> + </ul></li> + <li><code>body</code> + <ul> + <li><code>halftitlepage</code> + <ul> + <li><code>title</code></li> + <li><code>pubdate</code></li> + <li><code>subtitle</code></li> + <li><code>author</code></li> + </ul></li> + </ul></li> + </ul></li> +</ul> + + + + + + <section class="section"> +<header><h1 id="h_268" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The article contents.</td> + </tr> + </table> + +</section> + + + <section class="section"> +<header><h1 id="h_269" class="notoc">Attributes</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Attribute</th> + <th>Description</th> + </tr> +<tr> + <td>pre-title</td> + <td>Contents to include before the <a href="/glyph/book/macros/macros_block.html#m_title"><code>title</code></a> macro.</td> + </tr> + + + <tr> + <td>post-title</td> + <td>Contents to include after the <a href="/glyph/book/macros/macros_block.html#m_title"><code>title</code></a> macro.</td> + </tr> + + + <tr> + <td>head</td> + <td>Contents to include instead of the default <code>head</code> macro.</td> + </tr> + + + <tr> + <td>pubdate</td> + <td>Contents to include instead of the default <code>pubdate</code> macro.</td> + </tr> + + + <tr> + <td>halftitlepage</td> + <td>Contents to include instead of the default <code>halftitlepage</code> macro.</td> + </tr> + </table> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_book" class="toc"><code>book</code></h1></header> +<p>Used to create a book. By default, it includes the following macros:</p> +<ul> + <li><code>document</code> + <ul> + <li><code>head</code> + <ul> + <li><code>style[default.css]</code></li> + </ul></li> + <li><code>body</code> + <ul> + <li><code>titlepage</code> + <ul> + <li><code>title</code></li> + <li><code>pubdate</code></li> + <li><code>subtitle</code></li> + <li><code>revision</code></li> + <li><code>author</code></li> + </ul></li> + </ul></li> + </ul></li> +</ul> + + + + + + <section class="section"> +<header><h1 id="h_271" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The article contents.</td> + </tr> + </table> + +</section> + + + <section class="section"> +<header><h1 id="h_272" class="notoc">Attributes</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Attribute</th> + <th>Description</th> + </tr> +<tr> + <td>pre-title</td> + <td>Contents to include before the <a href="/glyph/book/macros/macros_block.html#m_title"><code>title</code></a> macro.</td> + </tr> + + + <tr> + <td>post-title</td> + <td>Contents to include after the <a href="/glyph/book/macros/macros_block.html#m_title"><code>title</code></a> macro.</td> + </tr> + + + <tr> + <td>head</td> + <td>Contents to include instead of the default <code>head</code> macro.</td> + </tr> + + + <tr> + <td>pubdate</td> + <td>Contents to include instead of the default <code>pubdate</code> macro.</td> + </tr> + + + <tr> + <td>titlepage</td> + <td>Contents to include instead of the default <code>titlepage</code> macro.</td> + </tr> + + + <tr> + <td>frontmatter</td> + <td>Contents to include within a <code>frontmatter</code> macro.</td> + </tr> + + + <tr> + <td>bodymatter</td> + <td>Contents to include within a <code>bodymatter</code> macro.</td> + </tr> + + + <tr> + <td>backmatter</td> + <td>Contents to include within a <code>backmatter</code> macro.</td> + </tr> + </table> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_document" class="toc"><code>document</code></h1></header> +<p>Creates an <code><html></code> tag and a <span class="caps">DOCTYPE</span> declaration. Called internally by the <a href="#m_book"><code>book</code></a> macro and the <a href="#m_article"><code>article</code></a> macro.</p> + + + + + + <section class="section"> +<header><h1 id="h_274" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The document contents.</td> + </tr> + </table> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_head" class="toc"><code>head</code></h1></header> +<p>Creates a <code><head></code> tag, pre-populated with <code>title</code> and author/copyright <code><meta></code> tags.</p> + + + + + + <section class="section"> +<header><h1 id="h_276" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The head contents.</td> + </tr> + </table> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_section" class="toc"><code>section</code></h1></header> +<p>Creates a section (<code><div></code> or <code><section></code> tag).</p> +<strong>Aliases:</strong> <code>acknowledgement, addendum, afterword, appendix, bibliography, chapter, colophon, dedication, epilogue, foreword, glossary, imprint, index, inspiration, introduction, lof, lot, part, postscript, preface, prologue, promotion, references, section, section, volume</code> + + + <section class="section"> +<header><h1 id="h_278" class="notoc">Example</h1></header> +<div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>section[ +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> @title[Test Section] +<span class="line-numbers"><a href="#n3" name="n3">3</a></span> @id[test] +<span class="line-numbers"><a href="#n4" name="n4">4</a></span>... +<span class="line-numbers"><a href="#n5" name="n5">5</a></span>]</pre></div> +</div> + +</section> + + + + <section class="section"> +<header><h1 id="h_279" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The text of the section</td> + </tr> + </table> + +</section> + + + <section class="section"> +<header><h1 id="h_280" class="notoc">Attributes</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Attribute</th> + <th>Description</th> + </tr> +<tr> + <td>title</td> + <td>The title of the section <em>(optional)</em></td> + </tr> + + + <tr> + <td>id</td> + <td>The ID of the section <em>(optional)</em></td> + </tr> + + + <tr> + <td>notoc</td> + <td>If not blank, the header will not appear in the Table of Contents. <em>(optional)</em></td> + </tr> + </table> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_style" class="toc"><code>style</code></h1></header> +<p>Embeds the content of a <span class="caps">CSS</span> or Sass file within a <code><style></code> tag (<span class="fmi">for more information on <mark>stylesheets</mark>, see <a href="/glyph/book/text_editing/stylesheets.html#stylesheets">Adding Stylesheets</a></span>).</p> + +<p><strong>Example:</strong> <code>style[default.css]</code></p> + + + + <section class="section"> +<header><h1 id="h_282" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The stylesheet file to embed.</td> + </tr> + </table> + +</section> + +</section> + + + + <section class="section"> +<header><h1 id="m_toc" class="toc"><code>toc</code></h1></header> +<p>Generates a <em>Table of Contents</em> based on how sections are nested in the current document.</p> + +<p><strong>Example:</strong> <code>toc[1]</code></p> + + + + <section class="section"> +<header><h1 id="h_284" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td>0</td> + <td>The maximum header depth of the TOC <em>(optional)</em>.</td> + </tr> + </table> + +</section> + +</section> + +<nav class="navigation"><a href="/glyph/book/macros/macros_filters.html">← Filter Macros</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/config/document.html"><code>document.*</code> →</a></nav>
A
contents/glyph/book/ref_commands.html
@@ -0,0 +1,365 @@
+----- +title: "Glyph – Command Reference" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/troubleshooting/errors_macro.html">← Macro Errors</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/macros/macros_core.html">Core Macros →</a></nav> +<p>Glyph’s command-line interface has been built using the <a href="http://github.com/davetron5000/gli">gli</a> (Git-like interface) gem. Therefore, Glyph commands are all written like this:</p> +<p><strong>glyph</strong> <em>global_options</em> <strong>command</strong> <em>options</em> <em>parameters</em></p> +<p>Where:</p> +<ul> + <li><em>global_options</em> and <em>options</em> are in the form: <code>-n</code> <em>value</em> or <code>--name=</code><em>value</em>, e.g. <code>-f pdf</code> or <code>--format=pdf</code></li> + <li><em>parameters</em> are separated by whitespaces, and can be wrapped in quotes.</li> +</ul> +<section class="section"> +<header><h1 id="h_115" class="toc">Global Options</h1></header> +<section class="section"> +<header><h1 id="debug_switch" class="toc"><code>-d</code>, <code>--debug</code></h1></header> +<p>If specified, the command is executed in debug mode and additional diagnostic information is printed on the screen.</p> + +</section> + <section class="section"> +<header><h1 id="help_switch" class="toc"><code>-h</code>, <code>--help</code></h1></header> +<p>Displays help on the program.</p> + +</section> + +</section> +<section class="section"> +<header><h1 id="c_add" class="toc"><code>add</code></h1></header> +<p>Creates a new text file in the <code>text/</code> folder.</p> + <p><strong>Example:</strong> <code>glyph add introduction.textile</code></p> + + <section class="section"> +<header><h1 id="h_119" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td><em>file_name</em></td> + <td>The name (or relative path) of the new file to be created.</td> + </tr> + </table> + +</section> + +</section> +<section class="section"> +<header><h1 id="c_compile" class="toc"><code>compile</code></h1></header> +<p>Compiles a Glyph document into an output file. If no options are specified, the <code>document.glyph</code> file is used as source to produce a standalone HTML file.</p> + <p><strong>Example:</strong> <code>glyph compile -f pdf</code></p> + + <section class="section"> +<header><h1 id="h_121" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td><em>source</em></td> + <td>The source glyph file to compile <em>(Optional)</em>.</td> + </tr> + + + <tr> + <td><em>destination</em></td> + <td>The destination file <em>(Optional)</em>.</td> + </tr> + </table> + +</section> + + + <section class="section"> +<header><h1 id="h_122" class="notoc">Options</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Option</th> + <th>Description</th> + </tr> +<tr> + <td><code>-s</code> (<code>--source</code>)</td> + <td> +The source file to compile. + <strong>Default Value:</strong> <code>document.glyph</code> + </td> + </tr> + + + <tr> + <td><code>-f</code> (<code>--format</code>)</td> + <td> +The format of the output file. + <strong>Default Value:</strong> <code>html</code> + *Possible Values:* @html, pdf@ + </td> + </tr> + + + <tr> + <td><code>-a</code> (<code>--auto</code>)</td> + <td> +If specified, enable <a href="/glyph/book/compiling/compiling.html#auto_regeneration">auto regeneration</a> (requires the <a href="http://rubygems.org/gems/directory_watcher">directory_watcher</a> gem to be installed). + </td> + </tr> + </table> + +</section> + +</section> +<section class="section"> +<header><h1 id="c_config" class="toc"><code>config</code></h1></header> +Gets or sets a configuration setting in the project or global configuration file (<span class="fmi">for more information on <mark>configuration files</mark>, see <a href="/glyph/book/getting_started/configuration.html#cfg">Project Configuration</a></span>). + <section class="section"> +<header><h1 id="h_124" class="notoc">Examples</h1></header> +<p> +<code>glyph config document.filename</code> +</p> + <p> +<code>glyph config -g document.author "Fabio Cevasco"</code> +</p> + +</section> + + <section class="section"> +<header><h1 id="h_125" class="notoc">Options</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Option</th> + <th>Description</th> + </tr> +<tr> + <td><code>-g</code> (<code>--global</code>)</td> + <td> +If specified, the global configuration file is processed instead of the project file. + <strong>Default Value:</strong> <code>false</code> + </td> + </tr> + </table> + +</section> + + + <section class="section"> +<header><h1 id="h_126" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td><em>setting</em></td> + <td>The name of a valid <a href="/glyph/book/document.html#cfg_ref">configuration setting</a>.</td> + </tr> + + + <tr> + <td><em>value</em></td> + <td>The new value of the configuration setting.</td> + </tr> + </table> + +</section> + +</section> +<section class="section"> +<header><h1 id="c_help" class="toc"><code>help</code></h1></header> +Prints information about all Glyph commands or about one specific command. + <section class="section"> +<header><h1 id="h_128" class="notoc">Examples</h1></header> +<p> +<code>glyph help</code> +</p> + <p> +<code>glyph help compile</code> +</p> + +</section> + + <section class="section"> +<header><h1 id="h_129" class="notoc">Parameters</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Parameter</th> + <th>Description</th> + </tr> +<tr> + <td><em>command</em></td> + <td>A valid Glyph command.</td> + </tr> + </table> + +</section> + +</section> +<section class="section"> +<header><h1 id="c_init" class="toc"><code>init</code></h1></header> +Creates a new Glyph project in the current directory (if empty). + <p><strong>Example:</strong> <code>glyph init</code></p> + +</section> +<section class="section"> +<header><h1 id="c_outline" class="toc"><code>outline</code></h1></header> +Display an outline of the current document. + + <section class="section"> +<header><h1 id="h_132" class="notoc">Options</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Option</th> + <th>Description</th> + </tr> +<tr> + <td><code>-l</code> (<code>--limit</code>)</td> + <td> +Only display headers until the specified level. + </td> + </tr> + + + <tr> + <td><code>-i</code> (<code>--ids</code>)</td> + <td> +Display section IDs. + </td> + </tr> + + + <tr> + <td><code>-f</code> (<code>--files</code>)</td> + <td> +Display file names. + </td> + </tr> + + + <tr> + <td><code>-t</code> (<code>--titles</code>)</td> + <td> +Display section titles. + </td> + </tr> + </table> + +</section> + + <section class="section"> +<header><h1 id="h_133" class="notoc">Examples</h1></header> +<p> +<code>glyph outline -it -l 1</code> +</p> + <p> +<code>glyph outline -l 2</code> +</p> + <p> +<code>glyph outline -f</code> +</p> + +</section> + +</section> +<section class="section"> +<header><h1 id="c_stats" class="toc"><code>stats</code></h1></header> +<p>Displays project statistics (<span class="fmi">for more information on <mark>this command</mark>, see <a href="/glyph/book/document.html#stats">Document Statistics</a></span>).</p> + <section class="section"> +<header><h1 id="h_135" class="notoc">Examples</h1></header> +<p> +<code>glyph stats -m</code> +</p> + <p> +<code>glyph stats --link=h3rald.com</code> +</p> + +</section> + + <section class="section"> +<header><h1 id="h_136" class="notoc">Options</h1></header> +<table style="width:100%;"> + <tr> + <th style="width:30%">Option</th> + <th>Description</th> + </tr> +<tr> + <td><code>-b</code> (<code>--bookmarks</code>)</td> + <td> +If specified, general statistics about bookmarks are displayed (see <a href="/glyph/book/stats/bookmarks.html#stats_bookmarks">Bookmark Statistics</a>). + </td> + </tr> + + + <tr> + <td><code>--bookmark</code></td> + <td> +Display detailed statistics about the specified bookmark. + </td> + </tr> + + + <tr> + <td><code>-f</code> (<code>--files</code>)</td> + <td> +If specified, general statistics about project files are displayed. + </td> + </tr> + + + <tr> + <td><code>-l</code> (<code>--links</code>)</td> + <td> +If specified, general statistics about links are displayed (see <a href="/glyph/book/stats/links.html#stats_links">Link Statistics</a>). + </td> + </tr> + + + <tr> + <td><code>--link</code></td> + <td> +Display detailed statistics about all links whose target matches the specified regular expression. + </td> + </tr> + + + <tr> + <td><code>-m</code> (<code>--macros</code>)</td> + <td> +If specified, general statistics about macros are displayed (see <a href="/glyph/book/stats/macros.html#stats_macros">Macro Statistics</a>). + </td> + </tr> + + + <tr> + <td><code>--macro</code></td> + <td> +Display detailed statistics about the specified macro. + </td> + </tr> + + + <tr> + <td><code>-s</code> (<code>--snippets</code>)</td> + <td> +If specified, general statistics about snippets are displayed (see <a href="/glyph/book/stats/snippets.html#stats_snippets">Snippet Statistics</a>). + </td> + </tr> + + + <tr> + <td><code>--snippet</code></td> + <td> +Display detailed statistics about the specified snippet. + </td> + </tr> + </table> + +</section> + +</section> +<section class="section"> +<header><h1 id="c_todo" class="toc"><code>todo</code></h1></header> +Prints all the todo items saved using the <a href="/glyph/book/macros/macros_inline.html#m_todo"><code>todo</code></a> macro. + <p><strong>Example:</strong> <code>glyph todo</code></p> + +</section> +<nav class="navigation"><a href="/glyph/book/troubleshooting/errors_macro.html">← Macro Errors</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/macros/macros_core.html">Core Macros →</a></nav>
A
contents/glyph/book/stats/bookmarks.html
@@ -0,0 +1,67 @@
+----- +title: "Glyph – Bookmark Statistics" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/stats/snippets.html">← Snippet Statistics</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/stats/links.html">Link Statistics →</a></nav> + + <section class="section"> +<header><h1 id="h_72" class="toc">Displaying stats about all bookmarks</h1></header> +<p>To display statistics about all bookmarks, execute <code>glyph stats --bookmarks</code>. Glyph displays something like this:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span>===== Bookmarks +<span class="line-numbers"> <a href="#n2" name="n2">2</a></span>-- Total Bookmarks: 241 +<span class="line-numbers"> <a href="#n3" name="n3">3</a></span>-- Total Referenced Bookmarks: 89 +<span class="line-numbers"> <a href="#n4" name="n4">4</a></span>-- Total Unreferenced Bookmarks: 155 +<span class="line-numbers"> <a href="#n5" name="n5">5</a></span>-- Bookmarks: +<span class="line-numbers"> <a href="#n6" name="n6">6</a></span> attribute_intro auto_regeneration c_add c_compile c_config +<span class="line-numbers"> <a href="#n7" name="n7">7</a></span> c_help c_init c_outline c_todo cfg +<span class="line-numbers"> <a href="#n8" name="n8">8</a></span> cfg_document cfg_filters cfg_ref cmd_ref compile +<span class="line-numbers"> <a href="#n9" name="n9">9</a></span>[...] +<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span>-- Referenced Bookmarks: +<span class="line-numbers"><a href="#n11" name="n11">11</a></span> - attribute_intro (1) +<span class="line-numbers"><a href="#n12" name="n12">12</a></span> - auto_regeneration (2) +<span class="line-numbers"><a href="#n13" name="n13">13</a></span> - c_add (2) +<span class="line-numbers"><a href="#n14" name="n14">14</a></span> - c_compile (10) +<span class="line-numbers"><a href="#n15" name="n15">15</a></span> - c_config (6) +<span class="line-numbers"><a href="#n16" name="n16">16</a></span> - c_init (1) +<span class="line-numbers"><a href="#n17" name="n17">17</a></span> - c_outline (1) +<span class="line-numbers"><a href="#n18" name="n18">18</a></span>[...] +<span class="line-numbers"><a href="#n19" name="n19">19</a></span>-- Unreferenced Bookmarks: +<span class="line-numbers"><strong><a href="#n20" name="n20">20</a></strong></span> c_help cmd_ref expanded_values extending h_1 +<span class="line-numbers"><a href="#n21" name="n21">21</a></span> h_10 h_102 h_105 h_107 h_109 +<span class="line-numbers"><a href="#n22" name="n22">22</a></span> h_111 h_112 h_114 h_115 h_117 +<span class="line-numbers"><a href="#n23" name="n23">23</a></span>[...]</pre></div> +</div> + + <section class="section"> +<header><h1 id="h_73" class="toc">Remarks</h1></header> +<ul> + <li>All the automatically-generated bookmarks (like headers, starting with <code>h_</code>) are included as well.</li> +</ul> + +</section> + +</section> + + <section class="section"> +<header><h1 id="h_74" class="toc">Displaying stats about a single bookmark</h1></header> +<p>To display statistics about a single bookmark (e.g. <code>rubydoc</code>), execute <code>glyph stats --bookmark=c_config</code>. Glyph displays something like this:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>===== Bookmark 'c_config' (header) +<span class="line-numbers"><a href="#n2" name="n2">2</a></span>-- Defined in: text/ref_commands.glyph +<span class="line-numbers"><a href="#n3" name="n3">3</a></span>-- Referenced in: +<span class="line-numbers"><a href="#n4" name="n4">4</a></span> - text/changelog.glyph (2) +<span class="line-numbers"><a href="#n5" name="n5">5</a></span> - text/getting_started/configuration.glyph (1) +<span class="line-numbers"><a href="#n6" name="n6">6</a></span> - text/troubleshooting/errors_command.glyph (3)</pre></div> +</div> + + <section class="section"> +<header><h1 id="h_75" class="toc">Remarks</h1></header> +<ul> + <li>Do not prepend the bookmark ID with <code>#</code>.</li> +</ul> + +</section> + +</section> +<nav class="navigation"><a href="/glyph/book/stats/snippets.html">← Snippet Statistics</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/stats/links.html">Link Statistics →</a></nav>
A
contents/glyph/book/stats/links.html
@@ -0,0 +1,108 @@
+----- +title: "Glyph – Link Statistics" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/stats/bookmarks.html">← Bookmark Statistics</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/internals.html">A quick look at Glyph's internals →</a></nav> + + <section class="section"> +<header><h1 id="h_77" class="toc">Displaying stats about all links</h1></header> +<p>To display statistics about all links, execute <code>glyph stats --links</code>. Glyph displays something like this:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span>===== Links +<span class="line-numbers"> <a href="#n2" name="n2">2</a></span>-- Total Internal Links: 89 +<span class="line-numbers"> <a href="#n3" name="n3">3</a></span>-- Internal Links +<span class="line-numbers"> <a href="#n4" name="n4">4</a></span> - #attribute_intro +<span class="line-numbers"> <a href="#n5" name="n5">5</a></span> - #auto_regeneration +<span class="line-numbers"> <a href="#n6" name="n6">6</a></span> - #c_add +<span class="line-numbers"> <a href="#n7" name="n7">7</a></span> - #c_compile +<span class="line-numbers"> <a href="#n8" name="n8">8</a></span> - #c_config +<span class="line-numbers"> <a href="#n9" name="n9">9</a></span> - #c_init +<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span> - #c_outline +<span class="line-numbers"><a href="#n11" name="n11">11</a></span> - #c_stats +<span class="line-numbers"><a href="#n12" name="n12">12</a></span> - #c_todo +<span class="line-numbers"><a href="#n13" name="n13">13</a></span> - #cfg +<span class="line-numbers"><a href="#n14" name="n14">14</a></span> - #cfg_document +<span class="line-numbers"><a href="#n15" name="n15">15</a></span> - #cfg_filters +<span class="line-numbers"><a href="#n16" name="n16">16</a></span>[...] +<span class="line-numbers"><a href="#n17" name="n17">17</a></span>-- Total External Links: 95 +<span class="line-numbers"><a href="#n18" name="n18">18</a></span>-- External Links +<span class="line-numbers"><a href="#n19" name="n19">19</a></span> - &[rubydoc]/Glyph +<span class="line-numbers"><strong><a href="#n20" name="n20">20</a></strong></span> - &[rubydoc]/Glyph/Document +<span class="line-numbers"><a href="#n21" name="n21">21</a></span> - &[rubydoc]/Glyph/Interpreter +<span class="line-numbers"><a href="#n22" name="n22">22</a></span> - &[rubydoc]/Glyph/Macro +<span class="line-numbers"><a href="#n23" name="n23">23</a></span> - &[rubydoc]/Glyph/Macro/Validators +<span class="line-numbers"><a href="#n24" name="n24">24</a></span> - &[rubydoc]/Glyph/Macro:update_source +<span class="line-numbers"><a href="#n25" name="n25">25</a></span> - &[rubydoc]/Glyph/MacroNode +<span class="line-numbers"><a href="#n26" name="n26">26</a></span> - &[rubydoc]/Glyph/Parser +<span class="line-numbers"><a href="#n27" name="n27">27</a></span> - &[rubydoc]/Glyph/SyntaxNode +<span class="line-numbers"><a href="#n28" name="n28">28</a></span> - &[rubydoc]/Macro +<span class="line-numbers"><a href="#n29" name="n29">29</a></span> - http://code.google.com/p/wkhtmltopdf/ +<span class="line-numbers"><strong><a href="#n30" name="n30">30</a></strong></span> - http://coderay.rubychan.de/ +<span class="line-numbers"><a href="#n31" name="n31">31</a></span> - http://coderay.rubychan.de/doc/classes/CodeRay/Encoders/HTML.html +<span class="line-numbers"><a href="#n32" name="n32">32</a></span>[...]</pre></div> +</div> + + <section class="section"> +<header><h1 id="h_78" class="toc">Remarks</h1></header> +<ul> + <li>The only criteria used to determine if a link is internal is whether it starts with a <code>#</code> or not.</li> +</ul> + +</section> + +</section> + + <section class="section"> +<header><h1 id="h_79" class="toc">Displaying stats about links matching a regular expression</h1></header> +<p>To display statistics about links matching a regular expression (e.g. <code>/c_/</code>), execute <code>glyph stats --link=c_</code>. Glyph displays something like this:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span>===== Links matching /c_/ +<span class="line-numbers"> <a href="#n2" name="n2">2</a></span>-- Total Links: 8 +<span class="line-numbers"> <a href="#n3" name="n3">3</a></span>-- Link Targets: +<span class="line-numbers"> <a href="#n4" name="n4">4</a></span> - #c_add +<span class="line-numbers"> <a href="#n5" name="n5">5</a></span> - #c_compile +<span class="line-numbers"> <a href="#n6" name="n6">6</a></span> - #c_config +<span class="line-numbers"> <a href="#n7" name="n7">7</a></span> - #c_init +<span class="line-numbers"> <a href="#n8" name="n8">8</a></span> - #c_outline +<span class="line-numbers"> <a href="#n9" name="n9">9</a></span> - #c_stats +<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span> - #c_todo +<span class="line-numbers"><a href="#n11" name="n11">11</a></span> - #esc_quot +<span class="line-numbers"><a href="#n12" name="n12">12</a></span>-- Details: +<span class="line-numbers"><a href="#n13" name="n13">13</a></span> - #c_add (2) +<span class="line-numbers"><a href="#n14" name="n14">14</a></span> - text/troubleshooting/errors_command.glyph (1) +<span class="line-numbers"><a href="#n15" name="n15">15</a></span> - text/troubleshooting/errors_generic.glyph (1) +<span class="line-numbers"><a href="#n16" name="n16">16</a></span> - #c_compile (10) +<span class="line-numbers"><a href="#n17" name="n17">17</a></span> - text/changelog.glyph (1) +<span class="line-numbers"><a href="#n18" name="n18">18</a></span> - text/compiling/compiling.glyph (2) +<span class="line-numbers"><a href="#n19" name="n19">19</a></span> - text/compiling/lite_mode.glyph (1) +<span class="line-numbers"><strong><a href="#n20" name="n20">20</a></strong></span> - text/compiling/programmatic_usage.glyph (2) +<span class="line-numbers"><a href="#n21" name="n21">21</a></span> - text/getting_started/create_project.glyph (1) +<span class="line-numbers"><a href="#n22" name="n22">22</a></span> - text/ref_config.glyph (1) +<span class="line-numbers"><a href="#n23" name="n23">23</a></span> - text/troubleshooting/errors_command.glyph (2) +<span class="line-numbers"><a href="#n24" name="n24">24</a></span> - #c_config (6) +<span class="line-numbers"><a href="#n25" name="n25">25</a></span> - text/changelog.glyph (2) +<span class="line-numbers"><a href="#n26" name="n26">26</a></span> - text/getting_started/configuration.glyph (1) +<span class="line-numbers"><a href="#n27" name="n27">27</a></span> - text/troubleshooting/errors_command.glyph (3) +<span class="line-numbers"><a href="#n28" name="n28">28</a></span> - #c_init (1) +<span class="line-numbers"><a href="#n29" name="n29">29</a></span> - text/troubleshooting/errors_generic.glyph (1) +<span class="line-numbers"><strong><a href="#n30" name="n30">30</a></strong></span> - #c_outline (1) +<span class="line-numbers"><a href="#n31" name="n31">31</a></span> - text/changelog.glyph (1) +<span class="line-numbers"><a href="#n32" name="n32">32</a></span> - #c_stats (1) +<span class="line-numbers"><a href="#n33" name="n33">33</a></span> - text/stats/stats.glyph (1) +<span class="line-numbers"><a href="#n34" name="n34">34</a></span> - #c_todo (1) +<span class="line-numbers"><a href="#n35" name="n35">35</a></span> - text/macros/macros_inline.glyph (1) +<span class="line-numbers"><a href="#n36" name="n36">36</a></span> - #esc_quot (2) +<span class="line-numbers"><a href="#n37" name="n37">37</a></span> - text/extending/macro_def.glyph (1) +<span class="line-numbers"><a href="#n38" name="n38">38</a></span> - text/text_editing/macro_intro.glyph (1)</pre></div> +</div> + + <section class="section"> +<header><h1 id="h_80" class="toc">Remarks</h1></header> +<ul> + <li>No distinction between external and internal targets is made.</li> +</ul> + +</section> + +</section> +<nav class="navigation"><a href="/glyph/book/stats/bookmarks.html">← Bookmark Statistics</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/internals.html">A quick look at Glyph's internals →</a></nav>
A
contents/glyph/book/stats/macros.html
@@ -0,0 +1,91 @@
+----- +title: "Glyph – Macro Statistics" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/stats/stats.html">← Using the stats command</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/stats/snippets.html">Snippet Statistics →</a></nav> + + <section class="section"> +<header><h1 id="h_62" class="toc">Displaying stats about all macros</h1></header> +<p>To display statistics about all macros, execute <code>glyph stats --macros</code>. Glyph displays something like this:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span>===== Macros +<span class="line-numbers"> <a href="#n2" name="n2">2</a></span>-- Total Macro Instances: 2497 +<span class="line-numbers"> <a href="#n3" name="n3">3</a></span>-- Total Macro Definitions: 65 +<span class="line-numbers"> <a href="#n4" name="n4">4</a></span>-- Total Macro Aliases: 57 +<span class="line-numbers"> <a href="#n5" name="n5">5</a></span>-- Total Used Macro Definitions: 56 +<span class="line-numbers"> <a href="#n6" name="n6">6</a></span>-- Macro Definitions: +<span class="line-numbers"> <a href="#n7" name="n7">7</a></span> #> $> %> alias: aliases +<span class="line-numbers"> <a href="#n8" name="n8">8</a></span> anchor and article author block_example +<span class="line-numbers"> <a href="#n9" name="n9">9</a></span> book box class codeblock comment +<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span> condition config config: config_table default +<span class="line-numbers"><a href="#n11" name="n11">11</a></span> document draftcomment eq error_table escape +<span class="line-numbers"><a href="#n12" name="n12">12</a></span> example examples features figure fmi +<span class="line-numbers"><a href="#n13" name="n13">13</a></span> head highlight image include issue +<span class="line-numbers"><a href="#n14" name="n14">14</a></span> link macro: markdown match navigation +<span class="line-numbers"><a href="#n15" name="n15">15</a></span> not note option or parameters +<span class="line-numbers"><a href="#n16" name="n16">16</a></span> pubdate ref_config ref_error ref_macro release +<span class="line-numbers"><a href="#n17" name="n17">17</a></span> revision rewrite: ruby section snippet +<span class="line-numbers"><a href="#n18" name="n18">18</a></span> snippet: stats_for style subtitle textile +<span class="line-numbers"><a href="#n19" name="n19">19</a></span> title toc todo values |xml| +<span class="line-numbers"><strong><a href="#n20" name="n20">20</a></strong></span> +<span class="line-numbers"><a href="#n21" name="n21">21</a></span>-- Used Macro Definitions: +<span class="line-numbers"><a href="#n22" name="n22">22</a></span> #> $> %> aliases anchor +<span class="line-numbers"><a href="#n23" name="n23">23</a></span> and author block_example book box +<span class="line-numbers"><a href="#n24" name="n24">24</a></span> class codeblock comment condition config +<span class="line-numbers"><a href="#n25" name="n25">25</a></span> config_table default document eq error_table +<span class="line-numbers"><a href="#n26" name="n26">26</a></span> escape example examples features figure +<span class="line-numbers"><a href="#n27" name="n27">27</a></span> fmi head highlight image include +<span class="line-numbers"><a href="#n28" name="n28">28</a></span> issue link note option or +<span class="line-numbers"><a href="#n29" name="n29">29</a></span> parameters pubdate ref_config ref_error ref_macro +<span class="line-numbers"><strong><a href="#n30" name="n30">30</a></strong></span> release revision rewrite: ruby section +<span class="line-numbers"><a href="#n31" name="n31">31</a></span> snippet snippet: stats_for style subtitle +<span class="line-numbers"><a href="#n32" name="n32">32</a></span> textile title toc todo values +<span class="line-numbers"><a href="#n33" name="n33">33</a></span> |xml|</pre></div> +</div> + + <section class="section"> +<header><h1 id="h_63" class="toc">Remarks</h1></header> +<ul> + <li>Only macro <em>definitions</em> (not their <em>aliases</em>) are displayed, both default and user-defined.</li> + <li>The <code>|xml|</code> macro is a special macro used if the <a href="/glyph/book/config/options.html#s_options_xml_fallback"><code>options.xml_fallback</code></a> setting is enabled.</li> + <li>There’s no distinction between macros defined by the user and macros defined by Glyph itself.</li> +</ul> + +</section> + +</section> + + <section class="section"> +<header><h1 id="h_64" class="toc">Displaying stats about a single macro</h1></header> +<p>To display statistics about a single macro (e.g. <code>note</code>), execute <code>glyph stats --macro=note</code>. Glyph displays something like this:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span>===== Macro 'note' +<span class="line-numbers"> <a href="#n2" name="n2">2</a></span>-- Total Instances: 18 +<span class="line-numbers"> <a href="#n3" name="n3">3</a></span>-- Occurrences: +<span class="line-numbers"> <a href="#n4" name="n4">4</a></span> - text/compiling/compiling.glyph (2) +<span class="line-numbers"> <a href="#n5" name="n5">5</a></span> - text/compiling/programmatic_usage.glyph (1) +<span class="line-numbers"> <a href="#n6" name="n6">6</a></span> - text/extending/params_attrs.glyph (1) +<span class="line-numbers"> <a href="#n7" name="n7">7</a></span> - text/getting_started/configuration.glyph (1) +<span class="line-numbers"> <a href="#n8" name="n8">8</a></span> - text/stats/macros.glyph (2) +<span class="line-numbers"> <a href="#n9" name="n9">9</a></span> - text/text_editing/attribute_intro.glyph (1) +<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span> - text/text_editing/esc_quot.glyph (1) +<span class="line-numbers"><a href="#n11" name="n11">11</a></span> - text/text_editing/images.glyph (1) +<span class="line-numbers"><a href="#n12" name="n12">12</a></span> - text/text_editing/inclusions.glyph (3) +<span class="line-numbers"><a href="#n13" name="n13">13</a></span> - text/text_editing/links.glyph (1) +<span class="line-numbers"><a href="#n14" name="n14">14</a></span> - text/text_editing/raw_html.glyph (1) +<span class="line-numbers"><a href="#n15" name="n15">15</a></span> - text/text_editing/section_aliases.glyph (1) +<span class="line-numbers"><a href="#n16" name="n16">16</a></span> - text/text_editing/xml_fallback.glyph (2)</pre></div> +</div> + + <section class="section"> +<header><h1 id="h_65" class="toc">Remarks</h1></header> +<ul> + <li>All the instances of the specified macro definition <em>and all its aliases</em> are collected, regardless whether a definition or an alias is specified.</li> + <li>If you use custom macros, make sure they call the <a href="http://rubydoc.info/gems/glyph/Glyph/Macro:update_source">Macro#update_source</a> appropriately method if necessary.</li> + <li>If macros are used within <a href="/glyph/book/extending/interpreting.html#rewriting">rewritten</a> macros, they’ll be also listed in each file where the rewritten macro is used.</li> +</ul> + +</section> + +</section> +<nav class="navigation"><a href="/glyph/book/stats/stats.html">← Using the stats command</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/stats/snippets.html">Snippet Statistics →</a></nav>
A
contents/glyph/book/stats/snippets.html
@@ -0,0 +1,68 @@
+----- +title: "Glyph – Snippet Statistics" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/stats/macros.html">← Macro Statistics</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/stats/bookmarks.html">Bookmark Statistics →</a></nav> + + <section class="section"> +<header><h1 id="h_67" class="toc">Displaying stats about all snippets</h1></header> +<p>To display statistics about all snippets, execute <code>glyph stats --snippets</code>. Glyph displays something like this:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span>===== Snippets +<span class="line-numbers"> <a href="#n2" name="n2">2</a></span>-- Total Snippets: 21 +<span class="line-numbers"> <a href="#n3" name="n3">3</a></span>-- Total Used Snippets: 21 +<span class="line-numbers"> <a href="#n4" name="n4">4</a></span>-- Total Unused Snippets: 0 +<span class="line-numbers"> <a href="#n5" name="n5">5</a></span>-- Snippets: +<span class="line-numbers"> <a href="#n6" name="n6">6</a></span> bin_params called_on_files coderay filter_by_ext +<span class="line-numbers"> <a href="#n7" name="n7">7</a></span> glang htmlcode img_attrs img_file +<span class="line-numbers"> <a href="#n8" name="n8">8</a></span> markups only_after_declaration only_defined_through opt +<span class="line-numbers"> <a href="#n9" name="n9">9</a></span> referenced_with_path sq_esc unsafe uv +<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span> rubydoc +<span class="line-numbers"><a href="#n11" name="n11">11</a></span>-- Used Snippets: +<span class="line-numbers"><a href="#n12" name="n12">12</a></span> bin_params called_on_files coderay filter_by_ext +<span class="line-numbers"><a href="#n13" name="n13">13</a></span> glang htmlcode img_attrs img_file +<span class="line-numbers"><a href="#n14" name="n14">14</a></span> markups only_after_declaration only_defined_through opt +<span class="line-numbers"><a href="#n15" name="n15">15</a></span> referenced_with_path sq_esc unsafe uv +<span class="line-numbers"><a href="#n16" name="n16">16</a></span> rubydoc</pre></div> +</div> + + <section class="section"> +<header><h1 id="h_68" class="toc">Remarks</h1></header> +<ul> + <li>Information on snippet usage and definitions is available only when displaying statistics for a single snippet.</li> +</ul> + +</section> + +</section> + + <section class="section"> +<header><h1 id="h_69" class="toc">Displaying stats about a single snippet</h1></header> +<p>To display statistics about a single snippet (e.g. <code>rubydoc</code>), execute <code>glyph stats --snippet=rubydoc</code>. Glyph displays something like this:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span>===== Snippet 'rubydoc' +<span class="line-numbers"> <a href="#n2" name="n2">2</a></span>-- Definition: +<span class="line-numbers"> <a href="#n3" name="n3">3</a></span>------------------- +<span class="line-numbers"> <a href="#n4" name="n4">4</a></span>http://rubydoc.info/gems/glyph +<span class="line-numbers"> <a href="#n5" name="n5">5</a></span>------------------- +<span class="line-numbers"> <a href="#n6" name="n6">6</a></span>-- Total Used Instances: 18 +<span class="line-numbers"> <a href="#n7" name="n7">7</a></span>-- Usage Details: +<span class="line-numbers"> <a href="#n8" name="n8">8</a></span> - text/extending/bookmarks_headers.glyph (1) +<span class="line-numbers"> <a href="#n9" name="n9">9</a></span> - text/extending/further_reading.glyph (5) +<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span> - text/extending/internals.glyph (5) +<span class="line-numbers"><a href="#n11" name="n11">11</a></span> - text/extending/macro_def.glyph (3) +<span class="line-numbers"><a href="#n12" name="n12">12</a></span> - text/extending/validators.glyph (1) +<span class="line-numbers"><a href="#n13" name="n13">13</a></span> - text/macros/macros_core.glyph (2) +<span class="line-numbers"><a href="#n14" name="n14">14</a></span> - text/stats/macros.glyph (1)</pre></div> +</div> + + <section class="section"> +<header><h1 id="h_70" class="toc">Remarks</h1></header> +<ul> + <li>Nested snippets appear as within the file containing the top-level snippet.</li> +</ul> + +</section> + +</section> +<nav class="navigation"><a href="/glyph/book/stats/macros.html">← Macro Statistics</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/stats/bookmarks.html">Bookmark Statistics →</a></nav>
A
contents/glyph/book/stats/stats.html
@@ -0,0 +1,71 @@
+----- +title: "Glyph – Using the stats command" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/compiling/programmatic_usage.html">← Using Glyph programmatically</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/stats/macros.html">Macro Statistics →</a></nav> + +<p>Glyph includes a <a href="/glyph/book/ref_commands.html#c_stats"><code>stats</code></a> command that can be used to display useful statistics about your Glyph project. If you try running Glyph's command help, you'll see that this command can take quite a few options: +</p> +<div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span>$ glyph help stats +<span class="line-numbers"> <a href="#n2" name="n2">2</a></span>Glyph v0.5.0 +<span class="line-numbers"> <a href="#n3" name="n3">3</a></span> +<span class="line-numbers"> <a href="#n4" name="n4">4</a></span>stats [options] +<span class="line-numbers"> <a href="#n5" name="n5">5</a></span> Display statistics +<span class="line-numbers"> <a href="#n6" name="n6">6</a></span> +<span class="line-numbers"> <a href="#n7" name="n7">7</a></span>Options: +<span class="line-numbers"> <a href="#n8" name="n8">8</a></span> -b, --bookmarks - Display stats about bookmarks +<span class="line-numbers"> <a href="#n9" name="n9">9</a></span> --bookmark=arg - Display stats about a single bookmark +<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span> -f, --files - Display stats about project files +<span class="line-numbers"><a href="#n11" name="n11">11</a></span> -l, --links - Display stats about links +<span class="line-numbers"><a href="#n12" name="n12">12</a></span> --link=arg - Display stats about links matching a regular expression +<span class="line-numbers"><a href="#n13" name="n13">13</a></span> -m, --macros - Display stats about macros +<span class="line-numbers"><a href="#n14" name="n14">14</a></span> --macro=arg - Display stats about a single macro +<span class="line-numbers"><a href="#n15" name="n15">15</a></span> -s, --snippets - Display stats about snippets +<span class="line-numbers"><a href="#n16" name="n16">16</a></span> --snippet=arg - Display stats about a single snippet</pre></div> +</div> + +<p>If no options are specified, the command returns a summary containing different element totals, i.e.:</p> +<ul> + <li>The files used in the project</li> + <li>Macro definitions and instances</li> + <li>Snippets</li> + <li>Bookmarks</li> + <li>Links and references</li> +</ul> +<p>Example:</p> +<div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span>===================================== +<span class="line-numbers"> <a href="#n2" name="n2">2</a></span>Glyph - Statistics +<span class="line-numbers"> <a href="#n3" name="n3">3</a></span>===================================== +<span class="line-numbers"> <a href="#n4" name="n4">4</a></span> +<span class="line-numbers"> <a href="#n5" name="n5">5</a></span>===== Files +<span class="line-numbers"> <a href="#n6" name="n6">6</a></span>-- Total Files: 50 +<span class="line-numbers"> <a href="#n7" name="n7">7</a></span>-- /text -- 46 +<span class="line-numbers"> <a href="#n8" name="n8">8</a></span>-- /images -- 3 +<span class="line-numbers"> <a href="#n9" name="n9">9</a></span>-- /styles -- 0 +<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span>-- /layouts -- 0 +<span class="line-numbers"><a href="#n11" name="n11">11</a></span>-- /lib -- 1 +<span class="line-numbers"><a href="#n12" name="n12">12</a></span> +<span class="line-numbers"><a href="#n13" name="n13">13</a></span>===== Macros +<span class="line-numbers"><a href="#n14" name="n14">14</a></span>-- Total Macro Instances: 2950 +<span class="line-numbers"><a href="#n15" name="n15">15</a></span>-- Total Macro Definitions: 22 +<span class="line-numbers"><a href="#n16" name="n16">16</a></span>-- Total Macro Aliases: 57 +<span class="line-numbers"><a href="#n17" name="n17">17</a></span>-- Total Used Macro Definitions: 60 +<span class="line-numbers"><a href="#n18" name="n18">18</a></span> +<span class="line-numbers"><a href="#n19" name="n19">19</a></span>===== Snippets +<span class="line-numbers"><strong><a href="#n20" name="n20">20</a></strong></span>-- Total Snippets: 21 +<span class="line-numbers"><a href="#n21" name="n21">21</a></span>-- Total Used Snippets: 21 +<span class="line-numbers"><a href="#n22" name="n22">22</a></span>-- Total Unused Snippets: 0 +<span class="line-numbers"><a href="#n23" name="n23">23</a></span> +<span class="line-numbers"><a href="#n24" name="n24">24</a></span>===== Bookmarks +<span class="line-numbers"><a href="#n25" name="n25">25</a></span>-- Total Bookmarks: 221 +<span class="line-numbers"><a href="#n26" name="n26">26</a></span>-- Total Referenced Bookmarks: 87 +<span class="line-numbers"><a href="#n27" name="n27">27</a></span>-- Total Unreferenced Bookmarks: 135 +<span class="line-numbers"><a href="#n28" name="n28">28</a></span> +<span class="line-numbers"><a href="#n29" name="n29">29</a></span>===== Links +<span class="line-numbers"><strong><a href="#n30" name="n30">30</a></strong></span>-- Total Internal Links: 87 +<span class="line-numbers"><a href="#n31" name="n31">31</a></span>-- Total External Links: 97</pre></div> +</div> + +<nav class="navigation"><a href="/glyph/book/compiling/programmatic_usage.html">← Using Glyph programmatically</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/stats/macros.html">Macro Statistics →</a></nav>
A
contents/glyph/book/text_editing/attribute_intro.html
@@ -0,0 +1,32 @@
+----- +title: "Glyph – Macro attributes" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/text_editing/macro_intro.html">← Introducing Glyph Macros</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/macro_composition.html">Macro Composition →</a></nav> + <p>Although a macro can take any number of parameters, they are often no more than two or three, for readibility reasons: parameters have no name, but their position within a macro is significant.</p> +<p>If you have something like this:</p> + + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>custom_image[test.png|50%|50%|Test Image]</pre></div> +</div> + + <p>it may still be easy enough to understand what each parameter is used for, but:</p> +<ul> + <li>you can easily forget that the third parameter is the image width</li> + <li>if you don’t want to resize the image, you still have to pass <em>empty parameters</em> to the macro, like this: <code>custom_image[test2.png|||Test Image]</code></li> +</ul> +<p>To avoid these situations, some macros which would normally take three or four parameters take optional attributes instead, so you can write:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>image[test.png +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> @width[50%] +<span class="line-numbers"><a href="#n3" name="n3">3</a></span> @alt[Test Image] +<span class="line-numbers"><a href="#n4" name="n4">4</a></span> @height[50%] +<span class="line-numbers"><a href="#n5" name="n5">5</a></span>]</pre></div> +</div> + + <p>More verbose, of course, but definitely more readable. In this way, if you won't want to scale an image, you can safely omit the <code>@width</code> and <code>@height</code> attributes.</p> + <aside class="note"> +<span class="note-title">Note</span>Like parameters, attributes can contain other macros, too. + +</aside> +<nav class="navigation"><a href="/glyph/book/text_editing/macro_intro.html">← Introducing Glyph Macros</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/macro_composition.html">Macro Composition →</a></nav>
A
contents/glyph/book/text_editing/code.html
@@ -0,0 +1,54 @@
+----- +title: "Glyph – Source Code" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/text_editing/images.html">← Images and Figures</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/raw_html.html">Textile or Markdown →</a></nav> + <p>If you’re a programmer, chances are that you’re going to include some source code in your articles and books. Glyph offers two ways to format code blocks effortlessly: the <a href="/glyph/book/macros/macros_block.html#m_codeblock"><code>codeblock</code></a> macro, which simply wraps text into <code><pre></code> and <code><code></code> tags, or the <a href="/glyph/book/macros/macros_filters.html#m_highlight"><code>highlight</code></a> macro. The last one requires either <a href="http://coderay.rubychan.de/">Coderay</a> or <a href="http://ultraviolet.rubyforge.org/">Ultraviolet</a>, but it provides syntax highlighting for the most common programming languages.</p> +<p>Cosider the following piece of ruby code:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>def find_child(&block) +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> children.each do |c| +<span class="line-numbers"><a href="#n3" name="n3">3</a></span> c.descend do |node, level| +<span class="line-numbers"><a href="#n4" name="n4">4</a></span> return node if block.call(node) +<span class="line-numbers"><a href="#n5" name="n5">5</a></span> end +<span class="line-numbers"><a href="#n6" name="n6">6</a></span> end +<span class="line-numbers"><a href="#n7" name="n7">7</a></span> nil +<span class="line-numbers"><a href="#n8" name="n8">8</a></span>end</pre></div> +</div> + + <p>It can be wrapped in a highlight macro, like so:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span>highlight[=ruby| +<span class="line-numbers"> <a href="#n2" name="n2">2</a></span> def find_child(&block) +<span class="line-numbers"> <a href="#n3" name="n3">3</a></span> children.each do |c| +<span class="line-numbers"> <a href="#n4" name="n4">4</a></span> c.descend do |node, level| +<span class="line-numbers"> <a href="#n5" name="n5">5</a></span> return node if block.call(node) +<span class="line-numbers"> <a href="#n6" name="n6">6</a></span> end +<span class="line-numbers"> <a href="#n7" name="n7">7</a></span> end +<span class="line-numbers"> <a href="#n8" name="n8">8</a></span> nil +<span class="line-numbers"> <a href="#n9" name="n9">9</a></span> end +<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span>=]</pre></div> +</div> + + <p>...to produce the following, using the coderay highlighter:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span><span class="keyword">def</span> <span class="function">find_child</span>(&block) +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> children.each <span class="keyword">do</span> |c| +<span class="line-numbers"><a href="#n3" name="n3">3</a></span> c.descend <span class="keyword">do</span> |node, level| +<span class="line-numbers"><a href="#n4" name="n4">4</a></span> <span class="keyword">return</span> node <span class="keyword">if</span> block.call(node) +<span class="line-numbers"><a href="#n5" name="n5">5</a></span> <span class="keyword">end</span> +<span class="line-numbers"><a href="#n6" name="n6">6</a></span> <span class="keyword">end</span> +<span class="line-numbers"><a href="#n7" name="n7">7</a></span> <span class="predefined-constant">nil</span> +<span class="line-numbers"><a href="#n8" name="n8">8</a></span><span class="keyword">end</span></pre></div> +</div> + + <aside class="box"> +<div class="box-title">Some Remarks</div> +<ul> + <li>Highlighters require some configuration. For more information on relevant configuration settings, see the <a href="/glyph/book/config/filters.html#cfg_filters">filters.*</a> configuration settings.</li> + <li>If you’re using the <a href="/glyph/book/macros/macros_filters.html#m_highlight"><code>highlight</code></a> macro together within the <a href="/glyph/book/macros/macros_filters.html#m_textile"><code>textile</code></a> macro, you must wrap the macro call within <code><notextile></code> tags.</li> + <li>You must always escape pipes (<code>|</code>) with the code or the highlight macro.</li> +</ul> + +</aside> +<nav class="navigation"><a href="/glyph/book/text_editing/images.html">← Images and Figures</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/raw_html.html">Textile or Markdown →</a></nav>
A
contents/glyph/book/text_editing/conditionals.html
@@ -0,0 +1,49 @@
+----- +title: "Glyph – Conditional Macros" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/text_editing/inclusions.html">← Content Reuse</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/evaluation.html">Simple Programming and Code Evaluation →</a></nav> + <p>Sometimes you may want text to be included in a document only if certain conditions are satisfied. For example, you may want to display a disclaimer section only if the document is a draft (see the <a href="/glyph/book/config/document.html#s_document_draft"><code>document.draft</code></a> setting), or use a particular stylesheet only if when you generate a <span class="caps">PDF</span> document.</p> +<p>To do so, you can use the <a href="/glyph/book/macros/macros_core.html#m_condition"><code>condition</code></a> macro (aliased by <code>?</code>), and a set of additional macros that can be used as conditional operators i.e.:</p> +<ul> + <li><a href="/glyph/book/macros/macros_core.html#m_eq"><code>eq</code></a> macro</li> + <li><a href="/glyph/book/macros/macros_core.html#m_not"><code>not</code></a> macro</li> + <li><a href="/glyph/book/macros/macros_core.html#m_and"><code>and</code></a> macro</li> + <li><a href="/glyph/book/macros/macros_core.html#m_or"><code>or</code></a> macro</li> +</ul> +<p>Consider the following code:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>?[$[document.draft]| +<span class="line-numbers"><a href="#n2" name="n2">2</a></span>This is a first draft of the Glyph Book| +<span class="line-numbers"><a href="#n3" name="n3">3</a></span>This is the official version of the Glyph Book]</pre></div> +</div> + + <p>In this case, if <code>document.draft</code> is set to <code>true</code>, “This is a first draft of the Glyph Book” will be displayed; if not, “This is the official version of the Glyph Book” will be displayed instead.</p> +<p>The <a href="/glyph/book/macros/macros_core.html#m_condition"><code>condition</code></a> macro takes up to three parameters:</p> +<ol> + <li>the condition to evaluate</li> + <li>the text to include in the document only if the condition is satisfied.</li> + <li><em>(Optional)</em> the text to include in the document if the condition is <em>not</em> satisfied.</li> +</ol> +<p>Note that <em>all</em> parameters can contain macros, of course, so you can write things like:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>?[and[ +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> eq[$[document.output]|pdf] +<span class="line-numbers"><a href="#n3" name="n3">3</a></span> | +<span class="line-numbers"><a href="#n4" name="n4">4</a></span> eq[$[tools.pdf_generator]|prince] +<span class="line-numbers"><a href="#n5" name="n5">5</a></span> ] +<span class="line-numbers"><a href="#n6" name="n6">6</a></span> | +<span class="line-numbers"><a href="#n7" name="n7">7</a></span> style[pagination.css]]</pre></div> +</div> + + <p>In this case, the <code>pagination.css</code> stylesheet is included only when you're generating a PDF document using Prince XML.</p> + <section class="section"> +<header><h1 id="h_42" class="toc">Results of conditional expressions</h1></header> +<p>The <a href="/glyph/book/macros/macros_core.html#m_condition"><code>condition</code></a> macro in Glyph works in a similar way as conditionals in programming languages: if the conditional expression (supplied as first parameter) is satisfied then the second parameter is executed or displayed. But when is a conditional expression satisfied? Glyph is a simple mini-language to perform text manipulation, and has no types, it can only understand text, therefore:</p> +<ul> + <li>A conditional expression is satisfied if it evaluates to a non-empty string except “false”.</li> + <li>A conditional expression is not satisfied if it evaluates to an empty string or the string “false”.</li> +</ul> + +</section> +<nav class="navigation"><a href="/glyph/book/text_editing/inclusions.html">← Content Reuse</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/evaluation.html">Simple Programming and Code Evaluation →</a></nav>
A
contents/glyph/book/text_editing/esc_quot.html
@@ -0,0 +1,96 @@
+----- +title: "Glyph – Escaping and Quoting" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/text_editing/macro_composition.html">← Macro Composition</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/sections.html">Sections and Headers →</a></nav> + <p>Glyph doesn’t require any special control characters like LaTeX, and its macro syntax is very straightforward and liberal. This however comes with a price: because square brackets are used as delimiters, you must escape any square bracket in your text with a backslash. That’s not <em>too</em> bad if you think about it, unless you’re writing programming code, in which case escaping every single square bracket can be painful.</p> +<p>If a portion of your text contains an excessive amount of square brackets, you may consider using the <a href="/glyph/book/macros/macros_core.html#m_escape"><code>escape</code></a> macro (or its alias <code>.</code>) with the <code>[=</code> and <code>=]</code> delimiters. By itself, the escape macro doesn’t do anything: it just evaluates to its contents, but the special delimiters act as an escape for any square bracket within them. As a consequence, any macro within <code>[=</code> and <code>=]</code> will <em>not</em> be evaluated.</p> +<p>You can use the quoting delimiters with <em>any</em> macro identifier. Obviously, using them as delimiters for things like <a href="/glyph/book/macros/macros_structure.html#m_section"><code>section</code></a> macros may not be a good idea, but they should be more or less mandatory with the <a href="/glyph/book/macros/macros_block.html#m_codeblock"><code>codeblock</code></a> macro or the <a href="/glyph/book/macros/macros_filters.html#m_highlight"><code>highlight</code></a> macro, especially when it contains square brackets or even Glyph code, like this:</p> + + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span>codeblock[= +<span class="line-numbers"> <a href="#n2" name="n2">2</a></span> section[ +<span class="line-numbers"> <a href="#n3" name="n3">3</a></span> @title[A section] +<span class="line-numbers"> <a href="#n4" name="n4">4</a></span> @id[test] +<span class="line-numbers"> <a href="#n5" name="n5">5</a></span>This is a section. +<span class="line-numbers"> <a href="#n6" name="n6">6</a></span> section[ +<span class="line-numbers"> <a href="#n7" name="n7">7</a></span> @title[A nested section] +<span class="line-numbers"> <a href="#n8" name="n8">8</a></span>This is another section. +<span class="line-numbers"> <a href="#n9" name="n9">9</a></span> ] +<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span> ] +<span class="line-numbers"><a href="#n11" name="n11">11</a></span>=]</pre></div> +</div> + + + <aside class="note"> +<span class="note-title">Note</span>Although quoting delimiters allow you to use square brackets without escaping them, you must still escape them if you want to escape quoting delimiters themselves. + +</aside> + + <p>Besides square brackets, there are other characters that must or can be escaped with backslashes, as shown in the following table:</p> + + <table> + <tr> + <th>Escape Sequence</th> + <th>Evaluates to...</th> + <th>Notes</th> + </tr> + <tr> + <td> +<code>\[</code> +</td> + <td> +<code>[</code> +</td> + <td> +Square brackets must be escaped unless used as macro delimiters or within a quoting macro. +</td> + </tr> + <tr> + <td> +<code>\]</code> +</td> + <td> +<code>]</code> +</td> + <td> +Square brackets must be escaped unless used as macro delimiters or within a quoting macro. +</td> + </tr> + <tr> + <td> +<code>\\</code> +</td> + <td> +<code>\</code> +</td> + <td>Backslashes do not have to be escaped by default, but an escaped backslash will evaluate to itself.</td> + </tr> + <tr> + <td> +<code>\=</code> +</td> + <td> +<code>=</code> +</td> + <td>Equal signs do not have to be escaped by default, but an escaped equal sign will evaluate to iself.</td> + </tr> + <tr> + <td> +<code>\|</code> +</td> + <td> +<code>|</code> +</td> + <td>Pipes must be escaped (even within quoting macros) unless they are used to separate macro parameters.</td> + </tr> + <tr> + <td> +<code>\/</code> +</td> + <td /> + <td>An escaped dot evaluates to nothing. Useful to separate macro identifiers from other characters: <br /><code>_\/=>[#link|This link is emphasized using Textile]_ </code> + </td> + </tr> + </table> +<nav class="navigation"><a href="/glyph/book/text_editing/macro_composition.html">← Macro Composition</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/sections.html">Sections and Headers →</a></nav>
A
contents/glyph/book/text_editing/evaluation.html
@@ -0,0 +1,70 @@
+----- +title: "Glyph – Simple Programming and Code Evaluation" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/text_editing/conditionals.html">← Conditional Macros</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/compiling/compiling.html">Compiling a project →</a></nav> + <section class="section"> +<header><h1 id="h_44" class="toc">Turing-completeness</h1></header> +<p>As of version 0.5.0, Glyph can be considered <em>Turing-complete</em>, as it satisfies the following <a href="http://c2.com/cgi/wiki?LanguageRequirementsForTuringCompleteness">requirements for Turing-completeness</a>:</p> +<ul> + <li>A conditional construct, implemented via the <a href="/glyph/book/macros/macros_core.html#m_condition"><code>condition</code></a> macro.</li> + <li>Variable assignment, by setting the value of snippets using the <a href="/glyph/book/macros/macros_core.html#m_snippet_"><code>snippet:</code></a> macro and of attributes using the <a href="/glyph/book/macros/macros_core.html#m_attribute_"><code>attribute:</code></a> macro.</li> + <li>(infinite) iteration implemented through the <a href="/glyph/book/macros/macros_core.html#m_while"><code>while</code></a> macro or recursion, which is possible thanks to the <a href="/glyph/book/macros/macros_core.html#m_define_"><code>define:</code></a> macro.</li> + <li>A memory model which emulates an infinite store: there are no enforced limits on attribute/snippets allocations and number of algorithms or parameters.</li> +</ul> + +</section> + + <section class="section"> +<header><h1 id="h_45" class="toc">Operations on integer values</h1></header> +<p>Glyph can be used to perform operation on integer values (additions, subtractions and multiplications). For example, <code>add[2|3|7]</code> will evaluate to @12@, and <code>multiply[add[3|7]|subtract[5|1|2]]</code> will return 20.</p> + +<p>As a more complex example, consider the following @factorial@ macro, which is able to calculate the factorial of a number recursively:</p> + + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>def:[factorial| +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> ?[ +<span class="line-numbers"><a href="#n3" name="n3">3</a></span> eq[{{0}}|0]|1| +<span class="line-numbers"><a href="#n4" name="n4">4</a></span> multiply[ +<span class="line-numbers"><a href="#n5" name="n5">5</a></span> {{0}} | factorial[subtract[{{0}}|1]] +<span class="line-numbers"><a href="#n6" name="n6">6</a></span> ] +<span class="line-numbers"><a href="#n7" name="n7">7</a></span> ] +<span class="line-numbers"><a href="#n8" name="n8">8</a></span>]</pre></div> +</div> + + +<p>If you try executing <code>factorial[5]</code>, it will evaluate to @120@.</p> + +</section> + <section class="section"> +<header><h1 id="h_46" class="toc">Lexically-scoped attribute assignment</h1></header> +<p><a href="/glyph/book/text_editing/inclusions.html#snippets">Snippets</a> can be used in a similar way as <em>variables</em> are used in programming languages. Or better, they can be used as <em>global variables</em>, as they are visible from anywhere in the Glyph document. If you need something more restricted to, say, a section and all its subsections, you can define your own attributes and use them in a very similar way.</p> +<p>Consider the following Glyph code:</p> + +</section> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>let[ +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> @:[a|bits] +<span class="line-numbers"><a href="#n3" name="n3">3</a></span> @:[b|bobs] +<span class="line-numbers"><a href="#n4" name="n4">4</a></span> section[ +<span class="line-numbers"><a href="#n5" name="n5">5</a></span> @title[Something more about attributes] +<span class="line-numbers"><a href="#n6" name="n6">6</a></span>Attributes are like lexically scoped variables. You can use them to store @[a] and @[b]. +<span class="line-numbers"><a href="#n7" name="n7">7</a></span> ] +<span class="line-numbers"><a href="#n8" name="n8">8</a></span>]</pre></div> +</div> + + <p>The <a href="/glyph/book/macros/macros_core.html#m_let"><code>let</code></a> macro here only acts as a dummy macro (it does nothing really) to bind attributes using the <a href="/glyph/book/macros/macros_core.html#m_attribute_"><code>attribute:</code></a> macro (aliased by <code>@:</code>). Attributes can then be used anywhere within the <code>let</code> macro, so the content of the section reads: “Attributes are like lexically-scoped variables. You can use them to store bits and bobs”.</p> +<p>Note that attributes defined through the <a href="/glyph/book/macros/macros_core.html#m_attribute_"><code>attribute:</code></a> macro are… well, attributes! Feel free to use the <a href="/glyph/book/macros/macros_core.html#m_attribute"><code>attribute</code></a> macro to access standard attributes like <code>title</code>, etc.</p> + <section class="section"> +<header><h1 id="h_47" class="toc">Evaluating Ruby code</h1></header> +<p>For anything more complex than what described in the previous sections you can also evaluate simple ruby code snippets using the <code>ruby</code> macro (aliased to <code>%</code>), like this:</p> +<ul> + <li><code>%[2 + 2]</code> → 4</li> + <li><code>%[Time.now]</code> → 2014-10-04 21:34:10 +0200</li> + <li><code>%[Glyph::VERSION]</code> → 0.5.3.1</li> +</ul> +<p>The scope for the code evaluation is the Kernel module, (with all inclusions required by Glyph itself).</p> +<p>Although it is possible to retrieve Glyph configuration settings in this way (e.g. <code>%[cfg('document.author')]</code>), the <a href="/glyph/book/macros/macros_core.html#m_config"><code>config</code></a> macro (aliased to <code>$</code>) makes things slightly simpler (e.g. <code>$[document.author]</code>).</p> + +</section> +<nav class="navigation"><a href="/glyph/book/text_editing/conditionals.html">← Conditional Macros</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/compiling/compiling.html">Compiling a project →</a></nav>
A
contents/glyph/book/text_editing/glyph_files.html
@@ -0,0 +1,9 @@
+----- +title: "Glyph – <code>.glyph</code> files" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/getting_started/configuration.html">← Project Configuration</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/macro_intro.html">Introducing Glyph Macros →</a></nav> + <p>The <code>text</code> folder of any Glyph folder contains all the text source files used to produce a document. Although there are no restrictions on the extension of the files in this folder, you may want to use <code>.glyph</code>, especially if <a href="http://www.vim.org">Vim</a> is your favorite text editor.</p> +<p>The reason is simple: a Glyph syntax file is <a href="http://www.vim.org/scripts/script.php?script_id=3086">available on vim.org</a>. Although not essential, syntax highlighting does help when editing Glyph files.</p> +<p>If you use TextMate, you may want to check out Eric Givens’ <a href="http://github.com/darthzippy/glyph.tmbundle">Glyph TextMate Bundle</a>.</p> +<nav class="navigation"><a href="/glyph/book/getting_started/configuration.html">← Project Configuration</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/macro_intro.html">Introducing Glyph Macros →</a></nav>
A
contents/glyph/book/text_editing/images.html
@@ -0,0 +1,41 @@
+----- +title: "Glyph – Images and Figures" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/text_editing/links.html">← Links and Bookmarks</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/code.html">Source Code →</a></nav> + <p>Same as for <a href="/glyph/book/text_editing/links.html#links">links</a>, you can also include images and figures using Textile or Markdown. If you want additional features, you can use the <a href="/glyph/book/macros/macros_block.html#m_image"><code>image</code></a> macro and the <a href="/glyph/book/macros/macros_block.html#m_figure"><code>figure</code></a> macro, as shown in the following example:</p> + + <aside class="box"> +<div class="box-title">Example</div> +<p> +The following Glyph code: +</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>image[glyph.svg +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> @with[20%] +<span class="line-numbers"><a href="#n3" name="n3">3</a></span> @height[20%] +<span class="line-numbers"><a href="#n4" name="n4">4</a></span>] +<span class="line-numbers"><a href="#n5" name="n5">5</a></span>figure[example.png|An example figure. +<span class="line-numbers"><a href="#n6" name="n6">6</a></span> @alt[Example Figure] +<span class="line-numbers"><a href="#n7" name="n7">7</a></span>]</pre></div> +</div> + + <p> +Is translated into the following HTML code: +</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span><span class="tag"><img</span> <span class="attribute-name">src</span>=<span class="string"><span class="delimiter">"</span><span class="content">images/glyph.svg</span><span class="delimiter">"</span></span> <span class="attribute-name">width</span>=<span class="string"><span class="delimiter">"</span><span class="content">20%</span><span class="delimiter">"</span></span> <span class="attribute-name">height</span>=<span class="string"><span class="delimiter">"</span><span class="content">20%</span><span class="delimiter">"</span></span> <span class="tag">/></span> +<span class="line-numbers"><a href="#n2" name="n2">2</a></span><span class="tag"><div</span> <span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">figure</span><span class="delimiter">"</span></span><span class="tag">></span> +<span class="line-numbers"><a href="#n3" name="n3">3</a></span> <span class="tag"><img</span> <span class="attribute-name">src</span>=<span class="string"><span class="delimiter">"</span><span class="content">images/example.png</span><span class="delimiter">"</span></span> <span class="attribute-name">alt</span>=<span class="string"><span class="delimiter">"</span><span class="content">Example Figure</span><span class="delimiter">"</span></span><span class="tag">/></span> +<span class="line-numbers"><a href="#n4" name="n4">4</a></span> <span class="tag"><div</span> <span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">caption</span><span class="delimiter">"</span></span><span class="tag">></span>An example figure.<span class="tag"></div></span> +<span class="line-numbers"><a href="#n5" name="n5">5</a></span><span class="tag"></div></span></pre></div> +</div> + + <p>Any attribute passed to the <a href="/glyph/book/macros/macros_block.html#m_image"><code>image</code></a> macro or the <a href="/glyph/book/macros/macros_block.html#m_figure"><code>figure</code></a> macro is automatically passed to the underlying <code><img></code> tag.</p> + +</aside> + <aside class="note"> +<span class="note-title">Note</span>In future releases, figures will be numbered automatically and included in a <em>List of Figures</em> section. + +</aside> +<nav class="navigation"><a href="/glyph/book/text_editing/links.html">← Links and Bookmarks</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/code.html">Source Code →</a></nav>
A
contents/glyph/book/text_editing/inclusions.html
@@ -0,0 +1,45 @@
+----- +title: "Glyph – Content Reuse" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/text_editing/stylesheets.html">← Adding Stylesheets</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/conditionals.html">Conditional Macros →</a></nav> + <section class="section"> +<header><h1 id="file-inclusions" class="toc">File inclusions</h1></header> +<p>If you’re authoring a user manual, a long article, or a book, writing everything inside a single <code>document.glyph</code> file may not be optimal. For this reason, Glyph provides an <a href="/glyph/book/macros/macros_core.html#m_include"><code>include</code></a> macro that can be used to include the contents of any file within the <code>text/</code> directory:</p> +<p><code>include[general/introduction.textile]</code></p> +<p>The macro call above loads the contents of the <code>introduction.textile</code> file, within the <code>text/general</code> directory.</p> +<p>When including a text file, an input filter macro is applied to its contents by default, based on the file extension used:</p> +<ul> + <li><code>.textile</code> or <code>.txt</code> → <a href="/glyph/book/macros/macros_filters.html#m_textile"><code>textile</code></a> macro</li> + <li><code>.markdown</code> or <code>.md</code> → <a href="/glyph/book/macros/macros_filters.html#m_markdown"><code>markdown</code></a> macro</li> +</ul> +<p>You can override this behavior by setting the <code>filters.by_file_extensions</code> configuration setting to <code>false</code>. If no extension is specified, <code>.glyph</code> is assumed.</p> + <section class="section"> +<header><h1 id="h_39" class="toc">Remarks</h1></header> +<ul> + <li>The <a href="/glyph/book/macros/macros_core.html#m_include"><code>include</code></a> macro can also be used to include (and evaluate) ruby files (with a <code>.rb</code> extension). In this case, the ruby file must be placed within the <code>lib/</code> directory of the current project.</li> + <li>The <a href="/glyph/book/macros/macros_core.html#m_load"><code>load</code></a> macro macro can be used to include the content of any file <em>without</em> performing any evaluation.</li> +</ul> + +</section> + +</section> + <section class="section"> +<header><h1 id="snippets" class="toc">Snippets</h1></header> +<p>While including the context of an entire file is definitely a useful feature for content reuse, sometimes it can be an overkill. What if, for example, you just want to reuse a short procedure or even a sentence or a single word? In this case, you may want to consider using a <em>snippet</em> instead.</p> +<p>Snippets can be defined using the <a href="/glyph/book/macros/macros_core.html#m_snippet_"><code>snippet:</code></a> macro (aliased by <code>&:</code>) and called by using the <a href="/glyph/book/macros/macros_core.html#m_snippet"><code>snippet</code></a> macro (aliased by <code>&</code>). Consider the following simple example:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>&:[markups|Textile or Markdown] +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> +<span class="line-numbers"><a href="#n3" name="n3">3</a></span>Glyph supports &[markups].</pre></div> +</div> + + <p>You can use <code>&[markups]</code> anywhere in your document instead of having to type "Textile or Markdown" every time. Additionally, later on you can change the value of the <code>markups</code> to change it everywhere else in the document.</p> + +</section> + <aside class="tip"> +<span class="note-title">Tip</span>Snippets (or any other macro) can be nested within other snippets. Glyph takes care of checking if you nested snippets or macros mutually and warns you as necessary. + +</aside> + +<nav class="navigation"><a href="/glyph/book/text_editing/stylesheets.html">← Adding Stylesheets</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/conditionals.html">Conditional Macros →</a></nav>
A
contents/glyph/book/text_editing/links.html
@@ -0,0 +1,66 @@
+----- +title: "Glyph – Links and Bookmarks" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/text_editing/topics.html">← Topics</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/images.html">Images and Figures →</a></nav> + <p>Lightweight markups let you create internal and external links in a very easy way, and you can still do so in Glyph. However, if you do so:</p> +<ul> + <li>you can’t check if they are valid</li> + <li>you can’t infer the link title automatically</li> +</ul> +<p>If you care about link validation and you want to save some keystrokes, then you should use:</p> +<ul> + <li>the <a href="/glyph/book/macros/macros_inline.html#m_link"><code>link</code></a> macro (aliased to <code>=></code>) — to create internal and external links.</li> + <li>the <a href="/glyph/book/macros/macros_inline.html#m_anchor"><code>anchor</code></a> macro (aliased to <code>#</code>) — to create named anchors (bookmarks) within your document.</li> +</ul> + <aside class="box"> +<div class="box-title">Example</div> +<p> +The following Glyph code: +</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>This is a link to link[#test]. +<span class="line-numbers"><a href="#n2" name="n2">2</a></span>... +<span class="line-numbers"><a href="#n3" name="n3">3</a></span>This is link[#wrong]. +<span class="line-numbers"><a href="#n4" name="n4">4</a></span>This is a #[test|test anchor].</pre></div> +</div> + + <p> +Is translated into the following HTML code: +</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span><span class="tag"><p></span>This is a link to <span class="tag"><a</span> <span class="attribute-name">href</span>=<span class="string"><span class="delimiter">"</span><span class="content">#test</span><span class="delimiter">"</span></span><span class="tag">></span>test anchor<span class="tag"></a></span>.<span class="tag"></p></span> +<span class="line-numbers"><a href="#n2" name="n2">2</a></span><span class="tag"><p></span>...<span class="tag"></p></span> +<span class="line-numbers"><a href="#n3" name="n3">3</a></span><span class="tag"><p></span>This is <span class="tag"><a</span> <span class="attribute-name">href</span>=<span class="string"><span class="delimiter">"</span><span class="content">#wrong</span><span class="delimiter">"</span></span><span class="tag">></span>#wrong<span class="tag"></a></span>.<span class="tag"></p></span> +<span class="line-numbers"><a href="#n4" name="n4">4</a></span><span class="tag"><p></span>This is a <span class="tag"><a</span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">test</span><span class="delimiter">"</span></span><span class="tag">></span>test anchor<span class="tag"></a></span>.<span class="tag"></p></span></pre></div> +</div> + + <p>Additionally, the following warning message is displayed when <a href="/glyph/book/compiling/compiling.html#compile">compiling</a>:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>warning: Bookmark 'wrong' does not exist +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> -> source: @: authoring.textile +<span class="line-numbers"><a href="#n3" name="n3">3</a></span> -> path: document/body/bodymatter/chapter/@/textile/section/section/box/link</pre></div> +</div> + +</aside> + <p>Basically, if you use the <a href="/glyph/book/macros/macros_inline.html#m_link"><code>link</code></a> macro and the <a href="/glyph/book/macros/macros_inline.html#m_anchor"><code>anchor</code></a> macro, Glyph makes sure that:</p> +<ul> + <li>all links point to valid anchors within the document (regardless if the anchors are before or after the link, in snippets or included files).</li> + <li>there are no duplicate anchors within the documents.</li> + <li>if no title is specified as second parameter for the <a href="/glyph/book/macros/macros_inline.html#m_link"><code>link</code></a> macro, the anchor’s name is used as such.</li> +</ul> +<p>Besides using the <a href="/glyph/book/macros/macros_inline.html#m_anchor"><code>anchor</code></a> macro, you can also create an anchor for a header by passing an <code>@id</code> attribute the the <a href="/glyph/book/macros/macros_structure.html#m_section"><code>section</code></a> macro, like this:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>section[ +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> @title[My Section] +<span class="line-numbers"><a href="#n3" name="n3">3</a></span> @id[my_section] +<span class="line-numbers"><a href="#n4" name="n4">4</a></span>... +<span class="line-numbers"><a href="#n5" name="n5">5</a></span>]</pre></div> +</div> + + <p>By default, validation is only enabled for internal links (i.e. the check occurs if the first parameter of the <a href="/glyph/book/macros/macros_inline.html#m_link"><code>link</code></a> macro starts with a <code>#</code>). You can enable it for external links as well by setting the <a href="/glyph/book/config/options.html#s_options_url_validation"><code>options.url_validation</code></a> setting to <code>true</code>. If URL validation is enabled, an error is returned if a link returns an HTTP status greater than 302.</p> + <aside class="important"> +<span class="note-title">Important</span>Enabling URL validation may significantly slow down compilation if a lot of external links are present. + +</aside> +<nav class="navigation"><a href="/glyph/book/text_editing/topics.html">← Topics</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/images.html">Images and Figures →</a></nav>
A
contents/glyph/book/text_editing/macro_composition.html
@@ -0,0 +1,32 @@
+----- +title: "Glyph – Macro Composition" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/text_editing/attribute_intro.html">← Macro attributes</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/esc_quot.html">Escaping and Quoting →</a></nav> +<p>Glyph macros can be <em>composed</em> with other using the <code>/</code> character. Macro composition can be used instead of nesting, provided that macro containers (also called <em>dispatchers</em> in certain situations) take only one parameter and no attributes.</p> +<p>For example, the following code:</p> +<div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>?[ +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> not[output?[pdf]]| +<span class="line-numbers"><a href="#n3" name="n3">3</a></span> ... +<span class="line-numbers"><a href="#n4" name="n4">4</a></span>]</pre></div> +</div> + + +<p>Can be written like this:</p> + +<div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>?[ +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> not/output?[pdf]| +<span class="line-numbers"><a href="#n3" name="n3">3</a></span> ... +<span class="line-numbers"><a href="#n4" name="n4">4</a></span>]</pre></div> +</div> + + +<p>In this case, the <a href="/glyph/book/macros/macros_core.html#m_not"><code>not</code></a> macro was composed with the <a href="/glyph/book/macros/macros_core.html#m_output_"><code>output?</code></a> macro, thus removing one level of nesting.</p> +<p>Composition can be useful to simplify complex Glyph macro constructs, but also for <em>macro dispatching</em>. Currently, Glyph supports two <em>dispatchers</em>:</p> +<ul> + <li>The <a href="/glyph/book/macros/macros_core.html#m_s"><code>s</code></a> macro, used to call almost any method of the Ruby String class.</li> + <li>The <a href="/glyph/book/macros/macros_core.html#m_xml"><code>xml</code></a> macro, used to render raw <span class="caps">XML</span> tags.</li> +</ul> +<nav class="navigation"><a href="/glyph/book/text_editing/attribute_intro.html">← Macro attributes</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/esc_quot.html">Escaping and Quoting →</a></nav>
A
contents/glyph/book/text_editing/macro_intro.html
@@ -0,0 +1,20 @@
+----- +title: "Glyph – Introducing Glyph Macros" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/text_editing/glyph_files.html">← <code>.glyph</code> files</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/attribute_intro.html">Macro attributes →</a></nav> + + <p>The most important concept to grasp about Glyph is the concept of <em>macro</em>.</p> +<p>A Glyph macro is, in a nutshell, an identifier of some kind that wraps a value or parameters within square brackets. More specifically:</p> +<ul> + <li>The macro identifier can contain <em>any</em> character except for: <code>[</code>, <code>]</code>, <code>\</code>, <code>|</code>, <code>@</code> or spaces.</li> + <li>The delimiters can be either <code>[</code> and <code>]</code> or <code>[=</code> and <code>=]</code> (<span class="fmi">for more information on <mark>differences between delimiters</mark>, see <a href="/glyph/book/text_editing/esc_quot.html#esc_quot">Escaping and Quoting</a></span>).</li> + <li>The value can be anything, even other macros. If a macro supports more than one parameter, they must be separated with <code>|</code>. For example, the <a href="/glyph/book/macros/macros_inline.html#m_link"><code>link</code></a> macro can take an optional second parameter for the link text: <code>link[#link_id|This is the link text]</code>.</li> + <li>A macro can also have <em>attributes</em>, which look exactly like macros but their identifier starts with a <code>@</code>.</li> +</ul> +<p>A macro can often have one or more aliases. For example, <code>=></code> is an alias for the <a href="/glyph/book/macros/macros_inline.html#m_link"><code>link</code></a> macro, so the following macro calls are equivalent:</p> +<ul> + <li><code>=>[#test|Test Section]</code></li> + <li><code>link[#test|Test Section]</code></li> +</ul> +<nav class="navigation"><a href="/glyph/book/text_editing/glyph_files.html">← <code>.glyph</code> files</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/attribute_intro.html">Macro attributes →</a></nav>
A
contents/glyph/book/text_editing/raw_html.html
@@ -0,0 +1,39 @@
+----- +title: "Glyph – Textile or Markdown" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/text_editing/code.html">← Source Code</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/xml_fallback.html">XML Fallback →</a></nav> + <p> +Textile or Markdown are very easy and intuitive to use, and they can produce HTML markup with almost no effort. Using them with Glyph is as simple as using the <a href="/glyph/book/macros/macros_filters.html#m_textile"><code>textile</code></a> macro (aliased to <code>txt</code>) and the <a href="/glyph/book/macros/macros_filters.html#m_markdown"><code>markdown</code></a> macro (aliased to <code>md</code>). +</p> + <aside class="box"> +<div class="box-title">Example</div> +<p>The following Glyph code:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>textile[ +<span class="line-numbers"><a href="#n2" name="n2">2</a></span>This is a paragraph with some _emphasized_ text. +<span class="line-numbers"><a href="#n3" name="n3">3</a></span> +<span class="line-numbers"><a href="#n4" name="n4">4</a></span>This is another paragraph with some -deleted- text. +<span class="line-numbers"><a href="#n5" name="n5">5</a></span>* This is +<span class="line-numbers"><a href="#n6" name="n6">6</a></span>* a bulletted +<span class="line-numbers"><a href="#n7" name="n7">7</a></span>* list +<span class="line-numbers"><a href="#n8" name="n8">8</a></span>]</pre></div> +</div> + + <p>produces the following HTML code:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span><span class="tag"><p></span>This is a paragraph with some <span class="tag"><em></span>emphasized<span class="tag"></em></span> text.<span class="tag"></p></span> +<span class="line-numbers"><a href="#n2" name="n2">2</a></span><span class="tag"><p></span>This is a paragraph with some <span class="tag"><del></span>deleted<span class="tag"></del></span> text.<span class="tag"></p></span> +<span class="line-numbers"><a href="#n3" name="n3">3</a></span><span class="tag"><ul></span> +<span class="line-numbers"><a href="#n4" name="n4">4</a></span> <span class="tag"><li></span>This is<span class="tag"></li></span> +<span class="line-numbers"><a href="#n5" name="n5">5</a></span> <span class="tag"><li></span>a bulletted<span class="tag"></li></span> +<span class="line-numbers"><a href="#n6" name="n6">6</a></span> <span class="tag"><li></span>list<span class="tag"></li></span> +<span class="line-numbers"><a href="#n7" name="n7">7</a></span><span class="tag"></ul></span></pre></div> +</div> + +</aside> + <aside class="important"> +<span class="note-title">Important</span>Be careful when using block-level HTML with Textile and Markdown: sometimes it may be necessary to add extra empty lines or escape tags. + +</aside> +<nav class="navigation"><a href="/glyph/book/text_editing/code.html">← Source Code</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/xml_fallback.html">XML Fallback →</a></nav>
A
contents/glyph/book/text_editing/section_aliases.html
@@ -0,0 +1,46 @@
+----- +title: "Glyph – Section Aliases" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/text_editing/sections.html">← Sections and Headers</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/topics.html">Topics →</a></nav> + <p>There are <em>a lot</em> of macros that can be used in the same way as <code>section</code>, one for each element commonly used in <a href="http://en.wikipedia.org/wiki/Book_design">book design</a>.</p> +<p>The following table lists the identifiers of all section-like macros, divided according to the part of the book they should be placed in:</p> + <table> + <tr> + <th>Frontmatter</th> + <td> +<p><code>imprint</code> <sup>†</sup>, <code>dedication</code> <sup>†</sup>, <code>inspiration</code> <sup>†</sup>, <code>foreword</code> <sup>‡</sup>, <code>introduction</code> <sup>‡</sup>, <code>acknowledgement</code> <sup>‡</sup>, <code>prologue</code> <sup>‡</sup>, <code>toc</code> <sup>*</sup></p> +</td> + </tr> + <tr> + <th>Bodymatter</th> + <td> +<p><code>volume</code>, <code>book</code>, <code>part</code>, <code>chapter</code></p> +</td> + </tr> + <tr> + <th>Backmatter</th> + <td> +<p><code>epilogue</code> <sup>‡</sup>, <code>afterword</code> <sup>‡</sup>, <code>postscript</code> <sup>†</sup>, <code>appendix</code>, <code>addendum</code> <sup>‡</sup>, <code>glossary</code> <sup>**‡</sup>, <code>colophon</code> <sup>†</sup>, <code>bibliography</code> <sup>**‡</sup>, <code>promotion</code> <sup>†</sup>, <code>references</code> <sup>**‡</sup>, <code>index</code> <sup>**‡</sup>, <code>lot</code> <sup>**‡</sup>, <code>lof</code> <sup>**‡</sup></p> +</td> + </tr> + </table> + + <p> +<strong>*</strong>: The <a href="/glyph/book/macros/macros_structure.html#m_toc"><code>toc</code></a> macro is used to generate the Table of Contents automatically, and it takes no parameters. +</p> + <p> +<strong>**</strong>: This macro is likely to be extended in future versions to generate/aggregate content automatically. +</p> + <p> +<strong>†</strong>: This section is not listed in the Table of Contents. +</p> + <p> +<strong>‡</strong>: Any subsection of this section is not listed in the Table of Contents. +</p> + + <aside class="note"> +<span class="note-title">Note</span><code>frontmatter</code>, <code>bodymatter</code> and <code>backmatter</code> are also macro identifiers, but they are also exposed as attributes for the <a href="/glyph/book/macros/macros_structure.html#m_book"><code>book</code></a> macro and the <a href="/glyph/book/macros/macros_structure.html#m_article"><code>article</code></a> macro, so if you're using either of these two macros as your root macro for your document, there's no need to use them explicitly. + +</aside> +<nav class="navigation"><a href="/glyph/book/text_editing/sections.html">← Sections and Headers</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/topics.html">Topics →</a></nav>
A
contents/glyph/book/text_editing/sections.html
@@ -0,0 +1,64 @@
+----- +title: "Glyph – Sections and Headers" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/text_editing/esc_quot.html">← Escaping and Quoting</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/section_aliases.html">Section Aliases →</a></nav> + + <p>Glyph documents are normally organized as a hierarchical tree of nested chapters, appendixes, sections, etc. To define a section, use the <a href="/glyph/book/macros/macros_structure.html#m_section"><code>section</code></a> macro (aliased by <code>§</code>), like so:</p> + + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>section[ +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> @title[Section #1] +<span class="line-numbers"><a href="#n3" name="n3">3</a></span>Write the section contents here... +<span class="line-numbers"><a href="#n4" name="n4">4</a></span> section[ +<span class="line-numbers"><a href="#n5" name="n5">5</a></span> @title[Section #2] +<span class="line-numbers"><a href="#n6" name="n6">6</a></span>This section is nested into the previous one. +<span class="line-numbers"><a href="#n7" name="n7">7</a></span> ] --[End of Section #2] +<span class="line-numbers"><a href="#n8" name="n8">8</a></span>] --[End of Section #1]</pre></div> +</div> + + + <p>This example defines two nested sections. If the <code>@title</code> attribute is specified like in this case, it will be converted to a proper <span class="caps">HTML</span> header and it will appear in the Table of Contents (see the <a href="/glyph/book/macros/macros_structure.html#m_toc"><code>toc</code></a> macro).</p> +<p>Note an important difference from <span class="caps">HTML</span>: there is no need for an explicit level for the headers, as it will be determined at runtime when the document is compiled, based on how sections are nested. The previous code snippet (taken as it is), for example, will be transformed into the following <span class="caps">HTML</span> code:</p> + + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span><span class="tag"><div</span> <span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">section</span><span class="delimiter">"</span></span><span class="tag">></span> +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> <span class="tag"><h2></span>Section #1<span class="tag"></h2></span> +<span class="line-numbers"><a href="#n3" name="n3">3</a></span> <span class="tag"><p></span>Write the section contents here...<span class="tag"></p></span> +<span class="line-numbers"><a href="#n4" name="n4">4</a></span> <span class="tag"><div</span> <span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">section</span><span class="delimiter">"</span></span><span class="tag">></span> +<span class="line-numbers"><a href="#n5" name="n5">5</a></span> <span class="tag"><h3></span>Section #2<span class="tag"></h3></span> +<span class="line-numbers"><a href="#n6" name="n6">6</a></span> <span class="tag"><p></span>This section is nested in the previous one<span class="tag"></p></span> +<span class="line-numbers"><a href="#n7" name="n7">7</a></span> <span class="tag"></div></span> +<span class="line-numbers"><a href="#n8" name="n8">8</a></span><span class="tag"></div></span></pre></div> +</div> + + + <p>By default, in Glyph the first header level is <em>2</em>, so the two headers are rendered as <code>h2</code> and <code>h3</code>, respectively (<code>--[...]</code> macros are <em>comments</em>, therefore they are not included in the final output).</p> + <section class="section"> +<header><h1 id="h_25" class="toc">Markup-aware sections</h1></header> +<p>Although Glyph can be used on its own to produce valid <span class="caps">HTML</span> or <span class="caps">XML</span> code, you may often want to use Textile or Markdown to save some typing. Typically, you’ll end up writing a lot of code like this:</p> + + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>section[ +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> @title[My Textile section] +<span class="line-numbers"><a href="#n3" name="n3">3</a></span> textile[ +<span class="line-numbers"><a href="#n4" name="n4">4</a></span>Textile markup can be used _here_. +<span class="line-numbers"><a href="#n5" name="n5">5</a></span> ] +<span class="line-numbers"><a href="#n6" name="n6">6</a></span>]</pre></div> +</div> + + <p>To save you even more typing, you can use the <a href="/glyph/book/macros/macros_filters.html#m_textile_section"><code>textile_section</code></a> macro (aliased by <code>txt_section</code> and <code>§txt</code>) and the <a href="/glyph/book/macros/macros_filters.html#m_markdown_section"><code>markdown_section</code></a> macro (aliased by <code>md_section</code> and <code>§md</code>). By doing so, the previous code snippet can be written like this:</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>§txt[ +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> @title[My Textile section] +<span class="line-numbers"><a href="#n3" name="n3">3</a></span>Textile markup can be used _here_. +<span class="line-numbers"><a href="#n4" name="n4">4</a></span>]</pre></div> +</div> + + <aside class="tip"> +<span class="note-title">Tip</span><p>On an Italian keyboard, you can type a <code>§</code> character by pressing <strong><span class="caps">SHIFT</span> + ù</strong>. Unfortunately, that’s about the only useful thing an Italian keyboard does. If you use Vim, you can map it to some key sequence like <code>''s</code>, like this: <code>map! ''s <C-V>u00A7</code>.</p> + +</aside> + +</section> +<nav class="navigation"><a href="/glyph/book/text_editing/esc_quot.html">← Escaping and Quoting</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/section_aliases.html">Section Aliases →</a></nav>
A
contents/glyph/book/text_editing/stylesheets.html
@@ -0,0 +1,53 @@
+----- +title: "Glyph – Adding Stylesheets" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/text_editing/xml_fallback.html">← XML Fallback</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/inclusions.html">Content Reuse →</a></nav> + <p>Currently, Glyph does not provide any native way to format text and pages. The reason is that there's absolutely no need for that: CSS does the job just fine. In particular, CSS3 offers specific attributes and elements that can be used specifically for paginated documents. That's no replacement for LaTeX by any means, but it is enough if you're not looking for advanced typographical features.</p> + <p>You can embed CSS files using the <a href="/glyph/book/macros/macros_structure.html#m_style"><code>style</code></a> macro, like this:</p> + <p> +<code> style[default.css] </code> +</p> + <p>In this case, the <a href="/glyph/book/macros/macros_structure.html#m_style"><code>style</code></a> macro looks for a <code>default.css</code> file in the <code>/styles</code> folder of your Glyph project <em>and</em> among the default Glyph stylesheets, and embeds it within a <code><style></code> tag. If you supply a file with a <code>.sass</code> or <code>.scss</code> extension, it will interpret it as a Sass file and convert it to <span class="caps">CSS</span> automatically (if the <em>Haml</em> gem is installed).</p> + <aside class="tip"> +<span class="note-title">Tip</span>By default, stylesheets are embedded within text files. If necessary, you can choose to link them or import them by changing the values of the <a href="/glyph/book/config/document.html#s_document_styles"><code>document.styles</code></a> setting. + +</aside> + <section class="section"> +<header><h1 id="default_stylesheets" class="toc">Default Stylesheets</h1></header> +<p>Glyph provides the following default stylesheets, that can be referenced directly using the <a href="/glyph/book/macros/macros_structure.html#m_style"><code>style</code></a> macro:</p> + <table> + <tr> + <th>File name</th> + <th>Notes</th> + </tr> + <tr> + <td> +<code>default.css</code> +</td> + <td>The stylesheet used for this book.</td> + </tr> + <tr> + <td> +<code>pagination.css</code> +</td> + <td>A CSS3-compliant stylesheet used for pagination, suitable for PDF generation using <a href="http://www.princexml.com/">Prince</a>.</td> + </tr> + <tr> + <td> +<code>coderay.css</code> +</td> + <td>The default <a href="http://coderay.rubychan.de/">Coderay</a> stylesheet, used for syntax highlighting.</td> + </tr> + <tr> + <td> +<code>ultraviolet/*</code> +</td> + <td>This folder contains the following <a href="http://ultraviolet.rubyforge.org/">Ultraviolet</a> stylesheets, used for syntax highlighting: <code> +active4d.css, all_hallows_eve.css, amy.css, blackboard.css, brilliance_black.css, brilliance_dull.css, cobalt.css, dawn.css, eiffel.css, espresso_libre.css, idle.css, iplastic.css, lazy.css, mac_classic.css, magicwb_amiga.css, pastels_on_dark.css, slush_poppies.css, spacecadet.css, sunburst.css, twilight.css, zenburnesque.css +</code></td> + </tr> + </table> + +</section> +<nav class="navigation"><a href="/glyph/book/text_editing/xml_fallback.html">← XML Fallback</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/inclusions.html">Content Reuse →</a></nav>
A
contents/glyph/book/text_editing/topics.html
@@ -0,0 +1,38 @@
+----- +title: "Glyph – Topics" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/text_editing/section_aliases.html">← Section Aliases</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/links.html">Links and Bookmarks →</a></nav> +<p>Sections can also be used to create <em>topics</em>. In a technical writing context, the term topic identifies a single page of an online help (e.g. a Compiled <span class="caps">HTML</span> file, or <span class="caps">CHM</span>). Topics should generally be:</p> +<ul> + <li>self-contained, in the sense that they should make sense on their own, ideally without the need to be read in sequence</li> + <li>be used for either <em>concepts</em>, <em>tasks</em> or <em>references</em></li> + <li>be divided into meaningful sections like <em>Introduction</em>, <em>Procedure</em>, <em>Result</em></li> +</ul> +<p>Glyph does not formally enforce the correctness of topic composition and usage, but it does enable authors to create them as a sort of external sections. Consider the following Glyph code:</p> +<div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>section[ +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> @title[My First Topic] +<span class="line-numbers"><a href="#n3" name="n3">3</a></span> @id[first_topic] +<span class="line-numbers"><a href="#n4" name="n4">4</a></span> @src[test/first_topic.glyph] +<span class="line-numbers"><a href="#n5" name="n5">5</a></span>]</pre></div> +</div> + +<p>This is an ordinary section with a title and an explicit ID, but it has no contents. Instead, its <code>@src</code> attribute references an external file. If you are generating a single-file document, like a standalone <span class="caps">HTML</span> file or a <span class="caps">PDF</span> file, the code snippet above is exactly the same as the following:</p> +<div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>section[ +<span class="line-numbers"><a href="#n2" name="n2">2</a></span> @title[My First Topic] +<span class="line-numbers"><a href="#n3" name="n3">3</a></span> @id[first_topic] +<span class="line-numbers"><a href="#n4" name="n4">4</a></span> include[test/first_topic.glyph] +<span class="line-numbers"><a href="#n5" name="n5">5</a></span>]</pre></div> +</div> + +<p>On the other hand, if you are planning on producing a document comprised of multiple files (see <a href="/glyph/book/compiling/compiling.html#web_output">Web/Web5 Output</a>), the <code>@src</code> attribute tells Glyph to create a <em>topic</em> for the section. In this case:</p> +<ul> + <li>The <code>@title</code> attribute must be specified and is used as the topic title</li> + <li>The body of the topic is constituted by the contents of the file referenced by the <code>@src</code> attribute.</li> + <li>The topic file is rendered according to a specific <a href="/glyph/book/extending/layouts.html#layouts">layout</a>.</li> + <li>The location of the topic is the same as the location of the included file, mirrored in the output folder.</li> + <li>Glyph takes care of changing the file extensions and resolving links automatically, regardless of the output target.</li> +</ul> +<nav class="navigation"><a href="/glyph/book/text_editing/section_aliases.html">← Section Aliases</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/links.html">Links and Bookmarks →</a></nav>
A
contents/glyph/book/text_editing/xml_fallback.html
@@ -0,0 +1,102 @@
+----- +title: "Glyph – XML Fallback" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/text_editing/raw_html.html">← Textile or Markdown</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/stylesheets.html">Adding Stylesheets →</a></nav> + <p>Sure Textile and Markdown are great, but sometimes you may want to just use HTML, without the extra verbosity, of course. Take tables for example: Textile offers an easy way to create them, but things may get dirty when you need to have multiple paragraphs or lists within cells.</p> + <p>Very early versions of Glyph used to offered some simple <code>table</code>, <code>tr</code>, <code>tr</code>, <code>td</code> macros just for that. Of course the problem was that thy didn't offer any way to customize the markup by adding, for example, CSS classes.</p> + <p>Instead, by default, Glyph can convert any unrecognized macro to the corresponding XML element and macro attributes to XML attributes.</p> + <aside class="box"> +<div class="box-title">Example</div> +<p> +The following Glyph code: +</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span>table[@class[features] +<span class="line-numbers"> <a href="#n2" name="n2">2</a></span> tr[ +<span class="line-numbers"> <a href="#n3" name="n3">3</a></span> th[ID] +<span class="line-numbers"> <a href="#n4" name="n4">4</a></span> th[Priority] +<span class="line-numbers"> <a href="#n5" name="n5">5</a></span> th[Description] +<span class="line-numbers"> <a href="#n6" name="n6">6</a></span> ] +<span class="line-numbers"> <a href="#n7" name="n7">7</a></span> tr[ +<span class="line-numbers"> <a href="#n8" name="n8">8</a></span> td[27] +<span class="line-numbers"> <a href="#n9" name="n9">9</a></span> td[span[@style[color:red;font-weight:bold;] HIGH]] +<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span> td[HTML output] +<span class="line-numbers"><a href="#n11" name="n11">11</a></span> ] +<span class="line-numbers"><a href="#n12" name="n12">12</a></span> tr[ +<span class="line-numbers"><a href="#n13" name="n13">13</a></span> td[42] +<span class="line-numbers"><a href="#n14" name="n14">14</a></span> td[span[@style[color:green;font-weight:bols;] LOW]] +<span class="line-numbers"><a href="#n15" name="n15">15</a></span> td[ +<span class="line-numbers"><a href="#n16" name="n16">16</a></span> p[Support for less-used tags:] +<span class="line-numbers"><a href="#n17" name="n17">17</a></span> ul[ +<span class="line-numbers"><a href="#n18" name="n18">18</a></span> li[cite] +<span class="line-numbers"><a href="#n19" name="n19">19</a></span> li[sup] +<span class="line-numbers"><strong><a href="#n20" name="n20">20</a></strong></span> li[...] +<span class="line-numbers"><a href="#n21" name="n21">21</a></span> ] +<span class="line-numbers"><a href="#n22" name="n22">22</a></span> ] +<span class="line-numbers"><a href="#n23" name="n23">23</a></span> ] +<span class="line-numbers"><a href="#n24" name="n24">24</a></span>]</pre></div> +</div> + + <p> +Is translated into the following HTML code: +</p> + <div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span><span class="tag"><table</span> <span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">features</span><span class="delimiter">"</span></span><span class="tag">></span> +<span class="line-numbers"> <a href="#n2" name="n2">2</a></span> <span class="tag"><tr></span> +<span class="line-numbers"> <a href="#n3" name="n3">3</a></span> <span class="tag"><th></span>ID<span class="tag"></th></span> +<span class="line-numbers"> <a href="#n4" name="n4">4</a></span> <span class="tag"><th></span>Priority<span class="tag"></th></span> +<span class="line-numbers"> <a href="#n5" name="n5">5</a></span> <span class="tag"><th></span>Description<span class="tag"></th></span> +<span class="line-numbers"> <a href="#n6" name="n6">6</a></span> <span class="tag"></tr></span> +<span class="line-numbers"> <a href="#n7" name="n7">7</a></span> <span class="tag"><tr></span> +<span class="line-numbers"> <a href="#n8" name="n8">8</a></span> <span class="tag"><td></span>27<span class="tag"></td></span> +<span class="line-numbers"> <a href="#n9" name="n9">9</a></span> <span class="tag"><td></span><span class="tag"><span</span> <span class="attribute-name">style</span>=<span class="string"><span class="delimiter">"</span><span class="key">color</span>:<span class="value">red</span>;<span class="key">font-weight</span>:<span class="value">bold</span>;<span class="delimiter">"</span></span><span class="tag">></span>HIGH<span class="tag"></span></span><span class="tag"></td></span> +<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span> <span class="tag"><td></span>HTML output<span class="tag"></td></span> +<span class="line-numbers"><a href="#n11" name="n11">11</a></span> <span class="tag"></tr></span> +<span class="line-numbers"><a href="#n12" name="n12">12</a></span> <span class="tag"><tr></span> +<span class="line-numbers"><a href="#n13" name="n13">13</a></span> <span class="tag"><td></span>42<span class="tag"></td></span> +<span class="line-numbers"><a href="#n14" name="n14">14</a></span> <span class="tag"><td></span><span class="tag"><span</span> <span class="attribute-name">style</span>=<span class="string"><span class="delimiter">"</span><span class="key">color</span>:<span class="value">green</span>;<span class="key">font-weight</span>:<span class="value">bold</span>;<span class="delimiter">"</span></span><span class="tag">></span>LOW<span class="tag"></span></span><span class="tag"></td></span> +<span class="line-numbers"><a href="#n15" name="n15">15</a></span> <span class="tag"><td></span> +<span class="line-numbers"><a href="#n16" name="n16">16</a></span> <span class="tag"><p></span>Support for less-used tags:<span class="tag"></p></span> +<span class="line-numbers"><a href="#n17" name="n17">17</a></span> <span class="tag"><ul></span> +<span class="line-numbers"><a href="#n18" name="n18">18</a></span> <span class="tag"><li></span>cite<span class="tag"></li></span> +<span class="line-numbers"><a href="#n19" name="n19">19</a></span> <span class="tag"><li></span>sup<span class="tag"></li></span> +<span class="line-numbers"><strong><a href="#n20" name="n20">20</a></strong></span> <span class="tag"><li></span>...<span class="tag"></li></span> +<span class="line-numbers"><a href="#n21" name="n21">21</a></span> <span class="tag"></ul></span> +<span class="line-numbers"><a href="#n22" name="n22">22</a></span> <span class="tag"></td></span> +<span class="line-numbers"><a href="#n23" name="n23">23</a></span> <span class="tag"></tr></span> +<span class="line-numbers"><a href="#n24" name="n24">24</a></span><span class="tag"></table></span></pre></div> +</div> + +</aside> + <p>Basically, if the <a href="/glyph/book/config/options.html#s_options_xml_fallback"><code>options.xml_fallback</code></a> setting is set to <code>true</code>, any macro unknown to Glyph with at most one parameter will be converted to an XML tag with the same name and any attribute will be converted to the corresponding XML attribute.</p> + <aside class="important"> +<span class="note-title">Important</span>While macro names and attributes are validated so that an error is returned if they contain illegal character, no check is performed against any particular XML schema. + +</aside> + <p>Additionally, it is possible to force macro-to-<span class="caps">XML</span> conversion by composing the name of a tag with the <a href="/glyph/book/macros/macros_core.html#m_xml"><code>xml</code></a> macro, so for example <code>xml/snippet[test]</code> will be converted into <code><snippet>test</snippet></code>.</p> + <section class="section"> +<header><h1 id="xml_blacklist" class="toc">Blacklisted XML tags</h1></header> +<p>By default, the following tags are blacklisted and will be ignored:</p> +<ul> + <li><code>applet</code></li> + <li><code>base</code></li> + <li><code>basefont</code></li> + <li><code>embed</code></li> + <li><code>frame</code></li> + <li><code>frameset</code></li> + <li><code>iframe</code></li> + <li><code>isindex</code></li> + <li><code>meta</code></li> + <li><code>noframes</code></li> + <li><code>noscript</code></li> + <li><code>object</code></li> + <li><code>param</code></li> + <li><code>title</code></li> +</ul> +<aside class="tip"> +<p><span class="note-title">Tip</span>You can change this list by modifying the <a href="/glyph/book/config/options.html#s_options_xml_blacklist"><code>options.xml_blacklist</code></a> setting.</p> +</aside> + +</section> +<nav class="navigation"><a href="/glyph/book/text_editing/raw_html.html">← Textile or Markdown</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/stylesheets.html">Adding Stylesheets →</a></nav>
A
contents/glyph/book/troubleshooting/errors_command.html
@@ -0,0 +1,76 @@
+----- +title: "Glyph – Command Errors" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/troubleshooting/errors_parser.html">← Parsing Errors</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/troubleshooting/errors_macro.html">Macro Errors →</a></nav> + + <table style="width:100%;"> + <tr> + <th style="width:30%">Error Message</th> + <th>Description</th> + </tr> + <tr> + <td>Source file '<em>source_file</em>' does not exist</td> + <td>Returned if Glyph is running in <a href="/glyph/book/compiling/lite_mode.html#lite_mode">lite mode</a> and the specified source file was not found.</td> + </tr> + + + <tr> + <td>Source and destination file are the same</td> + <td>Returned if Glyph is running in <a href="/glyph/book/compiling/lite_mode.html#lite_mode">lite mode</a> and you specified the same source and destination files.</td> + </tr> + + + <tr> + <td>DirectoryWatcher is not available. Install it with: gem install directory_watcher</td> + <td>Returned if <a href="/glyph/book/compiling/compiling.html#auto_regeneration">auto regeneration</a> is enabled but the <code>directory_watcher</code> gem in not installed.</td> + </tr> + + + <tr> + <td>Document cannot be finalized due to previous errors</td> + <td>Returned if one or more errors occurred in the document prevented finalization.</td> + </tr> + + + <tr> + <td>Please specify a file name</td> + <td>No file name was specified for the <a href="/glyph/book/ref_commands.html#c_add"><code>add</code></a> command.</td> + </tr> + + + <tr> + <td>Output target not specified</td> + <td>Returned if no target was specified for the <a href="/glyph/book/ref_commands.html#c_compile"><code>compile</code></a> command _and_ if the <a href="/glyph/book/config/document.html#s_document_output"><code>document.output</code></a> setting is not set.</td> + </tr> + + + <tr> + <td>Unknown output target '<em>target_name</em>'</td> + <td>An unsupported output target was specified for the <a href="/glyph/book/ref_commands.html#c_compile"><code>compile</code></a> command. Only the following output targets are supported: + <ul> + <li>html</li> + <li>pdf</li> + </ul></td> + </tr> + + + <tr> + <td>Too few/too many arguments</td> + <td>Returned if the <a href="/glyph/book/ref_commands.html#c_config"><code>config</code></a> command was used with no arguments or more than two arguments respectively.</td> + </tr> + + + <tr> + <td>Unknown setting '<em>setting_name</em>'</td> + <td>The name of an unknown setting was specified for the <a href="/glyph/book/ref_commands.html#c_config"><code>config</code></a> command.</td> + </tr> + + + <tr> + <td>Cannot reset '<em>setting_name</em>' setting (system use only).</td> + <td>Returned by the <a href="/glyph/book/ref_commands.html#c_config"><code>config</code></a> command when attempting to override a setting in the <code>system.*</code> namespace.</td> + </tr> + </table> + +<nav class="navigation"><a href="/glyph/book/troubleshooting/errors_parser.html">← Parsing Errors</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/troubleshooting/errors_macro.html">Macro Errors →</a></nav>
A
contents/glyph/book/troubleshooting/errors_generic.html
@@ -0,0 +1,108 @@
+----- +title: "Glyph – Generic Errors" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/extending/command.html">← Defining Custom Commands</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/troubleshooting/errors_parser.html">Parsing Errors →</a></nav> + + <table style="width:100%;"> + <tr> + <th style="width:30%">Error Message</th> + <th>Description</th> + </tr> + <tr> + <td>Invalid alias: macro '<em>macro_name</em>' already exists</td> + <td>The alias name supplied to the <code>macro_alias</code> method has already been used for another macro or alias.</td> + </tr> + + + <tr> + <td>Undefined macro '<em>macro_name</em>'</td> + <td>The document contains a macro that does not exist, i.e. it is not a standard or used-defined <a href="/glyph/book/document.html#macro_ref">Glyph macro or alias</a>.</td> + </tr> + + + <tr> + <td>No macro representation for '<em>macro_name</em>'</td> + <td>There is no valid macro representation for the specified macro.</td> + </tr> + + + <tr> + <td>An error occurred when generating _file-name_.pdf</td> + <td>Returned if Prince could not generate the PDF file or if Prince is not installed. Normally, Prince provides additional details on the specific error(s).</td> + </tr> + + + <tr> + <td>Glyph cannot generate PDF. Please specify a valid output.pdf.generator setting</td> + <td>Returned if the <a href="/glyph/book/config/output.html#s_output_pdf_generator"><code>output.pdf.generator</code></a> setting has not be set to a valid PDF renderer. Currently, the only supported values for this setting are <code>prince</code> and <code>wkhtmltopdf</code>.</td> + </tr> + + + <tr> + <td>Glyph cannot generate e-book. At present, output.<em>ebook_format</em>.generator can only be set to 'calibre'.</td> + <td>Returned if the output.<em>ebook_format</em>.generator setting has not be set to @calibre@.</td> + </tr> + + + <tr> + <td>The current directory is not a valid Glyph project</td> + <td>Returned if a glyph command was executed outside a valid glyph project directory.</td> + </tr> + + + <tr> + <td>Invalid snippet file</td> + <td>The <code>snippet.yml</code> file contains invalid data. Most likely, it does not evaluate to a Ruby <code>Hash</code>.</td> + </tr> + + + <tr> + <td>Directory '<em>directory_name</em>' is not empty</td> + <td>Returned when executing the <a href="/glyph/book/ref_commands.html#c_init"><code>init</code></a> command in a directory that is not empty.</td> + </tr> + + + <tr> + <td>File '<em>file_name</em>' already exists</td> + <td>Returned if the name of an existing file was specified as a parameter for the <a href="/glyph/book/ref_commands.html#c_add"><code>add</code></a> command.</td> + </tr> + + + <tr> + <td>Unknown macro '<em>macro_name</em>'</td> + <td>Returned by the <a href="/glyph/book/ref_commands.html#c_stats"><code>stats</code></a> command if the specified macro was not found.</td> + </tr> + + + <tr> + <td>Macro '<em>macro_name</em>' is not used in this document</td> + <td>Returned by the <a href="/glyph/book/ref_commands.html#c_stats"><code>stats</code></a> command if the specified macro is defined but unused.</td> + </tr> + + + <tr> + <td>Bookmark '<em>bookmark_name</em>' does not exist</td> + <td>Returned by the <a href="/glyph/book/ref_commands.html#c_stats"><code>stats</code></a> command if the specified bookmark does not exist.</td> + </tr> + + + <tr> + <td>No link matching /<em>regexp</em>/ was found</td> + <td>Returned by the <a href="/glyph/book/ref_commands.html#c_stats"><code>stats</code></a> command if the no link target matches the supplied regular expression.</td> + </tr> + + + <tr> + <td>Unknown snippet '<em>snippet_name</em>'</td> + <td>Returned by the <a href="/glyph/book/ref_commands.html#c_stats"><code>stats</code></a> command if the specified snippet was not found.</td> + </tr> + + + <tr> + <td>Snippet '<em>snippet_name</em>' is not used in this document</td> + <td>Returned by the <a href="/glyph/book/ref_commands.html#c_stats"><code>stats</code></a> command if the specified snippet is defined but unused.</td> + </tr> + </table> + +<nav class="navigation"><a href="/glyph/book/extending/command.html">← Defining Custom Commands</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/troubleshooting/errors_parser.html">Parsing Errors →</a></nav>
A
contents/glyph/book/troubleshooting/errors_macro.html
@@ -0,0 +1,186 @@
+----- +title: "Glyph – Macro Errors" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/troubleshooting/errors_command.html">← Command Errors</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/ref_commands.html">Command Reference →</a></nav> + <p>The following errors are displayed in the form:</p> +<p><em>message</em><br /> + source: <em>macro_source</em><br /> + path: <em>macro_path</em></p> +<p><em>macro_value</em></p> +<p>Where:</p> +<ul> + <li><em>message</em> is the error message.</li> + <li><em>macro_source</em> is the file or snippet where the error occurred.</li> + <li><em>macro_path</em> is the full path to the macro that returned the error, within the document syntax tree, e.g. <code>document/body/bodymatter/chapter/section/header/&</code> if the error occurrent in a snippet within the header of a section in the <code>bodymatter</code> part of the document.</li> + <li><em>macro_value</em> is the value of the macro (shown only if Glyph is running in <a href="/glyph/book/ref_commands.html#debug_switch">debug mode</a>).</li> +</ul> + + <table style="width:100%;"> + <tr> + <th style="width:30%">Error Message</th> + <th>Description</th> + </tr> + <tr> + <td>Macro '<em>name</em>' takes up to <em>x</em> parameter(s) (<em>y</em> given)</td> + <td>Returned if the macro was called with extra parameters.</td> + </tr> + + + <tr> + <td>Macro '<em>name</em>' takes at least <em>x</em> parameter(s) (<em>y</em> given)</td> + <td>Returned if the macro was called with fewer parameters than expected.</td> + </tr> + + + <tr> + <td>Macro '<em>name</em>' takes exactly <em>x</em> parameter(s) (<em>y</em> given)</td> + <td>Returned if the macro was called with a different number of parameters than.</td> + </tr> + + + <tr> + <td>Macro not available when compiling a single file.</td> + <td>Returned by the <a href="/glyph/book/macros/macros_core.html#m_include"><code>include</code></a> macro if used in <a href="/glyph/book/compiling/lite_mode.html#lite_mode">lite mode</a>.</td> + </tr> + + + <tr> + <td>Filter macro '<em>extension</em>' not available</td> + <td>Returned by a filter macro if <a href="/glyph/book/config/options.html#s_options_filters_by_file_extension"><code>options.filters_by_file_extension</code></a> setting is set to @true@, but the extension was not recognized.</td> + </tr> + + + <tr> + <td>Invalid regular expression: <em>regexp</em></td> + <td>Returned by the <a href="/glyph/book/macros/macros_core.html#m_match"><code>match</code></a> macro if an invalid regular expression was supplied.</td> + </tr> + + + <tr> + <td>Macro '<em>name</em>' takes no parameters (<em>x</em> given)</td> + <td>Returned if the macro was called with parameters but none are requested.</td> + </tr> + + + <tr> + <td>No highlighter installed. Please run: gem install coderay</td> + <td>Returned by the <a href="/glyph/book/macros/macros_filters.html#m_highlight"><code>highlight</code></a> macro if no highlighters are installed.</td> + </tr> + + + <tr> + <td>CodeRay highlighter not installed. Please run: gem install coderay</td> + <td>Returned by the <a href="/glyph/book/macros/macros_filters.html#m_highlight"><code>highlight</code></a> macro if <a href="/glyph/book/config/filters.html#s_filters_highlighter"><code>filters.highlighter</code></a> setting is set to @coderay@ but <a href="http://coderay.rubychan.de/">Coderay</a> is not installed.</td> + </tr> + + + <tr> + <td>UltraViolet highlighter not installed. Please run: gem install ultraviolet</td> + <td>Returned by the <a href="/glyph/book/macros/macros_filters.html#m_highlight"><code>highlight</code></a> macro if <a href="/glyph/book/config/filters.html#s_filters_highlighter"><code>filters.highlighter</code></a> setting is set to @ultraviolet@ but <a href="http://ultraviolet.rubyforge.org/">Ultraviolet</a> is not installed.</td> + </tr> + + + <tr> + <td>Mutual Inclusion in parameter/attribute(<em>name</em>): '<em>value</em>'</td> + <td>Returned if a catch-22 situation occurs with macro inclusion, for example if the value of a snippet includes a reference to the same snippet.</td> + </tr> + + + <tr> + <td>Snippet '<em>snippet_id</em>' does not exist</td> + <td>Returned by the <a href="/glyph/book/macros/macros_core.html#m_snippet"><code>snippet</code></a> macro if an invalid snippet ID was supplied.</td> + </tr> + + + <tr> + <td>File '<em>file_name</em>' not found</td> + <td>Returned by the <a href="/glyph/book/macros/macros_core.html#m_include"><code>include</code></a> macro if an invalid file was supplied.</td> + </tr> + + + <tr> + <td>Filter macro '<em>macro_name</em>' not found</td> + <td>Returned by the <a href="/glyph/book/macros/macros_core.html#m_include"><code>include</code></a> macro if the <a href="/glyph/book/config/options.html#s_options_filters_by_file_extension"><code>options.filters_by_file_extension</code></a> setting is set to @true@ but the file extension of the included file is not recognized as a filter macro.</td> + </tr> + + + <tr> + <td>RedCloth gem not installed. Please run: gem install RedCloth</td> + <td>Returned by the <a href="/glyph/book/macros/macros_filters.html#m_textile"><code>textile</code></a> macro if the RedCloth gem is not installed.</td> + </tr> + + + <tr> + <td>No MarkDown converter installed. Please run: gem install bluecloth</td> + <td>Returned by the <a href="/glyph/book/macros/macros_filters.html#m_markdown"><code>markdown</code></a> macro if no valid Markdown converter gem is installed. Glyph checks for: BlueCloth, Maruku, Kramdown and RDiscount.</td> + </tr> + + + <tr> + <td>Image/Figure not found</td> + <td>Retured by the <a href="/glyph/book/macros/macros_block.html#m_image"><code>image</code></a> macro or the <a href="/glyph/book/macros/macros_block.html#m_figure"><code>figure</code></a> macro respectively, if the specified image file could not be found within the <code>images/</code> folder.</td> + </tr> + + + <tr> + <td>Bookmark '<em>bookmark_name</em>' already exists</td> + <td>Returned by the <a href="/glyph/book/macros/macros_inline.html#m_anchor"><code>anchor</code></a> macro or by the <a href="/glyph/book/macros/macros_structure.html#m_section"><code>section</code></a> macro if the anchor ID supplied as attribute has already been used in the document.</td> + </tr> + + + <tr> + <td>Bookmark '<em>bookmark_name</em>' already exists</td> + <td>Returned by the <a href="/glyph/book/macros/macros_inline.html#m_link"><code>link</code></a> macro if the anchor ID supplied as parameter has not been used in the document.</td> + </tr> + + + <tr> + <td>Stylesheet '<em>file_name</em>' not found</td> + <td>Returned by the <a href="/glyph/book/macros/macros_structure.html#m_style"><code>style</code></a> macro if the <code>.css</code> or <code>.sass</code> file supplied as parameter was not found in the <code>styles/</code> directory.</td> + </tr> + + + <tr> + <td>Haml is not installed. Please run: gem install haml</td> + <td>Returned by the <a href="/glyph/book/macros/macros_structure.html#m_style"><code>style</code></a> macro if a <code>.sass</code> file was passed as parameter but the Haml gem is not installed.</td> + </tr> + + + <tr> + <td>Invalid XML element: '<em>element_name</em>'</td> + <td>An invalid XML element name was supplied to the <code>|xml|</code> system macro (see <a href="/glyph/book/document.html#other_elements">Other HTML Elements</a>).</td> + </tr> + + + <tr> + <td>Invalid XML element: '<em>element_name</em>'</td> + <td>An invalid XML attribute name was supplied to the <code>|xml|</code> system macro (see <a href="/glyph/book/document.html#other_elements">Other HTML Elements</a>).</td> + </tr> + + + <tr> + <td>Macro '<em>macro_name</em>' cannot be used in safe mode</td> + <td>Returned if a forbidden macro was used in safe mode (see <a href="/glyph/book/compiling/programmatic_usage.html#modes">Modes</a>).</td> + </tr> + + + <tr> + <td>Cannot reset 'system.<em>setting_name</em>' setting (system use only).</td> + <td>Returned by the <a href="/glyph/book/macros/macros_core.html#m_config_"><code>config:</code></a> when attempting to override a setting in the <code>system.*</code> namespace.</td> + </tr> + + + <tr> + <td>Macro '<em>macro_a</em>' must be within a '<em>macro_b</em>' macro</td> + <td>Returned if a macro was used in the wrong place.</td> + </tr> + + + <tr> + <td>Macro '<em>macro_a</em>' must not be within a '<em>macro_b</em>' macro</td> + <td>Returned if a macro was used in the wrong place.</td> + </tr> + </table> + +<nav class="navigation"><a href="/glyph/book/troubleshooting/errors_command.html">← Command Errors</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/ref_commands.html">Command Reference →</a></nav>
A
contents/glyph/book/troubleshooting/errors_parser.html
@@ -0,0 +1,60 @@
+----- +title: "Glyph – Parsing Errors" +content-type: page +----- +<nav class="navigation"><a href="/glyph/book/troubleshooting/errors_generic.html">← Generic Errors</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/troubleshooting/errors_command.html">Command Errors →</a></nav> + + <table style="width:100%;"> + <tr> + <th style="width:30%">Error Message</th> + <th>Description</th> + </tr> + <tr> + <td>Macro delimiter '<em>delimiter</em>' not escaped</td> + <td>Returned in case of unescaped <code>[</code>or <code>]</code>.</td> + </tr> + + + <tr> + <td><em>macro_name</em>[...] - A macro cannot start with '@' or a digit.</td> + <td>Returned if an invalid macro name was specified.</td> + </tr> + + + <tr> + <td>Macro '<em>macro_name</em>' not closed</td> + <td>Returned if a macro lacks its end delimiter <code>=]</code>.</td> + </tr> + + + <tr> + <td>Escaping macro '<em>macro_name</em>' not closed</td> + <td>Returned if an escaping macro lacks its end delimiter <code>=]</code>.</td> + </tr> + + + <tr> + <td>Attribute @<em>attribute_name</em> not closed</td> + <td>Returned if a macro attribute lacks its end delimiter <code>]</code>.</td> + </tr> + + + <tr> + <td>Attributes cannot be nested</td> + <td>Returned if a macro attribute was found immediately within another attribute.</td> + </tr> + + + <tr> + <td>Cannot nest escaping macro '<em>macro_name_1</em>' within escaping macro '<em>macro_name_2</em>'</td> + <td>Returned if an escaping macro contains another escaping macro.</td> + </tr> + + + <tr> + <td>Parameter delimiter '|' not allowed here</td> + <td>Returned if a parameter delimiter is outside a macro or inside an attribute.</td> + </tr> + </table> + +<nav class="navigation"><a href="/glyph/book/troubleshooting/errors_generic.html">← Generic Errors</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/troubleshooting/errors_command.html">Command Errors →</a></nav>
M
contents/h3rald.html
→
contents/h3rald.html
@@ -3,90 +3,223 @@ title: "H3RALD Web Site"
content-type: project subtitle: "The site you're looking at" github: h3rald -status: Active -version: 8.4.0 +active: true +home: /h3rald/ +summary: "This very web site, in its 9th incarnation. H3RALD.com has been operative since 2004 and through the years its backend changed from being pure vanilla HTML, to server-side PHP (Prado and CakePHP) to Ruby (Rails, Nanoc), and finally Nim (HastySite)." +version: 9.0.0 ----- -<nav class="project-links"> -<p><a href="http://github.com/h3rald/h3rald/tree/master"><span class="caps">SOURCE</span></a> | <a href="http://github.com/h3rald/h3rald/issues"><span class="caps">TRACKING</span></a></p> -</nav> -<ul class="project-data"> - <li>Project Status: <strong>Active</strong></li> - <li>Version: <strong>8.4.0</strong></li> -</ul> -<p>The H3RALD.com domain was bought in March 2004 and since than has always been my home on the Internet. Through the years, a total of 8 versions of this web site has been released, each featuring some change in the backend.</p> -<p>Currently, this web site is fully static (minus a few Ajax calls) and is powered by the <a href="http://nanoc.stoneship.org/">Nanoc</a>, a very flexible web publishing system written in Ruby.</p> -<div class="spacer-50"></div> -<div class="spacer-50"></div> -<h3>Releases</h3> -<h4>Version 8 (September 2009 – now)</h4> -<ul> - <li>Web Server: <a href="http://www.apache.org">Apache</a>, <a href="http://wiki.nginx.org/Main">Nginx</a> (from version 8.3 onwards)</li> - <li>Database: n/a</li> - <li>Framework/<span class="caps">CMS</span>/Other: <a href="http://www.h3rald.com">Nanoc</a></li> - <li>Programming Language: <a href="http://www.ruby-lang.org">Ruby</a></li> -</ul> -<h4>Version 7 (July 2007 – September 2009)</h4> -<ul> - <li>Web Server: <a href="http://www.apache.org">Apache</a></li> - <li>Database: <a href="http://www.mysql.com">MySQL</a></li> - <li>Framework/<span class="caps">CMS</span>/Other: <a href="http://www.rubyonrails.org">Ruby on Rails</a> + <a href="http://www.typosphere.org">Typo</a></li> - <li>Programming Language: <a href="http://www.ruby-lang.org">Ruby</a></li> -</ul> -<h4>Version 6 (December 2005 – July 2007)</h4> -<ul> - <li>Web Server: <a href="http://www.apache.org">Apache</a></li> - <li>Database: <a href="http://www.mysql.com">MySQL</a></li> - <li>Framework/<span class="caps">CMS</span>/Other: <a href="http://www.cakephp.com">CakePHP</a></li> - <li>Programming Language: <a href="http://www.php.net"><span class="caps">PHP</span></a></li> -</ul> -<h4>Version 5 (April 2005 – December 2005)</h4> -<ul> - <li>Web Server: <a href="http://www.apache.org">Apache</a></li> - <li>Database: <a href="http://www.sqlite.org">SQLite</a></li> - <li>Framework/<span class="caps">CMS</span>/Other: <a href="http://www.xisc.com/">Prado</a></li> - <li>Programming Language: <a href="http://www.php.net"><span class="caps">PHP</span></a></li> -</ul> -<h4>Version 4 (February 2005 – April 2005)</h4> -<ul> - <li>Web Server: <a href="http://www.apache.org">Apache</a></li> - <li>Database: <a href="http://www.mysql.com">MySQL</a></li> - <li>Framework/<span class="caps">CMS</span>/Other: n/a</li> - <li>Programming Language: <a href="http://www.php.net"><span class="caps">PHP</span></a></li> -</ul> -<h4>Version 3 (November 2005 – February 2005)</h4> -<ul> - <li>Web Server: <a href="http://www.apache.org">Apache</a></li> - <li>Database: <a href="http://www.mysql.com">MySQL</a></li> - <li>Framework/<span class="caps">CMS</span>/Other: <a href="http://www.xoops.org/"><span class="caps">XOOPS</span></a></li> - <li>Programming Language: <a href="http://www.php.net"><span class="caps">PHP</span></a></li> -</ul> -<h4>Version 2 (May 2004 – November 2004)</h4> -<ul> - <li>Web Server: <a href="http://www.apache.org">Apache</a></li> - <li>Database: n/a</li> - <li>Framework/<span class="caps">CMS</span>/Other: n/a</li> - <li>Programming Language: <a href="http://www.php.net"><span class="caps">PHP</span></a></li> -</ul> -<h4>Version 1 (March 2004 – May 2004)</h4> -<ul> - <li>Web Server: <a href="http://www.apache.org">Apache</a></li> - <li>Database: n/a</li> - <li>Framework/<span class="caps">CMS</span>/Other: n/a</li> - <li>Programming Language: n/a</li> -</ul> +<p>The H3RALD.com domain was bought in March 2004 and since than has always been my home on the Internet. Through the years, a total of 9 major versions of this web site has been released, each featuring some change in the backend.</p> +<p>Currently, this site is fully static (minus a few AJAX calls) and is powered by my very own static site generator, HastySite (soon to be released) and by <a href="/litestore/">LiteStore</a> (for the archive search functionality).</p> +<h3>Major Releases</h3> + + +<div class="timeline"> + <div class="timeline-item"> + <div class="timeline-left"> + <div class="timeline-icon icon-lg"> + <i class="ent ent-flag"></i> + </div> + </div> + <div class="timeline-content"> + <div class="tile"> + <div class="tile-content"> + <p class="tile-subtitle"> + Version 9 (October 2017 – present) + </p> + <ul> + <li>Web Server: <a href="http://wiki.nginx.org/Main">Nginx</a></li> + <li>Database: <a href="/litestore/">LiteStore</a> (for the archive search functionality only)</li> + <li>Framework/<span class="caps">CMS</span>/Other: HastySite (static site generator)</li> + <li>Programming Language: <a href="https://nim-lang.org">Nim</a></li> + </ul> + </div> + </div> + </div> + </div> + <div class="timeline-item"> + <div class="timeline-left"> + <div class="timeline-icon icon-lg"> + <i class="ent ent-flag"></i> + </div> + </div> + <div class="timeline-content"> + <div class="tile"> + <div class="tile-content"> + <p class="tile-subtitle"> + Version 8 (September 2009 – October 2017) + </p> + <ul> + <li>Web Server: <a href="http://www.apache.org">Apache</a>, <a href="http://wiki.nginx.org/Main">Nginx</a> (from version 8.3 onwards)</li> + <li>Database: n/a</li> + <li>Framework/<span class="caps">CMS</span>/Other: <a href="http://www.h3rald.com">Nanoc</a> (static site generator)</li> + <li>Programming Language: <a href="http://www.ruby-lang.org">Ruby</a></li> + </ul> + </div> + </div> + </div> + </div> + <div class="timeline-item"> + <div class="timeline-left"> + <div class="timeline-icon icon-lg"> + <i class="ent ent-flag"></i> + </div> + </div> + <div class="timeline-content"> + <div class="tile"> + <div class="tile-content"> + <p class="tile-subtitle"> + Version 7 (July 2007 – September 2009) + </p> + <ul> + <li>Web Server: <a href="http://www.apache.org">Apache</a></li> + <li>Database: <a href="http://www.mysql.com">MySQL</a></li> + <li>Framework/<span class="caps">CMS</span>/Other: <a href="http://www.rubyonrails.org">Ruby on Rails</a> + <a href="http://www.typosphere.org">Typo</a></li> + <li>Programming Language: <a href="http://www.ruby-lang.org">Ruby</a></li> + </ul> + </div> + </div> + </div> + </div> + <div class="timeline-item"> + <div class="timeline-left"> + <div class="timeline-icon icon-lg"> + <i class="ent ent-flag"></i> + </div> + </div> + <div class="timeline-content"> + <div class="tile"> + <div class="tile-content"> + <p class="tile-subtitle"> + Version 6 (December 2005 – July 2007) + </p> + <ul> + <li>Web Server: <a href="http://www.apache.org">Apache</a></li> + <li>Database: <a href="http://www.mysql.com">MySQL</a></li> + <li>Framework/<span class="caps">CMS</span>/Other: <a href="http://www.cakephp.com">CakePHP</a></li> + <li>Programming Language: <a href="http://www.php.net"><span class="caps">PHP</span></a></li> + </ul> + </div> + </div> + </div> + </div> + <div class="timeline-item"> + <div class="timeline-left"> + <div class="timeline-icon icon-lg"> + <i class="ent ent-flag"></i> + </div> + </div> + <div class="timeline-content"> + <div class="tile"> + <div class="tile-content"> + <p class="tile-subtitle"> + Version 5 (April 2005 – December 2005) + </p> + <ul> + <li>Web Server: <a href="http://www.apache.org">Apache</a></li> + <li>Database: <a href="http://www.sqlite.org">SQLite</a></li> + <li>Framework/<span class="caps">CMS</span>/Other: <a href="http://www.xisc.com/">Prado</a></li> + <li>Programming Language: <a href="http://www.php.net"><span class="caps">PHP</span></a></li> + </ul> + </div> + </div> + </div> + </div> + <div class="timeline-item"> + <div class="timeline-left"> + <div class="timeline-icon icon-lg"> + <i class="ent ent-flag"></i> + </div> + </div> + <div class="timeline-content"> + <div class="tile"> + <div class="tile-content"> + <p class="tile-subtitle"> + Version 4 (February 2005 – April 2005) + </p> + <ul> + <li>Web Server: <a href="http://www.apache.org">Apache</a></li> + <li>Database: <a href="http://www.mysql.com">MySQL</a></li> + <li>Framework/<span class="caps">CMS</span>/Other: n/a</li> + <li>Programming Language: <a href="http://www.php.net"><span class="caps">PHP</span></a></li> + </ul> + </div> + </div> + </div> + </div> + <div class="timeline-item"> + <div class="timeline-left"> + <div class="timeline-icon icon-lg"> + <i class="ent ent-flag"></i> + </div> + </div> + <div class="timeline-content"> + <div class="tile"> + <div class="tile-content"> + <p class="tile-subtitle"> + Version 3 (November 2005 – February 2005) + </p> + <ul> + <li>Web Server: <a href="http://www.apache.org">Apache</a></li> + <li>Database: <a href="http://www.mysql.com">MySQL</a></li> + <li>Framework/<span class="caps">CMS</span>/Other: <a href="http://www.xoops.org/"><span class="caps">XOOPS</span></a></li> + <li>Programming Language: <a href="http://www.php.net"><span class="caps">PHP</span></a></li> + </ul> + </div> + </div> + </div> + </div> + <div class="timeline-item"> + <div class="timeline-left"> + <div class="timeline-icon icon-lg"> + <i class="ent ent-flag"></i> + </div> + </div> + <div class="timeline-content"> + <div class="tile"> + <div class="tile-content"> + <p class="tile-subtitle"> + Version 2 (May 2004 – November 2004) + </p> + <ul> + <li>Web Server: <a href="http://www.apache.org">Apache</a></li> + <li>Database: n/a</li> + <li>Framework/<span class="caps">CMS</span>/Other: n/a</li> + <li>Programming Language: <a href="http://www.php.net"><span class="caps">PHP</span></a></li> + </ul> + </div> + </div> + </div> + </div> + <div class="timeline-item"> + <div class="timeline-left"> + <div class="timeline-icon icon-lg"> + <i class="ent ent-flag"></i> + </div> + </div> + <div class="timeline-content"> + <div class="tile"> + <div class="tile-content"> + <p class="tile-subtitle"> + Version 1 (March 2004 – May 2004) + </p> + <ul> + <li>Web Server: <a href="http://www.apache.org">Apache</a></li> + <li>Database: n/a</li> + <li>Framework/<span class="caps">CMS</span>/Other: n/a</li> + <li>Programming Language: n/a</li> + </ul> + </div> + </div> + </div> + </div> +</div> + <h3>Latest Updates</h3> -<ul><li><a href="/articles/h3rald-83/">H3RALD.com v8.3 Released</a> — <time class="timeago" datetime="2012-12-27T22:41:34Z">Thursday, 27 December 2012</time></li> -<li><a href="/articles/h3rald-81/">H3RALD.com v8.1 Released</a> — <time class="timeago" datetime="2010-09-23T12:04:25Z">Thursday, 23 September 2010</time></li> -<li><a href="/articles/take-back-your-site-with-nanoc/">Take back your site, with nanoc!</a> — <time class="timeago" datetime="2009-09-15T11:32:51Z">Tuesday, 15 September 2009</time></li> -<li><a href="/articles/h3rald-71/">Introducing H3RALD.com v7.1</a> — <time class="timeago" datetime="2008-10-27T04:29:00Z">Monday, 27 October 2008</time></li> -<li><a href="/articles/apache2-upgrade/">Beware of sudden upgrades!</a> — <time class="timeago" datetime="2007-12-20T06:41:00Z">Thursday, 20 December 2007</time></li> -<li><a href="/articles/review-services/">Review Services</a> — <time class="timeago" datetime="2007-12-14T11:24:00Z">Friday, 14 December 2007</time></li> -<li><a href="/articles/back-from-holiday/">Back from holiday</a> — <time class="timeago" datetime="2007-08-30T02:59:00Z">Thursday, 30 August 2007</time></li> -<li><a href="/articles/simply-on-rails-1-concepts-map/">Simply on Rails – Part 1: Concepts and Bubbles</a> — <time class="timeago" datetime="2007-07-07T05:43:00Z">Saturday, 07 July 2007</time></li> -<li><a href="/articles/h3rald-v7-overview/">Back on Track…</a> — <time class="timeago" datetime="2007-06-22T12:38:00Z">Friday, 22 June 2007</time></li> -<li><a href="/articles/41/">Comments temporarily disabled</a> — <time class="timeago" datetime="2007-01-07T05:53:00Z">Sunday, 07 January 2007</time></li> -<li><a href="/articles/37/">Some updates</a> — <time class="timeago" datetime="2006-07-25T01:07:00Z">Tuesday, 25 July 2006</time></li> -<li><a href="/articles/29/">Writing more articles…</a> — <time class="timeago" datetime="2006-05-14T04:26:00Z">Sunday, 14 May 2006</time></li> -<li><a href="/articles/21/">Birthday present? Web space, please…</a> — <time class="timeago" datetime="2006-04-27T12:47:00Z">Thursday, 27 April 2006</time></li> -<li><a href="/articles/8/">New site operative</a> — <time class="timeago" datetime="2006-04-06T14:57:00Z">Thursday, 06 April 2006</time></li> +<ul><li><a href="/articles/h3rald-83/">H3RALD.com v8.3 Released</a></li> + <li><a href="/articles/h3rald-81/">H3RALD.com v8.1 Released</a></li> + <li><a href="/articles/take-back-your-site-with-nanoc/">Take back your site, with nanoc!</a></li> + <li><a href="/articles/h3rald-71/">Introducing H3RALD.com v7.1</a></li> + <li><a href="/articles/h3rald-v7-overview/">Back on Track…</a></li> + <li><a href="/articles/37/">Some updates</a></li> + <li><a href="/articles/8/">New site operative</a></li> </ul>
D
contents/hastyscribe.html
@@ -1,110 +0,0 @@
------ -title: "" -content-type: project -github: hastyscribe -status: Active -version: 1.6.0 ------ - -<div class="jumbotron"> - <p style="text-align:center;"><i class="hastyscribe" style="font-size: 180%; color: #000"></i></p> - <p class="donthyphenate">A simple, self-contained, command-line program able to convert <a href="http://daringfireball.net/projects/markdown">markdown</a> files into self-contained HTML pages, automatically embedding all the needed fonts, stylesheets and images.</p> -</div> - -<div class="row donthyphenate" style="text-align: center; margin: auto;"> - <div class="col-md-4" style="padding: 2em;"> - <div class="row"> - <i class="h3-os-apple fa-3x"></i> - <i class="h3-os-linux fa-3x"></i> - <i class="h3-os-win-04 fa-3x"></i> - </div> - <div class="row"> - <h3 class="centered">Cross Platform</h3> - <p>Download the precompiled HastyScribe binaries for OS X, Linux, and Windows, or build directly from the source.</p> - </div> - </div> - <div class="col-md-4" style="padding: 2em;"> - <div class="row"> - <i class="h3-terminal fa-3x"></i> - </div> - <div class="row"> - <h3 class="centered">Command Line</h3> - <p>HastyScribe is a command-line application that doesn't need anything else but a single, small, executable file.</p> - </div> - </div> - <div class="col-md-4" style="padding: 2em;"> - <div class="row"> - <i class="fa fa-mobile fa-3x"></i> - <i class="fa fa-tablet fa-3x"></i> - <i class="fa fa-desktop fa-3x"></i> - </div> - <div class="row"> - <h3 class="centered">Responsive</h3> - <p>HastyScribe generates valid, self-contained, responsive HTML5 documents that can be viewed with any major modern broswer, and look great on any device.</p> - </div> - </div> -</div> - -<div class="row"> - <div class="col-md-6"> - <div class="panel panel-default"> - <div class="panel-heading">Usage & Syntax</div> - <div class="panel-body"> - <p>Run HastyScribe from the command line like this:</p> - <p><code><strong>hastyscribe</strong> <em>MyMarkdownFile.md</em></code></p> - </div> - </div> - </div> - <div class="col-md-6"> - <div class="panel panel-default"> - <div class="panel-heading">Example & Documentation</div> - <div class="panel-body"> - <p>View/download the <strong><a href="/hastyscribe/HastyScribe_UserGuide.htm">HastyScribe User Guide</a></strong></p> - <p>generated with HastyScribe (<a href="https://raw.githubusercontent.com/h3rald/hastyscribe/master/doc/HastyScribe_UserGuide.md">source</a>)</p> - </div> - </div> - </div> -</div> - -<div class="row" style="margin:auto; text-align:center;"> -<div class="btn-group"> - <button type="button" class="btn btn-primary dropdown-toggle" data-toggle="dropdown"> - <span class="fa-download"></span> Download <span class="caret"></span> - </button> - <ul class="dropdown-menu" role="menu" style="text-align: left;"> - <li> - <a href="https://github.com/h3rald/hastyscribe/releases/download/v1.6.0/hastyscribe_v1.6.0_macosx_x64.zip"> - <i class="h3-os-apple"></i> HastyScribe for OS X (x64) - </a> - </li> - <li> - <a href="https://github.com/h3rald/hastyscribe/releases/download/v1.6.0/hastyscribe_v1.6.0_linux_x64.zip"> - <i class="h3-os-linux"></i> HastyScribe for Linux (x64) - </a> - </li> - <li> - <a href="https://github.com/h3rald/hastyscribe/releases/download/v1.6.0/hastyscribe_v1.6.0_linux_x86.zip"> - <i class="h3-os-linux"></i> HastyScribe for Linux (x86) - </a> - </li> - <li> - <a href="https://github.com/h3rald/hastyscribe/releases/download/v1.6.0/hastyscribe_v1.6.0_linux_arm.zip"> - <i class="h3-os-linux"></i> HastyScribe for Linux (ARM) - </a> - </li> - <li> - <a href="https://github.com/h3rald/hastyscribe/releases/download/v1.6.0/hastyscribe_v1.6.0_windows_x64.zip"> - <i class="h3-os-win-04"></i> HastyScribe for Windows (x64) - </a> - </li> - </ul> -</div> - <a href="https://github.com/h3rald/hastyscribe" - class="btn btn-success" style="margin:20px;"> - <i class="fa fa-github"></i> View on Github</a> -</div> - -<div class="row" style="margin:auto; text-align: center;"> - — <i class="hastyscribe"></i> is open source software, licensed under the terms of the <a href="http://opensource.org/licenses/MIT">MIT License.</a> — -</div> -
A
contents/hastyscribe.md
@@ -0,0 +1,36 @@
+----- +title: "HastyScribe" +content-type: project +github: hastyscribe +subtitle: "A self-contained markdown compiler" +active: true +home: /hastyscribe/ +docs: /hastyscribe/HastyScribe_UserGuide.htm +summary: "A self-contained Markdown compiler that can generate self-contained HTML files, useful for writing essays, reports, meeting notes, etc." +version: "1.6.0" +download: "https://github.com/h3rald/hastyscribe/releases/download/" +----- +{{download => https://github.com/h3rald/hastyscribe/releases/download/}} + +[](class:hastyscribe) is a simple, self-contained, command-line program able to convert [markdown](http://daringfireball.net/projects/markdown) files into self-contained HTML pages, automatically embedding all the needed fonts, stylesheets and images. + +HastyScribe is: + +* **cross-platform**, you can download precompiled binaries for macOS, Linux and Windows. +* **self-contained**, it's a command-line application that doesn't require installing or prerequisites: it's all in a single, small, executable file. +* a **powerful markdown compiler**, which leverages the feature-rich [Discount](https://www.pell.portland.or.us/~orc/Code/discount/) markdown engine, and adds even more features like snippets, custom fields, and substitution macros. +* able to generate **self-contained, responsive HTML5 documents** that can be viewed with any major modern broswer, and look great on any device. + +For more information and a sample of HastyScribe's power, you can download and read the [HastyScribe User Guide](/hastyscribe/HastyScribe_UserGuide.htm) – generated with HastyScribe of course. + +### Downloads + +* [macOS (x64)]({{$download}}v{{$version}}/{{$github}}_v{{$version}}_macosx_x64.zip) +* [Linux (x64)]({{$download}}v{{$version}}/{{$github}}_v{{$version}}_linux_x64.zip) +* [Linux (x86)]({{$download}}v{{$version}}/{{$github}}_v{{$version}}_linux_x86.zip) +* [Linux (ARM)]({{$download}}v{{$version}}/{{$github}}_v{{$version}}_linux_arm.zip) +* [Windows (x64)]({{$download}}v{{$version}}/{{$github}}_v{{$version}}_windows_x64.zip) + +### Resources + +* [Introducing HastyScribe](/articles/hastyscribe/)
M
contents/herald-vim-color-scheme.html
→
contents/herald-vim-color-scheme.html
@@ -1,7 +1,11 @@
----- -title: "herald.vim" +title: "Herald Vim Color Scheme" content-type: project subtitle: "An easy to read, portable and pretty Vim Color Scheme" +home: /herald-vim-color-scheme/ +summary: "A dark, easy-to-read color scheme for the Vim text editor. It can be used with 255, 16 or 8 colors." +active: true +version: 0.2.1 ----- <p><strong>herald</strong> is a dark color scheme for <a href="http://www.vim.org">Vim</a> which aims to be easy to read, eye-appealing, portable on multiple terminals, and suitable for source code highlighting in multiple languages.</p> <p>You can get the latest version <strong><a href="/files/herald.vim"><span class="caps">HERE</span></a></strong> (direct link).</p>
D
contents/litestore.html
@@ -1,116 +0,0 @@
------ -title: "" -content-type: project -github: litestore -status: Active -version: 1.1.1 ------ - -<div class="jumbotron"> - <h2 class="centered"> - LiteStore<br> - <img src="/images/litestore/litestore.png" style="margin-left:-35px" /> - </h2> - <p class="donthyphenate">A lightweight, self-contained, RESTful, multi-format NoSQL document store server written in <a href="http://nim-lang.org">Nim</a> and powered by a <a href="http://www.sqlite.org">SQLite</a> backend for storage. It aims to be a very simple and lightweight backend ideal for prototyping and testing REST APIs and client-side, single-page applications. </p> -</div> - -<div class="row donthyphenate" style="text-align: center; margin: auto;"> - <div class="col-md-4" style="padding: 2em;"> - <div class="row"> - <i class="h3-os-apple fa-3x"></i> - <i class="h3-os-linux fa-3x"></i> - <i class="h3-os-win-04 fa-3x"></i> - </div> - <div class="row"> - <h3 class="centered">Cross Platform</h3> - <p>Download the precompiled LiteStore binaries for OS X, Linux, and Windows, or build directly from the source.</p> - </div> - </div> - <div class="col-md-4" style="padding: 2em;"> - <div class="row"> - <i class="fa fa-archive fa-3x"></i> - </div> - <div class="row"> - <h3 class="centered">Self-Contained</h3> - <p>LiteStore is a command-line application that doesn't need anything else but a single, small, executable file.</p> - </div> - </div> - <div class="col-md-4" style="padding: 2em;"> - <div class="row"> - <i class="fa fa-cogs fa-3x"></i> - </div> - <div class="row"> - <h3 class="centered">RESTFul</h3> - <p>LiteStore exposes a simple RESTful HTTP APIs, perfect for prototyping SPAs.</p> - </div> - </div> -</div> - -<div class="row"> - <div class="col-md-6"> - <div class="panel panel-default"> - <div class="panel-heading">Usage & Syntax</div> - <div class="panel-body"> - <p>Run LiteStore from the command line like this:</p> - <p><code><strong>litestore</strong> -s:<em>MyDataStore.db</em></code></p> - </div> - </div> - </div> - <div class="col-md-6"> - <div class="panel panel-default"> - <div class="panel-heading">Documentation</div> - <div class="panel-body"> - <p>View/download the <strong><a href="/litestore/LiteStore_UserGuide.htm">LiteStore User Guide</a></strong></p> - <p>(generated with <a href="/hastyscribe/">HastyScribe</a>)</p> - </div> - </div> - </div> -</div> - -<div class="row" style="margin:auto; text-align:center;"> -<div class="btn-group"> - <button type="button" class="btn btn-primary dropdown-toggle" data-toggle="dropdown"> - <span class="fa fa-download"></span> Download <span class="caret"></span> - </button> - <ul class="dropdown-menu" role="menu" style="text-align: left;"> - <li> - <a href="https://github.com/h3rald/litestore/releases/download/v1.1.1/litestore_v1.1.1_macosx_x64.zip"> - <i class="h3-os-apple"></i> LiteStore for OS X (x64) - </a> - </li> - <li> - <a href="https://github.com/h3rald/litestore/releases/download/v1.1.1/litestore_v1.1.1_linux_x64.zip"> - <i class="h3-os-linux"></i> LiteStore for Linux (x64) - </a> - </li> - <li> - <a href="https://github.com/h3rald/litestore/releases/download/v1.1.1/litestore_v1.1.1_linux_x86.zip"> - <i class="h3-os-linux"></i> LiteStore for Linux (x86) - </a> - </li> - <li> - <a href="https://github.com/h3rald/litestore/releases/download/v1.1.1/litestore_v1.1.1_linux_arm.zip"> - <i class="h3-os-linux"></i> LiteStore for Linux (ARM) - </a> - </li> - <li> - <a href="https://github.com/h3rald/litestore/releases/download/v1.1.1/litestore_v1.1.1_windows_x64.zip"> - <i class="h3-os-win-04"></i> LiteStore for Windows (x64) - </a> - </li> - <li> - <a href="https://github.com/h3rald/litestore/releases/download/v1.1.1/litestore_v1.1.1_windows_x86.zip"> - <i class="h3-os-win-04"></i> LiteStore for Windows (x86) - </a> - </li> - </ul> -</div> - <a href="https://github.com/h3rald/litestore" - class="btn btn-success" style="margin:20px;"> - <i class="fa fa-github"></i> View on Github</a> -</div> - -<div class="row" style="margin:auto; text-align: center;"> - — <em>LiteStore</em> is open source software, licensed under the terms of the <a href="http://opensource.org/licenses/MIT">MIT License.</a> — -</div> -
A
contents/litestore.md
@@ -0,0 +1,34 @@
+----- +title: "LiteStore" +content-type: project +github: litestore +home: /litestore/ +active: true +docs: /litestore/LiteStore_UserGuide.htm +version: 1.1.1 +subtitle: "A tiny NoSQL database for rapid prototyping" +summary: "A lightweight, self-contained, RESTful, multi-format NoSQL document store server written in Nim and powered by a SQLite backend for storage." +download: "https://github.com/h3rald/litestore/releases/download/" +----- + +LiteStore is a lightweight, self-contained, RESTful, multi-format NoSQL document store server written in [Nim](http://nim-lang.org) and powered by a [SQLite](http://www.sqlite.org)" backend for storage. It aims to be a very simple and lightweight backend ideal for prototyping and testing REST APIs and client-side, single-page applications. + +LiteStore is: + + +* **cross-platform**, you can download precompiled binaries for macOS, Linux and Windows. +* **self-contained**, it's a command-line application that doesn't require installing or prerequisites: it's all in a single, small, executable file. +* **RESTful**, you can access it via HTTP — perfect for prototyping SPAs. + +### Downloads + +* [macOS (x64)]({{$download}}v{{$version}}/{{$github}}_v{{$version}}_macosx_x64.zip) +* [Linux (x64)]({{$download}}v{{$version}}/{{$github}}_v{{$version}}_linux_x64.zip) +* [Linux (x86)]({{$download}}v{{$version}}/{{$github}}_v{{$version}}_linux_x86.zip) +* [Linux (ARM)]({{$download}}v{{$version}}/{{$github}}_v{{$version}}_linux_arm.zip) +* [Windows (x64)]({{$download}}v{{$version}}/{{$github}}_v{{$version}}_windows_x64.zip) +* [Windows (x86)]({{$download}}v{{$version}}/{{$github}}_v{{$version}}_windows_x86.zip) + +### Resources + +* [Introducing LiteStore](/articles/litestore/)
D
contents/projects.html
@@ -1,22 +0,0 @@
------ -title: "Projects" -content-type: page ------ -<div class="projects-page"> -<h3><a href="/h3rald/">H3RALD Web Site</a></h3> -<p>This very web site, in its 8th incarnation. H3RALD.com has been operative since 2004 and through the years its backend changed from being pure vanilla <span class="caps">HTML</span>, to server-side <span class="caps">PHP</span> (Prado and CakePHP) to Ruby (Rails, Nanoc).</p> -<h3><a href="/hastyscribe/">HastyScribe</a></h3> -<p>A self-contained Markdown compiler that can generate self-contained <span class="caps">HTML</span> files, useful for writing essays, reports, meeting notes, etc.</p> -<h3><a href="/litestore/">LiteStore</a></h3> -<p>A lightweight, self-contained, RESTful, multi-format NoSQL document store server written in Nim and powered by a SQLite backend for storage.</p> -<h3><a href="/glyph/">Glyph</a></h3> -<p>A <em>Rapid Document Authoring Framework</em> written in Ruby that can be used to create and manage books and articles.</p> -<h3><a href="/ruby-compendium/">Ruby Compendium</a></h3> -<p>A free book aiming to help beginners learn about Ruby. It doesn’t focus on learning the language, but rather on its vast ecosystem and freely available resources.</p> -<h3><a href="/rawline/">RawLine</a></h3> -<p>Rawline is a Ruby library which provides a subset of the functionality of the C Readline library. Being implemented in pure Ruby, it gives Ruby developers much more control over key bindings and word completion.</p> -<h3><a href="/concatenative/">Concatenative</a></h3> -<p>A Ruby <span class="caps">DSL</span> for concatenative programming. Although quite slow if compared to other concatenative languages like Factor, it implements all the most common concatenative combinator and makes it possible to use Ruby objects in a concatenative way.</p> -<h3><a href="/herald-vim-color-scheme/">Herald Vim Color Scheme</a></h3> -<p>A dark, easy-to-read color scheme for the Vim text editor. It can be used with 255, 16 or 8 colors.</p> -</div>
M
contents/rawline.html
→
contents/rawline.html
@@ -3,16 +3,12 @@ title: "RawLine"
content-type: project subtitle: "A pure-ruby alternative to ReadLine" github: rawline -status: On Hold +inactive: true +home: /rawline/ +summary: "A Ruby library which provides a subset of the functionality of the C Readline library. Being implemented in pure Ruby, it gives Ruby developers much more control over key bindings and word completion." version: 0.3.2 +docs: "http://rawline.rubyforge.org" ----- -<nav class="project-links"> -<p><a href="http://rawline.rubyforge.org"><span class="caps">DOCUMENTATION</span></a> | <a href="http://rubyforge.org/projects/rawline"><span class="caps">DOWNLOAD</span></a> | <a href="http://github.com/h3rald/rawline/tree/master"><span class="caps">SOURCE</span></a> | <a href="http://h3rald.lighthouseapp.com/projects/26374-rawline/overview"><span class="caps">TRACKING</span></a></p> -</nav> -<ul class="project-data"> - <li>Project Status: <strong>On Hold</strong></li> - <li>Version: <strong>0.3.2</strong></li> -</ul> <p>RawLine is a 100% Ruby alternative to the ReadLine library, providing some of its most popular features such as:</p> <ul> <li>Basic line editing operations</li>@@ -22,32 +18,32 @@ <li>Custom key/key sequences bindings</li>
</ul> <h3>Installation</h3> <p>The simplest method to install RawLine is to install the gem:</p> -<div class='text'><pre><code>gem install rawline</code></pre></div><h3>Usage</h3> +<div><pre><code class="bash">gem install rawline</code></pre></div><h3>Usage</h3> <p>Editor initialization:</p> -<div class='ruby'><pre><code>require 'rawline' +<div><pre><code class="ruby">require 'rawline' editor = RawLine::Editor.new</code></pre></div><p>Key binding:</p> -<div class='ruby'><pre><code>editor.bind(:ctrl_z) { editor.undo } +<div><pre><code>editor.bind(:ctrl_z) { editor.undo } editor.bind(:up_arrow) { editor.history_back } editor.bind(:ctrl_x) { puts "Exiting..."; exit }</code></pre></div><p>Setup word completion</p> -<div class='ruby'><pre><code>editor.completion_proc = lambda do |word| +<div><pre><code>editor.completion_proc = lambda do |word| if word ['select', 'update', 'delete', 'debug', 'destroy'].find_all { |e| e.match(/^#{Regexp.escape(word)}/) } end end editor.completion_append_string = " "</code></pre></div><p>Read input:</p> -<div class='ruby'><pre><code>editor.read("=> ", true)</code></pre></div><h3>Replacing Readline</h3> +<div><pre><code>editor.read("=> ", true)</code></pre></div><h3>Replacing Readline</h3> <p>Simply include the RawLine (or Rawline) module:</p> -<div class='ruby'><pre><code>include Rawline</code></pre></div><p>…and you’ll get:</p> -<div class='ruby'><pre><code>readline(prompt, add_history) # RawLine::Editor#read(prompt, add_history) +<div><pre><code>include Rawline</code></pre></div><p>…and you’ll get:</p> +<div><pre><code class="ruby">readline(prompt, add_history) # RawLine::Editor#read(prompt, add_history) HISTORY # RawLine::Editor#history FILENAME_COMPLETION_PROC # Rawline::Editor#filename_completion_proc # ...</code></pre></div><p>but also:</p> -<div class='ruby'><pre><code>Rawline.editor # RawLine::Editor</code></pre></div><p>…which opens a world of endless possibilities! ;-)</p> +<div><pre><code class="ruby">Rawline.editor # RawLine::Editor</code></pre></div><p>…which opens a world of endless possibilities! ;-)</p> <h3>Latest Updates</h3> -<ul><li><a href="/articles/real-world-rawline-usage/">Real-world Rawline usage</a> — <time class="timeago" datetime="2009-03-07T03:54:00Z">Saturday, 07 March 2009</time></li> -<li><a href="/articles/rawline-030/">RawLine 0.3.0 released â now with Readline emulation</a> — <time class="timeago" datetime="2009-03-01T06:47:00Z">Sunday, 01 March 2009</time></li> -<li><a href="/articles/rawline-020/">New Release: RawLine 0.2.0</a> — <time class="timeago" datetime="2008-04-02T03:33:00Z">Wednesday, 02 April 2008</time></li> -<li><a href="/articles/inline-name-change/">InLine name change: what’s your opinion?</a> — <time class="timeago" datetime="2008-03-27T05:30:00Z">Thursday, 27 March 2008</time></li> -<li><a href="/articles/inline-introduction/">RawLine – a 100% Ruby solution for console inline editing</a> — <time class="timeago" datetime="2008-03-10T05:59:00Z">Monday, 10 March 2008</time></li> +<ul><li><a href="/articles/real-world-rawline-usage/">Real-world Rawline usage</a></li> + <li><a href="/articles/rawline-030/">RawLine 0.3.0 released â now with Readline emulation</a></li> + <li><a href="/articles/rawline-020/">New Release: RawLine 0.2.0</a></li> + <li><a href="/articles/inline-name-change/">InLine name change: what’s your opinion?</a></li> + <li><a href="/articles/inline-introduction/">RawLine – a 100% Ruby solution for console inline editing</a></li> </ul>
M
contents/ruby-compendium.html
→
contents/ruby-compendium.html
@@ -3,19 +3,13 @@ title: "Ruby Compendium"
content-type: project subtitle: "An Essential Guide to the Ruby Ecosystem" github: ruby-compendium -status: On Hold +inactive: true +home: /ruby-compendium/ +docs: /ruby-compendium/book/ +summary: "A free book aiming to help beginners learn about Ruby. It doesn’t focus on learning the language, but rather on its vast ecosystem and freely available resources." version: 0.2.0 ----- -<nav class="project-links"> - <a href="https://github.com/h3rald/ruby-compendium/downloads">DOWNLOAD</a> | <a href="/ruby-compendium/book">READ ONLINE</a> | <a href="https://github.com/h3rald/ruby-compendium">SOURCE</a> | <a href="http://github.com/h3rald/ruby-compendium/issues">TRACKING</a> -</nav> -<ul class="project-data"> - <li>Project Status: <strong>On Hold</strong></li> - <li>Version: <strong>0.2.0</strong></li> -</ul> - - <p>This book was written by Fabio Cevasco and it is licensed under a <a href="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons Attribution-ShareAlike 3.0 Unported License</a>.</p> <p>This book was authored using <a href="http://www.h3rald.com/glyph">Glyph</a> and the <span class="caps">PDF</span> version was produced with <a href="http://www.princexml.org">Prince <span class="caps">XML</span></a>.</p> <p>The Ruby logo is copyright © 2006, Yukihiro Matsumoto, and used under the terms of the <a href="http://creativecommons.org/licenses/by-sa/2.5/">Creative Commons Attribution-ShareAlike 2.5 License</a>.</p>@@ -28,8 +22,8 @@
<h3>Latest Updates</h3> -<ul><li><a href="/articles/ruby-compendium-020/">Ruby Compendium v0.2.0 released</a> — <time class="timeago" datetime="2011-08-07T16:01:52Z">Sunday, 07 August 2011</time></li> -<li><a href="/articles/introducing-ruby-compendium/">Introducing the Ruby Compendium</a> — <time class="timeago" datetime="2011-01-23T17:02:15Z">Sunday, 23 January 2011</time></li> +<ul><li><a href="/articles/ruby-compendium-020/">Ruby Compendium v0.2.0 released</a></li> + <li><a href="/articles/introducing-ruby-compendium/">Introducing the Ruby Compendium</a></li> </ul>
A
contents/ruby-compendium/book/books.html
@@ -0,0 +1,30 @@
+----- +title: "Ruby Compendium – Books" +content-type: page +----- +<nav class="navigation"><a href="/ruby-compendium/book/web-sites.html">← Web Sites</a> | <a href="/ruby-compendium/book/index.html">Contents</a> | <a href="/ruby-compendium/book/podcasts.html">Podcasts and Screencasts →</a></nav> + + <p><strong><a href="http://www.humblelittlerubybook.com/book/">The Humble Little Ruby Book</a></strong> – A nicely-written free book on Ruby, by <a href="/ruby-compendium/book/rubyists.html#jm">Jeremy McAnally</a></p> + + <p><strong><a href="http://www.sapphiresteel.com/The-Little-Book-Of-Ruby">The Little Book of Ruby</a></strong> – An 87-page free introduction covering Ruby basics.</p> + + <p><strong><a href="http://www.sapphiresteel.com/Blog/The-Book-Of-Ruby-free-in-depth">The Book of Ruby</a></strong> – A 400-page free Ruby bible by Huw Collingbourne.</p> + + <p><strong><a href="http://ruby-doc.org/docs/ProgrammingRuby/">Programming Ruby</a></strong> – The first edition of the so-called <em>Pickaxe</em> book, available for free, by <a href="/ruby-compendium/book/rubyists.html#davethomas">Dave Thomas</a>, <a href="/ruby-compendium/book/rubyists.html#chad">Chad Fowler</a> and <a href="/ruby-compendium/book/rubyists.html#andyhunt">Andy Hunt</a></p> + + <p><strong><a href="http://mislav.uniqpath.com/poignant-guide/">Why’s (poignant) guide to Ruby</a></strong> – The legendary book by <a href="/ruby-compendium/book/rubyists.html#_why">why the lucky stiff</a>. With foxes, little elves, and… chunky bacon!). Exquisitely weird and witty.</p> + + <p><strong><a href="http://ruby.runpaint.org/">Read Ruby 1.9</a></strong> – <em>“Very early draft of a book about version 1.9 of the Ruby programming language, released under a Creative Commons license.”</em></p> + + <p><strong><a href="http://ruby.learncodethehardway.org/">Learn Ruby The Hard Way</a></strong> – A Ruby translation of the popular book <em>Learn Python The Hard Way</em>, by Zed Shaw.</p> +<aside class="box"> +<div class="box-title">What about <em>real</em> books?</div> +<p>All the books mentioned so far are free, but there’s plenty of published books on Ruby. Check out the following titles:</p> +<ul> + <li><a href="http://www.informit.com/imprint/series_detail.aspx?ser=2124042">Addison-Wesley Progessional Ruby Series</a></li> + <li><a href="http://oreilly.com/pub/topic/ruby">Ruby books by O’Reilly</a></li> + <li><a href="http://pragprog.com/categories/ruby_and_rails">Ruby books by Pragmatic Programmers</a></li> +</ul> + +</aside> +<nav class="navigation"><a href="/ruby-compendium/book/web-sites.html">← Web Sites</a> | <a href="/ruby-compendium/book/index.html">Contents</a> | <a href="/ruby-compendium/book/podcasts.html">Podcasts and Screencasts →</a></nav>
A
contents/ruby-compendium/book/core-stdlib.html
@@ -0,0 +1,31 @@
+----- +title: "Ruby Compendium – The Core and the Standard Library" +content-type: page +----- +<nav class="navigation"><a href="/ruby-compendium/book/syntax.html">← Syntax</a> | <a href="/ruby-compendium/book/index.html">Contents</a> | <a href="/ruby-compendium/book/features.html">Advanced Language Features →</a></nav> +<p>By default, Ruby always loads its core classes and modules when a script is executed. This means that in all Ruby programs you can always instantiate core objects like:</p> +<ul> + <li>Numbers (integers, floats)</li> + <li>Strings</li> + <li>Arrays</li> + <li>Hashes</li> + <li>Files</li> + <li>Regular expressions</li> + <li>Symbols</li> + <li>Threads</li> + <li>Times and dates</li> + <li>…and many more.</li> +</ul> +<p>Most likely, this is not going to be enough. That’s when the Standard Library comes into play: it’s a large collection of internal libraries that ships with every Ruby implementations. There are libraries to connect to the Internet, to read/write to various file formats such as <span class="caps">CSV</span> or <span class="caps">YAML</span>, to work with files and paths, access system features, and so on.</p> +<p>Unlike core classes, standard libraries must be required specifically if needed, before they can be used.</p> +<aside class="box"> +<div class="box-title">If you want to know more...</div> +<p>On core libraries and the Standard Library, checkout the official documentation:</p> +<ul> + <li><a href="http://www.ruby-doc.org/core/">Core Reference</a></li> + <li><a href="http://www.ruby-doc.org/stdlib/">Standard Library Reference</a></li> +</ul> +<p>Overwhelmed? Don’t know where to start? Familiarize yourself with the <a href="http://www.ruby-doc.org/core/classes/Enumerable.html">Enumerable</a> module; you won’t regret it!</p> + +</aside> +<nav class="navigation"><a href="/ruby-compendium/book/syntax.html">← Syntax</a> | <a href="/ruby-compendium/book/index.html">Contents</a> | <a href="/ruby-compendium/book/features.html">Advanced Language Features →</a></nav>
A
contents/ruby-compendium/book/features.html
@@ -0,0 +1,31 @@
+----- +title: "Ruby Compendium – Advanced Language Features" +content-type: page +----- +<nav class="navigation"><a href="/ruby-compendium/book/core-stdlib.html">← The Core and the Standard Library</a> | <a href="/ruby-compendium/book/index.html">Contents</a> | <a href="/ruby-compendium/book/gems.html">Ruby Gems →</a></nav> +<p>One of the best things about Ruby is that you’re not stuck with a single programming paradigm. Even though everything in Ruby is an object (thereby making it a fully object-oriented language), nothing forbids you to program procedurally, or even use typical functional constructs.</p> +<p>The beauty of this is that you can (and should) combine elements from different paradigms, resulting in very powerful and expressive code. What I really like about Ruby though is its inherent dynamic nature.</p> +<p>You have a very few constraints when coding:</p> +<ul> + <li>you can open and close class definitions at will,</li> + <li>you are not constrained by object types</li> + <li>you can mix-in methods in multiple classes at the same time</li> + <li>you can write code that <em>writes itself</em> dynamically (this is commonly called <em>metaprogramming</em>)</li> + <li>you can easily create Domain-Specific Language to solve problems faster, with style</li> + <li>you can create and pass around blocks of code</li> +</ul> +<p>All these things make the language very flexible and powerful. Do not overuse Ruby’s power: if your code starts to look like black magic, you’re probably going too far.</p> +<aside class="box"> +<div class="box-title">If you want to know more...</div> +<p>…on specific and advanced Ruby features, check out these articles:</p> +<ul> + <li><a href="http://olabini.com/blog/2006/09/ruby-metaprogramming-techniques/">Ruby Metaprogramming techniques</a></li> + <li><a href="http://www.skorks.com/2010/05/ruby-procs-and-lambdas-and-the-difference-between-them/">Ruby Procs And Lambdas (And The Difference Between Them)</a></li> + <li><a href="http://juixe.com/techknow/index.php/2006/06/15/mixins-in-ruby/">Ruby Mixin Tutorial</a></li> + <li><a href="http://www.valibuk.net/2009/03/domain-specific-languages-in-ruby/">Domain Specific Languages in Ruby</a></li> +</ul> + +</aside> + + +<nav class="navigation"><a href="/ruby-compendium/book/core-stdlib.html">← The Core and the Standard Library</a> | <a href="/ruby-compendium/book/index.html">Contents</a> | <a href="/ruby-compendium/book/gems.html">Ruby Gems →</a></nav>
A
contents/ruby-compendium/book/gem-tips.html
@@ -0,0 +1,352 @@
+----- +title: "Ruby Compendium – What you can use for..." +content-type: page +----- +<nav class="navigation"><a href="/ruby-compendium/book/gems.html">← Ruby Gems</a> | <a href="/ruby-compendium/book/index.html">Contents</a> | <a href="/ruby-compendium/book/resources.html">Resources →</a></nav> +<p>You could spend hours on the RubyGems web site to find what you’re looking for sometimes. Not because you can’t find it, but because often there are too many alternative libraries that overlap in terms of functionalities offered.</p> +<p>A site to check when you don’t know much of what has been done in a particular domain is <a href="http://ruby-toolbox.com/">The Ruby Toolbox</a>, which organizes quite a lot of gems into <a href="http://ruby-toolbox.com/categories.html">categories</a>. This section is somewhat similar, but it focuses on just a few common tasks and a small set of hand-picked gems.</p> + +<section class="section"> +<header><h1 id="h_18" class="toc">Command Line Applications</h1></header> +<p><strong>cmdparse</strong> <blockquote>“cmdparse provides classes for parsing commands on the command line; command line options are parsed using optparse or any other option parser implementation.”</blockquote></p> +<ul> + <li>Web Page: <a href="http://cmdparse.rubyforge.org/">http://cmdparse.rubyforge.org/</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/cmdparse">http://www.rubygems.org/gems/cmdparse</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/cmdparse">http://www.rubydoc.info/gems/cmdparse</a></li> +</ul> + + <p><strong>gli</strong> <blockquote>“An application and <span class="caps">API</span> for describing command line interfaces that can be used to quickly create a shell for executing command-line tasks.”</blockquote></p> +<ul> + <li>Web Page: <a href="http://davetron5000.github.com/gli">http://davetron5000.github.com/gli</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/gli">http://www.rubygems.org/gems/gli</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/gli">http://www.rubydoc.info/gems/gli</a></li> +</ul> + + <p><strong>highline</strong> <blockquote>“A high-level IO library that provides validation, type conversion, and more for command-line interfaces. HighLine also includes a complete menu system that can crank out anything from simple list selection to complete shells with just minutes of work.”</blockquote></p> +<ul> + <li>Web Page: <a href="http://highline.rubyforge.org/">http://highline.rubyforge.org/</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/highline">http://www.rubygems.org/gems/highline</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/highline">http://www.rubydoc.info/gems/highline</a></li> +</ul> + + <p><strong>hirb</strong> <blockquote>“A mini view framework for console/irb that’s easy to use, even while under its influence. Console goodies include a no-wrap table, auto-pager, tree and menu”</blockquote></p> +<ul> + <li>Web Page: <a href="https://github.com/cldwalker/hirb">https://github.com/cldwalker/hirb</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/hirb">http://www.rubygems.org/gems/hirb</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/hirb">http://www.rubydoc.info/gems/hirb</a></li> +</ul> + +</section> +<section class="section"> +<header><h1 id="h_19" class="toc">Documentation</h1></header> +<p><strong>glyph</strong> <blockquote>“Glyph is a framework for structured document authoring.”</blockquote></p> +<ul> + <li>Web Page: <a href="http://www.h3rald.com/glyph/">http://www.h3rald.com/glyph/</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/glyph">http://www.rubygems.org/gems/glyph</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/glyph">http://www.rubydoc.info/gems/glyph</a></li> +</ul> + + <p><strong>rdoc</strong> <blockquote>“RDoc produces <span class="caps">HTML</span> and online documentation for Ruby projects. RDoc includes the rdoc and ri tools for generating and displaying online documentation.”</blockquote></p> +<ul> + <li>Web Page: <a href="https://github.com/rdoc/rdoc/">https://github.com/rdoc/rdoc/</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/rdoc">http://www.rubygems.org/gems/rdoc</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/rdoc">http://www.rubydoc.info/gems/rdoc</a></li> +</ul> + + <p><strong>yard</strong> <blockquote>“<span class="caps">YARD</span> is a documentation generation tool for the Ruby programming language. It enables the user to generate consistent, usable documentation that can be exported to a number of formats very easily, and also supports extending for custom Ruby constructs such as custom class level definitions.”</blockquote></p> +<ul> + <li>Web Page: <a href="http://yardoc.org/">http://yardoc.org/</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/yard">http://www.rubygems.org/gems/yard</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/yard">http://www.rubydoc.info/gems/yard</a></li> +</ul> + +</section> +<section class="section"> +<header><h1 id="h_20" class="toc">Gem Management</h1></header> +<p><strong>bundler</strong> <blockquote>“Bundler manages an application’s dependencies through its entire life, across many machines, systematically and repeatably.”</blockquote></p> +<ul> + <li>Web Page: <a href="http://gembundler.com/">http://gembundler.com/</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/bundler">http://www.rubygems.org/gems/bundler</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/bundler">http://www.rubydoc.info/gems/bundler</a></li> +</ul> + + <p><strong>jeweler</strong> <blockquote>“Simple and opinionated helper for creating Rubygem projects on GitHub”</blockquote></p> +<ul> + <li>Web Page: <a href="http://github.com/technicalpickles/jeweler">http://github.com/technicalpickles/jeweler</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/jeweler">http://www.rubygems.org/gems/jeweler</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/jeweler">http://www.rubydoc.info/gems/jeweler</a></li> +</ul> + + <p><strong>bones</strong> <blockquote>“Mr Bones is a handy tool that creates new projects from a code skeleton.”</blockquote></p> +<ul> + <li>Web Page: <a href="https://github.com/TwP/bones">https://github.com/TwP/bones</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/bones">http://www.rubygems.org/gems/bones</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/bones">http://www.rubydoc.info/gems/bones</a></li> +</ul> + +</section> +<section class="section"> +<header><h1 id="h_21" class="toc">GUI Programming</h1></header> +<p><strong>bowline</strong> <blockquote>“Ruby/JS <span class="caps">GUI</span> framework”</blockquote></p> +<ul> + <li>Web Page: <a href="http://bowlineapp.com/">http://bowlineapp.com/</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/bowline">http://www.rubygems.org/gems/bowline</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/bowline">http://www.rubydoc.info/gems/bowline</a></li> +</ul> + + <p><strong>fxruby</strong> <blockquote>“FXRuby is the Ruby binding to the <span class="caps">FOX</span> <span class="caps">GUI</span> toolkit”</blockquote></p> +<ul> + <li>Web Page: <a href="http://www.fxruby.org/">http://www.fxruby.org/</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/fxruby">http://www.rubygems.org/gems/fxruby</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/fxruby">http://www.rubydoc.info/gems/fxruby</a></li> +</ul> + + <p><strong>wxruby</strong> <blockquote>“wxRuby allows the creation of graphical user interface (<span class="caps">GUI</span>) applications via the wxWidgets library. wxRuby provides native-style <span class="caps">GUI</span> windows, dialogs and controls on platforms including Windows, OS X and Linux.”</blockquote></p> +<ul> + <li>Web Page: <a href="http://wxruby.org/">http://wxruby.org/</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/wxruby">http://www.rubygems.org/gems/wxruby</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/wxruby">http://www.rubydoc.info/gems/wxruby</a></li> +</ul> + + <p><strong>qtruby4</strong> <blockquote>“Qt4 Bindings for Ruby.”</blockquote></p> +<ul> + <li>Web Page: <a href="http://rubyforge.org/projects/korundum/">http://rubyforge.org/projects/korundum/</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/qtruby4">http://www.rubygems.org/gems/qtruby4</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/qtruby4">http://www.rubydoc.info/gems/qtruby4</a></li> +</ul> + + <p><strong>rugui</strong> <blockquote>“RuGUI is a framework which aims to help building desktop applications. RuGUI was mostly inspired by the Ruby on Rails framework, taking most of its features from it.”</blockquote></p> +<ul> + <li>Web Page: <a href="http://rugui.org/">http://rugui.org/</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/rugui">http://www.rubygems.org/gems/rugui</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/rugui">http://www.rubydoc.info/gems/rugui</a></li> +</ul> + <aside class="box"> +<div class="box-title">What about Shoes?</div> +<a href="http://shoesrb.com/">Shoes</a> is a cross-platform, easy-to-use Ruby toolkit originally created by <a href="/ruby-compendium/book/rubyists.html#_why"></a>. Unfortunately, it is distributed as a standalone application rather than a gem (yet), due to its internal architecture and dependencies. + +</aside> + +</section> +<section class="section"> +<header><h1 id="h_22" class="toc">Markup and Template Languages</h1></header> +<p><strong>bluecloth</strong> <blockquote>“BlueCloth is a Ruby implementation of Markdown, a text-to-<span class="caps">HTML</span> conversion tool for web writers. To quote from the project page: Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid <span class="caps">XHTML</span> (or <span class="caps">HTML</span>).”</blockquote></p> +<ul> + <li>Web Page: <a href="http://www.deveiate.org/projects/BlueCloth">http://www.deveiate.org/projects/BlueCloth</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/bluecloth">http://www.rubygems.org/gems/bluecloth</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/bluecloth">http://www.rubydoc.info/gems/bluecloth</a></li> +</ul> + + <p><strong>github-markup</strong> <blockquote>“This gem is used by GitHub to render any fancy markup such as Markdown, Textile, Org-Mode, etc. Fork it and add your own!”</blockquote></p> +<ul> + <li>Web Page: <a href="http://github.com/github/markup">http://github.com/github/markup</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/github-markup">http://www.rubygems.org/gems/github-markup</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/github-markup">http://www.rubydoc.info/gems/github-markup</a></li> +</ul> + + <p><strong>haml</strong> <blockquote>“Haml (<span class="caps">HTML</span> Abstraction Markup Language) is a layer on top of <span class="caps">XHTML</span> or <span class="caps">XML</span> that’s designed to express the structure of <span class="caps">XHTML</span> or <span class="caps">XML</span> documents in a non-repetitive, elegant, easy way, using indentation rather than closing tags and allowing Ruby to be embedded with ease. It was originally envisioned as a plugin for Ruby on Rails, but it can function as a stand-alone templating engine.”</blockquote></p> +<ul> + <li>Web Page: <a href="http://haml-lang.com/">http://haml-lang.com/</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/haml">http://www.rubygems.org/gems/haml</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/haml">http://www.rubydoc.info/gems/haml</a></li> +</ul> + + <p><strong>liquid</strong> <blockquote>“A secure, non-evaling end user template engine with aesthetic markup.”</blockquote></p> +<ul> + <li>Web Page: <a href="http://www.liquidmarkup.org/">http://www.liquidmarkup.org/</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/liquid">http://www.rubygems.org/gems/liquid</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/liquid">http://www.rubydoc.info/gems/liquid</a></li> +</ul> + + <p><strong>mustache</strong> <blockquote>"Inspired by ctemplate, Mustache is a framework-agnostic way to render logic-free views. As ctemplates says, “It emphasizes separating logic from presentation: it is impossible to embed application logic in this template language. Think of Mustache as a replacement for your views. Instead of views consisting of <span class="caps">ERB</span> or <span class="caps">HAML</span> with random helpers and arbitrary logic, your views are broken into two parts: a Ruby class and an <span class="caps">HTML</span> template.”</blockquote></p> +<ul> + <li>Web Page: <a href="http://github.com/defunkt/mustache">http://github.com/defunkt/mustache</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/mustache">http://www.rubygems.org/gems/mustache</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/mustache">http://www.rubydoc.info/gems/mustache</a></li> +</ul> + + <p><strong>rdiscount</strong> <blockquote>“Fast Implementation of Gruber’s Markdown in C”</blockquote></p> +<ul> + <li>Web Page: <a href="http://github.com/rtomayko/rdiscount/">http://github.com/rtomayko/rdiscount/</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/rdiscount">http://www.rubygems.org/gems/rdiscount</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/rdiscount">http://www.rubydoc.info/gems/rdiscount</a></li> +</ul> + + <p><strong>redcloth</strong> <blockquote>“RedCloth is a Ruby library for converting Textile into <span class="caps">HTML</span>.”</blockquote></p> +<ul> + <li>Web Page: <a href="http://redcloth.org/">http://redcloth.org/</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/redcloth">http://www.rubygems.org/gems/redcloth</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/redcloth">http://www.rubydoc.info/gems/redcloth</a></li> +</ul> + +</section> +<section class="section"> +<header><h1 id="h_23" class="toc">Static Web Site Generators</h1></header> +<p><strong>jekyll</strong> <blockquote>“Jekyll is a simple, blog aware, static site generator.”</blockquote></p> +<ul> + <li>Web Page: <a href="http://jekyllrb.com/">http://jekyllrb.com/</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/jekyll">http://www.rubygems.org/gems/jekyll</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/jekyll">http://www.rubydoc.info/gems/jekyll</a></li> +</ul> + + <p><strong>nanoc</strong> <blockquote>“a web publishing system written in Ruby for building small to medium-sized websites.”</blockquote></p> +<ul> + <li>Web Page: <a href="http://nanoc.stoneship.org/">http://nanoc.stoneship.org/</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/nanoc">http://www.rubygems.org/gems/nanoc</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/nanoc">http://www.rubydoc.info/gems/nanoc</a></li> +</ul> + + <p><strong>toto</strong> <blockquote>“the tiniest blog-engine in Oz.”</blockquote></p> +<ul> + <li>Web Page: <a href="http://cloudhead.io/toto">http://cloudhead.io/toto</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/toto">http://www.rubygems.org/gems/toto</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/toto">http://www.rubydoc.info/gems/toto</a></li> +</ul> + + <p><strong>webby</strong> <blockquote>“Webby is a fantastic little website management system. It would be called a content management system if it were a bigger kid. But, it’s just a runt with a special knack for transforming text. And that’s really all it does – manages the legwork of turning text into something else, an <span class="caps">ASCII</span> Alchemist if you will.”</blockquote></p> +<ul> + <li>Web Page: <a href="http://webby.rubyforge.org/">http://webby.rubyforge.org/</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/webby">http://www.rubygems.org/gems/webby</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/webby">http://www.rubydoc.info/gems/webby</a></li> +</ul> + +</section> +<section class="section"> +<header><h1 id="h_24" class="toc">Testing</h1></header> +<p><strong>bacon</strong> <blockquote>“Bacon is a small RSpec clone weighing less than 350 LoC but nevertheless providing all essential features.”</blockquote></p> +<ul> + <li>Web Page: <a href="http://github.com/chneukirchen/bacon">http://github.com/chneukirchen/bacon</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/bacon">http://www.rubygems.org/gems/bacon</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/bacon">http://www.rubydoc.info/gems/bacon</a></li> +</ul> + + <p><strong>cucumber</strong> <blockquote>“Behaviour Driven Development with elegance and joy”</blockquote></p> +<ul> + <li>Web Page: <a href="http://cukes.info/">http://cukes.info/</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/cucumber">http://www.rubygems.org/gems/cucumber</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/cucumber">http://www.rubydoc.info/gems/cucumber</a></li> +</ul> + + <p><strong>minitest</strong> <blockquote>“minitest provides a complete suite of testing facilities supporting <span class="caps">TDD</span>, <span class="caps">BDD</span>, mocking, and benchmarking. minitest/unit is a small and incredibly fast unit testing framework.”</blockquote></p> +<ul> + <li>Web Page: <a href="https://github.com/seattlerb/minitest">https://github.com/seattlerb/minitest</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/minitest">http://www.rubygems.org/gems/minitest</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/minitest">http://www.rubydoc.info/gems/minitest</a></li> +</ul> + + <p><strong>rspec</strong> <blockquote>“RSpec is a Behaviour-Driven Development tool for Ruby programmers. <span class="caps">BDD</span> is an approach to software development that combines Test-Driven Development, Domain Driven Design, and Acceptance Test-Driven Planning. RSpec helps you do the <span class="caps">TDD</span> part of that equation, focusing on the documentation and design aspects of <span class="caps">TDD</span>.”</blockquote></p> +<ul> + <li>Web Page: <a href="http://relishapp.com/rspec">http://relishapp.com/rspec</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/rspec">http://www.rubygems.org/gems/rspec</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/rspec">http://www.rubydoc.info/gems/rspec</a></li> +</ul> + + <p><strong>shoulda</strong> <blockquote>“Making tests easy on the fingers and eyes”</blockquote></p> +<ul> + <li>Web Page: <a href="http://www.thoughtbot.com/projects/shoulda">http://www.thoughtbot.com/projects/shoulda</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/shoulda">http://www.rubygems.org/gems/shoulda</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/shoulda">http://www.rubydoc.info/gems/shoulda</a></li> +</ul> + +</section> +<section class="section"> +<header><h1 id="h_25" class="toc">Web Development</h1></header> +<p><strong>rails</strong> <blockquote>“Ruby on Rails is a full-stack web framework optimized for programmer happiness and sustainable productivity. It encourages beautiful code by favoring convention over configuration.”</blockquote></p> +<ul> + <li>Web Page: <a href="http://rubyonrails.org/">http://rubyonrails.org/</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/rails">http://www.rubygems.org/gems/rails</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/rails">http://www.rubydoc.info/gems/rails</a></li> +</ul> + + <p><strong>sinatra</strong> <blockquote>“Classy web-development dressed in a <span class="caps">DSL</span>”</blockquote></p> +<ul> + <li>Web Page: <a href="http://www.sinatrarb.com/">http://www.sinatrarb.com/</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/sinatra">http://www.rubygems.org/gems/sinatra</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/sinatra">http://www.rubydoc.info/gems/sinatra</a></li> +</ul> + + <p><strong>padrino-framework</strong> <blockquote>“The Godfather of Sinatra provides a full-stack agnostic framework on top of Sinatra”</blockquote></p> +<ul> + <li>Web Page: <a href="http://www.padrinorb.com/">http://www.padrinorb.com/</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/padrino-framework">http://www.rubygems.org/gems/padrino-framework</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/padrino-framework">http://www.rubydoc.info/gems/padrino-framework</a></li> +</ul> + + <p><strong>merb-core</strong> <blockquote>“Merb. Pocket rocket web framework.”</blockquote></p> +<ul> + <li>Web Page: <a href="http://www.merbivore.com/">http://www.merbivore.com/</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/merb-core">http://www.rubygems.org/gems/merb-core</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/merb-core">http://www.rubydoc.info/gems/merb-core</a></li> +</ul> + + <p><strong>ramaze</strong> <blockquote>“Ramaze is a simple and modular web framework”</blockquote></p> +<ul> + <li>Web Page: <a href="http://ramaze.net/">http://ramaze.net/</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/ramaze">http://www.rubygems.org/gems/ramaze</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/ramaze">http://www.rubydoc.info/gems/ramaze</a></li> +</ul> + + <p><strong>camping</strong> <blockquote>“miniature rails for stay-at-home moms”</blockquote></p> +<ul> + <li>Web Page: <a href="http://camping.rubyforge.org/">http://camping.rubyforge.org/</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/camping">http://www.rubygems.org/gems/camping</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/camping">http://www.rubydoc.info/gems/camping</a></li> +</ul> + +</section> +<section class="section"> +<header><h1 id="h_26" class="toc">Web and App Servers</h1></header> +<p><strong>passenger</strong> <blockquote>“Easy and robust Ruby web application deployment.”</blockquote></p> +<ul> + <li>Web Page: <a href="http://www.modrails.com/">http://www.modrails.com/</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/passenger">http://www.rubygems.org/gems/passenger</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/passenger">http://www.rubydoc.info/gems/passenger</a></li> +</ul> + + <p><strong>rack</strong> <blockquote>“Rack provides a minimal interface between webservers supporting Ruby and Ruby frameworks.”</blockquote></p> +<ul> + <li>Web Page: <a href="http://rack.rubyforge.org/">http://rack.rubyforge.org/</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/rack">http://www.rubygems.org/gems/rack</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/rack">http://www.rubydoc.info/gems/rack</a></li> +</ul> + + <p><strong>thin</strong> <blockquote>“A thin and fast web server”</blockquote></p> +<ul> + <li>Web Page: <a href="http://code.macournoyer.com/thin/">http://code.macournoyer.com/thin/</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/thin">http://www.rubygems.org/gems/thin</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/thin">http://www.rubydoc.info/gems/thin</a></li> +</ul> + + <p><strong>unicorn</strong> <blockquote>“Unicorn is an <span class="caps">HTTP</span> server for Rack applications designed to only serve fast clients on low-latency, high-bandwidth connections and take advantage of features in Unix/Unix-like kernels.”</blockquote></p> +<ul> + <li>Web Page: <a href="http://unicorn.bogomips.org/">http://unicorn.bogomips.org/</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/unicorn">http://www.rubygems.org/gems/unicorn</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/unicorn">http://www.rubydoc.info/gems/unicorn</a></li> +</ul> + +</section> +<section class="section"> +<header><h1 id="h_27" class="toc">XML Parsing</h1></header> +<p><strong>hpricot</strong> <blockquote>“a swift, liberal <span class="caps">HTML</span> parser with a fantastic library”</blockquote></p> +<ul> + <li>Web Page: <a href="http://code.whytheluckystiff.net/hpricot/">http://code.whytheluckystiff.net/hpricot/</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/hpricot">http://www.rubygems.org/gems/hpricot</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/hpricot">http://www.rubydoc.info/gems/hpricot</a></li> +</ul> + + <p><strong>nokogiri</strong> <blockquote>“An <span class="caps">HTML</span>, <span class="caps">XML</span>, <span class="caps">SAX</span>, & Reader parser with the ability to search documents via XPath or CSS3 selectors… and much more”</blockquote></p> +<ul> + <li>Web Page: <a href="http://nokogiri.org/">http://nokogiri.org/</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/nokogiri">http://www.rubygems.org/gems/nokogiri</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/nokogiri">http://www.rubydoc.info/gems/nokogiri</a></li> +</ul> + + <p><strong>xml-simple</strong> <blockquote>“A simple <span class="caps">API</span> for <span class="caps">XML</span> processing.”</blockquote></p> +<ul> + <li>Web Page: <a href="http://xml-simple.rubyforge.org/">http://xml-simple.rubyforge.org/</a></li> + <li>Download: <a href="http://www.rubygems.org/gems/xml-simple">http://www.rubygems.org/gems/xml-simple</a></li> + <li>Documentation: <a href="http://www.rubydoc.info/gems/xml-simple">http://www.rubydoc.info/gems/xml-simple</a></li> +</ul> + +</section> +<nav class="navigation"><a href="/ruby-compendium/book/gems.html">← Ruby Gems</a> | <a href="/ruby-compendium/book/index.html">Contents</a> | <a href="/ruby-compendium/book/resources.html">Resources →</a></nav>
A
contents/ruby-compendium/book/gems.html
@@ -0,0 +1,20 @@
+----- +title: "Ruby Compendium – Ruby Gems" +content-type: page +----- +<nav class="navigation"><a href="/ruby-compendium/book/features.html">← Advanced Language Features</a> | <a href="/ruby-compendium/book/index.html">Contents</a> | <a href="/ruby-compendium/book/gem-tips.html">What you can use for... →</a></nav> +<p>Sure, the <a href="/ruby-compendium/book/core-stdlib.html#core-stdlib">Standard Library</a> is quite large but… no, it does not have everything you need. Luckily, it’s full of gems out there! Rubygems is Ruby’s packaging system, and the best way to distribute your own libraries and applications.</p> +<p>The Rubygems packaging system is now included in most Ruby implementation and distributions. Installing a gem and all its dependencies is as easy as issuing <code>gem install <name of the gem></code>. So for example if you want to install the <a href="https://rubygems.org/gems/rails">rails</a> gem, you can just run</p> +<p><code>gem install rails</code></p> +<p>…and it will be automatically downloaded and installed on your system, along with the other gems it depends on.</p> +<section class="section"> +<header><h1 id="h_16" class="toc">RubyGems.org</h1></header> +There are over 1300 different gems publicly (and freely!) available. Luckily, the official gem host site, <a href="http://www.rubygems.org">RubyGems.org</a> makes it very easy to find what you're looking for: just search for a particular gem or a functionality you're looking for, and browse through the results. You can also register and <em>push</em> your own gems for other people to use. + +</section> +<aside class="box"> +<div class="box-title">What happened to RubyForge?</div> +<p>If you started to learn Ruby a few years ago, the <a href="http://www.rubyforge.org">RubyForge</a> was <em>the</em> place to find user-created ruby code and gems. The site is still there, but nowadays Rubyists prefer using <a href="http://www.github.com">GitHub</a> as host for their source code repositories and RubyGems.org as the home for their gems.</p> + +</aside> +<nav class="navigation"><a href="/ruby-compendium/book/features.html">← Advanced Language Features</a> | <a href="/ruby-compendium/book/index.html">Contents</a> | <a href="/ruby-compendium/book/gem-tips.html">What you can use for... →</a></nav>
A
contents/ruby-compendium/book/implementations.html
@@ -0,0 +1,83 @@
+----- +title: "Ruby Compendium – Versions and Implementations" +content-type: page +----- +<nav class="navigation"><a href="/ruby-compendium/book/ten-good-things.html">← 10 Good Things about Ruby</a> | <a href="/ruby-compendium/book/index.html">Contents</a> | <a href="/ruby-compendium/book/syntax.html">Syntax →</a></nav> +<p>One thing that may appear unusual and even discouraging to newcomers is the different versions and implementations of the language. Ruby has two version branches:</p> +<ul> + <li><strong>1.8</strong> – The former stable version, which is still widely used in production and it is still updated.</li> + <li><strong>1.9</strong> – As of release 1.9.2, this is considered the current stable and recommended version of the language. Although most third-party libraries work with it, some old and now unmaintained libraries may not. The good news is that there are normally newer and better libraries available instead.</li> +</ul> +<p>Different implementations of Ruby offer different degrees of support to one or the other version. Compared to 1.8, Ruby 1.9 has some additional syntax for certain expressions, improved character encoding support and a few new bundled libraries and features.</p> +<p>If you’re new to Ruby and you have no particular restrictions or needs, you should start learning Ruby using version 1.9 (either <a href="#yarv">the official implementation</a>, <a href="#jruby">JRuby</a> or <a href="#macruby">MacRuby</a>)!</p> +<aside class="box"> +<div class="box-title">If you want to know more...</div> +<p>There are many articles and presentations online outlining the changes in Ruby 1.9, for example:</p> +<ul> + <li><a href="http://www.slideshare.net/komrade/piterrb-2-ruby-18-vs-ruby-19">Piter.rb #2 – Ruby 1.8 vs Ruby 1.9</a></li> + <li><a href="http://eigenclass.org/hiki/Changes+in+Ruby+1.9">Changes in Ruby 1.9</a></li> + <li><a href="http://slideshow.rubyforge.org/ruby19.html#1">Ruby 1.9: What to Expect</a></li> +</ul> + +</aside> +<section class="section"> +<header><h1 id="h_6" class="notoc">Official Ruby 1.8 Implementation</h1></header> +<p>The official Ruby 1.8 implementation was written in C by Yukihiru Matsumoto, the creator of Ruby.</p> +<ul> + <li>Current Version: <strong>1.8.7-p352</strong></li> + <li>Download: <a href="http://www.ruby-lang.org/en/downloads/">Official Ruby Web Site</a></li> +</ul> + +</section> +<section class="section"> +<header><h1 id="yarv" class="notoc">Official Ruby 1.9 Implementation</h1></header> +<p>The official Ruby 1.9 implementation is based on a bytecode interpreter written Koichi Sasada.</p> +<ul> + <li>Current Version: <strong>1.9.2-p200</strong></li> + <li>Preview Version: <strong>1.9.2-preview1</strong></li> + <li>Download: <a href="http://www.ruby-lang.org/en/downloads/">Official Ruby Web Site</a></li> +</ul> + +</section> +<section class="section"> +<header><h1 id="jruby" class="notoc">JRuby</h1></header> +<p>An implementation of the Ruby language running on the Java Virtual Machine, mature and usable in production. It offers real threading, performance improvements, and Java interoperability. Fully-compatible with both Ruby 1.8 and 1.9.</p> +<ul> + <li>Current Version: <strong>1.6.3</strong></li> + <li>Download: <a href="http://jruby.org/">JRuby Web Site</a></li> +</ul> + +</section> +<section class="section"> +<header><h1 id="h_9" class="notoc">Rubinius</h1></header> +<p>A C++ and <a href="http://llvm.org/"><span class="caps">LLVM</span></a>-powered Ruby implementation. Although still not as mature as <span class="caps">YARV</span> or JRuby, it’s getting there. It currently aims at being compatible with Ruby 1.8.7, although support for Ruby 1.9 is planned.</p> +<ul> + <li>Current Version: <strong>1.2.4</strong></li> + <li>Download: <a href="http://rubini.us/">Rubinius Web Site</a></li> +</ul> + +</section> +<section class="section"> +<header><h1 id="macruby" class="notoc">MacRuby</h1></header> +<p>A Mac-only Ruby implementation compatible with Ruby 1.9, specifically tuned for Mac OS X operating systems.</p> +<ul> + <li>Current Version: <strong>0.10</strong></li> + <li>Download: <a href="http://www.macruby.org/">MacRuby Web Site</a></li> +</ul> + +</section> +<section class="section"> +<header><h1 id="h_11" class="notoc">IronRuby</h1></header> +<p>A .<span class="caps">NET</span> implementation of the Ruby Programming Language, compatible with Ruby 1.8.6 (IronRuby 1.0) and 1.9 (IronRuby 1.1.1 onwards). Not as mature as the other implementations.</p> +<ul> + <li>Current Version: <strong>1.1.3</strong></li> + <li>Download: <a href="http://www.ironruby.net/">IronRuby Web Site</a></li> +</ul> + +</section> +<aside class="box"> +<div class="box-title">Try'em All!</div> +<p>Don’t know which Ruby to choose? You don’t have to! <a href="/ruby-compendium/book/rubyists.html#wayneeseguin"></a> created <a href="https://rvm.beginrescueend.com/">Ruby Version Manager</a> (<span class="caps">RVM</span>) to allow you to install, upgrade and manage several Ruby installation seamlessly on the same computer. If you’re on OS X or Linux, that is. If you’re on a Windows computer, <a href="https://github.com/vertiginous/pik">Pik</a> provides something similar.</p> + +</aside> +<nav class="navigation"><a href="/ruby-compendium/book/ten-good-things.html">← 10 Good Things about Ruby</a> | <a href="/ruby-compendium/book/index.html">Contents</a> | <a href="/ruby-compendium/book/syntax.html">Syntax →</a></nav>
A
contents/ruby-compendium/book/index.html
@@ -0,0 +1,14 @@
+----- +title: "Ruby Compendium" +content-type: page +----- +<nav class="contents"> +<h1 class="toc-header" id="toc">Table of Contents</h1> +<ol class="toc"> + <li class="frontmatter introduction"><a href="/ruby-compendium/book/intro.html#h_1">So you want to learn Ruby...</a></li><li><ol><li class="frontmatter section"><a href="/ruby-compendium/book/notes.html#h_2">About this Book</a></li></ol></li> +<li class="bodymatter chapter"><a href="/ruby-compendium/book/language.html#h_3">Quick Tour</a></li><li><ol><li class="bodymatter section"><a href="/ruby-compendium/book/ten-good-things.html#ten-good-things">10 Good Things about Ruby</a></li><li class="bodymatter section"><a href="/ruby-compendium/book/implementations.html#implementations">Versions and Implementations</a></li><li class="bodymatter section"><a href="/ruby-compendium/book/syntax.html#syntax">Syntax</a></li><li class="bodymatter section"><a href="/ruby-compendium/book/core-stdlib.html#core-stdlib">The Core and the Standard Library</a></li><li class="bodymatter section"><a href="/ruby-compendium/book/features.html#features">Advanced Language Features</a></li></ol></li> +<li class="bodymatter chapter"><a href="/ruby-compendium/book/gems.html#gems">Ruby Gems</a></li><li><ol><li class="bodymatter section"><a href="/ruby-compendium/book/gem-tips.html#h_17">What you can use for...</a></li></ol></li> +<li class="bodymatter chapter"><a href="/ruby-compendium/book/resources.html#resources">Resources</a></li><li><ol><li class="bodymatter section"><a href="/ruby-compendium/book/web-sites.html#websites">Web Sites</a></li><li class="bodymatter section"><a href="/ruby-compendium/book/books.html#books">Books</a></li><li class="bodymatter section"><a href="/ruby-compendium/book/podcasts.html#podcasts">Podcasts and Screencasts</a></li></ol></li> +<li class="backmatter appendix"><a href="/ruby-compendium/book/rubyists.html#h_32">Notable Rubyists</a></li> +</ol> +</nav>
A
contents/ruby-compendium/book/intro.html
@@ -0,0 +1,11 @@
+----- +title: "Ruby Compendium – So you want to learn Ruby..." +content-type: page +----- +<nav class="navigation"> | <a href="/ruby-compendium/book/index.html">Contents</a> | <a href="/ruby-compendium/book/notes.html">About this Book →</a></nav> +<p>…or maybe not. Maybe you’re <em>thinking</em> about it, but you’re not entirely convinced it’s a good idea. Maybe you have an annoying co-worker who constantly raves about it and made you curious. Whatever the case, this tiny book is about telling you all you need to know about the language before you actually start getting your hands dirty.</p> +<p>There are many different ways to learn new programming languages. Typically, you’d start reading tutorials online, try a few example programs, maybe buy a book and start reading it. That’s what most people do nowadays, and it works, in the end. The downside of this is that you may spend weeks or even months trying to get the hang of the language, spend a lot of time trying to find information about it, ask dumb questions in forums and mailing lists, re-invent the wheel only to find out —months later— that someone already made a library which does exactly the same thing as yours, but in a much better way.</p> +<p>You can learn through mistakes, but there’s no harm in starting with the right foot.</p> +<p>This <em>Ruby Compendium</em> gives you an overview of the Ruby Ecosystem from 10,000ft. It briefly describes the language, its libraries, and what resources you can find online. By the time you finish reading this, you will <em>not</em> know how to write Ruby programs (yet) but you’ll definitely know <em>how to learn</em> this amazing and powerful language and where to look for information and help.</p> +<p>Close your editor now, relax, and enjoy!</p> +<nav class="navigation"> | <a href="/ruby-compendium/book/index.html">Contents</a> | <a href="/ruby-compendium/book/notes.html">About this Book →</a></nav>
A
contents/ruby-compendium/book/language.html
@@ -0,0 +1,16 @@
+----- +title: "Ruby Compendium – Quick Tour" +content-type: page +----- +<nav class="navigation"><a href="/ruby-compendium/book/notes.html">← About this Book</a> | <a href="/ruby-compendium/book/index.html">Contents</a> | <a href="/ruby-compendium/book/ten-good-things.html">10 Good Things about Ruby →</a></nav> +<p>Ruby is a relatively new programming language. It was created by <a href="/ruby-compendium/book/rubyists.html#matz">Yukihiro Matzumoto</a> (aka “Matz”) in 1995, but it took another ten years to become popular outside Japan, thanks to the <em>Ruby on Rails</em> web framework.</p> +<aside class="box"> +<div class="box-title">Isn't Ruby <em>slow?</em></div> +<p>Being a high-level, interpreted language, Ruby is slower than compiled languages like C or C++ or even other interpreted languages like Perl 5. However, this may vary depending on the implementation.</p> +<ul> + <li>If you are interested in Ruby benchmarks, check out Antonio Cangiano’s <a href="http://programmingzen.com/2010/07/19/the-great-ruby-shootout-july-2010/">Great Ruby Shootout</a>, which also includes data on <a href="http://www.rubyenterpriseedition.com/">Ruby Enterprise Edition</a> and <a href="http://ruby.gemstone.com/">MagLev</a> implementations.</li> + <li>If you are interested in benchmarks between Ruby implementations and other languages, the <a href="http://shootout.alioth.debian.org/">Computer Language Benchmark Game</a> is a good place to start.</li> +</ul> + +</aside> +<nav class="navigation"><a href="/ruby-compendium/book/notes.html">← About this Book</a> | <a href="/ruby-compendium/book/index.html">Contents</a> | <a href="/ruby-compendium/book/ten-good-things.html">10 Good Things about Ruby →</a></nav>
A
contents/ruby-compendium/book/notes.html
@@ -0,0 +1,14 @@
+----- +title: "Ruby Compendium – About this Book" +content-type: page +----- +<nav class="navigation"><a href="/ruby-compendium/book/intro.html">← So you want to learn Ruby...</a> | <a href="/ruby-compendium/book/index.html">Contents</a> | <a href="/ruby-compendium/book/language.html">Quick Tour →</a></nav> +<p>This book was written by Fabio Cevasco and it is licensed under a <a href="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons Attribution-ShareAlike 3.0 Unported License</a>.</p> +<p>This book was authored using <a href="http://www.h3rald.com/glyph">Glyph</a> and the <span class="caps">PDF</span> version was produced with <a href="http://www.princexml.org">Prince <span class="caps">XML</span></a>.</p> +<p>The Ruby logo is copyright © 2006, Yukihiro Matsumoto, and used under the terms of the <a href="http://creativecommons.org/licenses/by-sa/2.5/">Creative Commons Attribution-ShareAlike 2.5 License</a>.</p> +<p>Special thanks to the following individuals who contributed to the project, in some ways:</p> +<ul> + <li><a href="http://blog.dio.jp/">Akira Matsuda</a></li> + <li><a href="http://www.bitcetera.com/">Sven Schwyn</a></li> +</ul> +<nav class="navigation"><a href="/ruby-compendium/book/intro.html">← So you want to learn Ruby...</a> | <a href="/ruby-compendium/book/index.html">Contents</a> | <a href="/ruby-compendium/book/language.html">Quick Tour →</a></nav>
A
contents/ruby-compendium/book/podcasts.html
@@ -0,0 +1,18 @@
+----- +title: "Ruby Compendium – Podcasts and Screencasts" +content-type: page +----- +<nav class="navigation"><a href="/ruby-compendium/book/books.html">← Books</a> | <a href="/ruby-compendium/book/index.html">Contents</a> | <a href="/ruby-compendium/book/rubyists.html">Notable Rubyists →</a></nav> + + <p><strong><a href="http://5by5.tv/rubyshow">The Ruby Show</a></strong> – <em>The</em> Ruby podcast, with <a href="/ruby-compendium/book/rubyists.html#danbenjamin">Dan Benjamin</a> and <a href="/ruby-compendium/book/rubyists.html#jseifer">Jason Seifer</a>.</p> + + <p><strong><a href="http://ruby5.envylabs.com/">Ruby5</a></strong> – Frequently-released short podcasts on what’s new in the Ruby and Rails community. By <a href="/ruby-compendium/book/rubyists.html#greggpollack">Gregg Pollack</a>.</p> + + <p><strong><a href="http://rubyonrails.org/screencasts">Ruby On Rails Screencasts</a></strong> – Free Ruby on Rails screencasts</p> + + <p><strong><a href="http://sdruby.org/podcast">SD Ruby Podcast</a></strong> – Ruby podcasts by the San Diego Ruby community.</p> + + <p><strong><a href="http://www.rubypulse.com/">Ruby Pulse</a></strong> – Free Ruby-related podcasts.</p> + + <p><strong><a href="http://ruby-kickstart.com/">Ruby Kickstart</a></strong> – Hours of free screencast to teach you how to program in Ruby, with loads of free material, quizzes, and goodies.</p> +<nav class="navigation"><a href="/ruby-compendium/book/books.html">← Books</a> | <a href="/ruby-compendium/book/index.html">Contents</a> | <a href="/ruby-compendium/book/rubyists.html">Notable Rubyists →</a></nav>
A
contents/ruby-compendium/book/resources.html
@@ -0,0 +1,9 @@
+----- +title: "Ruby Compendium – Resources" +content-type: page +----- +<nav class="navigation"><a href="/ruby-compendium/book/gem-tips.html">← What you can use for...</a> | <a href="/ruby-compendium/book/index.html">Contents</a> | <a href="/ruby-compendium/book/web-sites.html">Web Sites →</a></nav> +<p>There are a lot of resources out there to help you get started or stay up-to-date with Ruby. The Ruby community is active and supportive, as long as you ask nicely.</p> +<p>The following section contains a small set of hand-picked web sites, books and podcasts which you should definitely have a look at. For even more community resources, check out the <a href="http://www.ruby-lang.org/en/community/">Community Page</a> on the Official Ruby Web Site.</p> + +<nav class="navigation"><a href="/ruby-compendium/book/gem-tips.html">← What you can use for...</a> | <a href="/ruby-compendium/book/index.html">Contents</a> | <a href="/ruby-compendium/book/web-sites.html">Web Sites →</a></nav>
A
contents/ruby-compendium/book/rubyists.html
@@ -0,0 +1,271 @@
+----- +title: "Ruby Compendium – Notable Rubyists" +content-type: page +----- +<nav class="navigation"><a href="/ruby-compendium/book/podcasts.html">← Podcasts and Screencasts</a> | <a href="/ruby-compendium/book/index.html">Contents</a> | </nav> + + + <section class="section"> +<span style="padding-top: 20px;display: block;"> + +<a id="chad"></a><strong><a href="http://chadfowler.com/">Chad Fowler</a></strong> – <a href="http://twitter.com/chadfowler">@chadfowler</a> + </span> + <div style="margin-left: 30px;"> + +Pragmatic Programmer, published author, Ruby core committer. + </div> + +</section> + + <section class="section"> +<span style="padding-top: 20px;display: block;"> + +<a id="matz"></a><strong><a href="http://www.rubyist.net/~matz/">Yukihiro Matsumoto</a></strong> – <a href="http://twitter.com/yukihiro_matz">@yukihiro_matz</a> + </span> + <div style="margin-left: 30px;"> + +The creator of the Ruby Programming Language. + </div> + +</section> + + <section class="section"> +<span style="padding-top: 20px;display: block;"> + +<a id="davethomas"></a><strong><a href="http://pragdave.pragprog.com/">Dave Thomas</a></strong> – <a href="http://twitter.com/pragdave">@pragdave</a> + </span> + <div style="margin-left: 30px;"> + +Pragmatic Programmer, published author, Ruby core committer. + </div> + +</section> + + <section class="section"> +<span style="padding-top: 20px;display: block;"> + +<a id="dhh"></a><strong><a href="http://www.loudthinking.com/">David Heinemeier Hansson</a></strong> – <a href="http://twitter.com/dhh">@dhh</a> + </span> + <div style="margin-left: 30px;"> + +Creator of the Ruby on Rails framework. + </div> + +</section> + + <section class="section"> +<span style="padding-top: 20px;display: block;"> + +<a id="_why"></a><strong><a href="http://viewsourcecode.org/why/">why the lucky stiff</a></strong> – <a href="http://twitter.com/_why">@_why</a> + </span> + <div style="margin-left: 30px;"> + +Semi-legendary, prolific Ruby developer, core committer, blogger, book author. Mysteriously disappeared in August 2009. + </div> + +</section> + + <section class="section"> +<span style="padding-top: 20px;display: block;"> + +<a id="wycatz"></a><strong><a href="http://www.yehudakatz.com/">Yehuda Katz</a></strong> – <a href="http://twitter.com/wycatz">@wycatz</a> + </span> + <div style="margin-left: 30px;"> + +Rails core committer, lead developer of the Merb project. + </div> + +</section> + + <section class="section"> +<span style="padding-top: 20px;display: block;"> + +<a id="jm"></a><strong><a href="http://www.jeremymcanally.com/">Jeremy McAnally</a></strong> – <a href="http://twitter.com/jm">@jm</a> + </span> + <div style="margin-left: 30px;"> + +Published author, blogger. Known for the Little Humble Ruby Book. + </div> + +</section> + + <section class="section"> +<span style="padding-top: 20px;display: block;"> + +<a id="obie"></a><strong><a href="http://obiefernandez.com/">Obie Fernandez</a></strong> – <a href="http://twitter.com/obie">@obie</a> + </span> + <div style="margin-left: 30px;"> + +Published author, editor of Addison-Wesley's Professional Ruby Series, enterpreneur. + </div> + +</section> + + <section class="section"> +<span style="padding-top: 20px;display: block;"> + +<a id="olabini"></a><strong><a href="http://olabini.com/blog">Ola Bini</a></strong> – <a href="http://twitter.com/olabini">@olabini</a> + </span> + <div style="margin-left: 30px;"> + +JRuby core committer, published author, blogger. + </div> + +</section> + + <section class="section"> +<span style="padding-top: 20px;display: block;"> + +<a id="peterc"></a><strong><a href="http://peterc.org/">Peter Cooper</a></strong> – <a href="http://twitter.com/peterc">@peterc</a> + </span> + <div style="margin-left: 30px;"> + +Published author, blogger, enterpreneaur. Creator of Ruby Inside. + </div> + +</section> + + <section class="section"> +<span style="padding-top: 20px;display: block;"> + +<a id="acangiano"></a><strong><a href="http://antoniocangiano.com/">Antonio Cangiano</a></strong> – <a href="http://twitter.com/acangiano">@acangiano</a> + </span> + <div style="margin-left: 30px;"> + +Technical Evangelist, blogger, published author, and Ruby's unofficial benchmarker. + </div> + +</section> + + <section class="section"> +<span style="padding-top: 20px;display: block;"> + +<a id="andyhunt"></a><strong><a href="http://blog.toolshed.com/">Andy Hunt</a></strong> – <a href="http://twitter.com/pragmaticandy">@pragmaticandy</a> + </span> + <div style="margin-left: 30px;"> + +Pragmatic Programmer, published author. + </div> + +</section> + + <section class="section"> +<span style="padding-top: 20px;display: block;"> + +<a id="satish"></a><strong><a href="http://satishtalim.com/">Satish Talim</a></strong> – <a href="http://twitter.com/indianguru">@indianguru</a> + </span> + <div style="margin-left: 30px;"> + +Creator of RubyLearning.com, one of the best resources for learning Ruby. + </div> + +</section> + + <section class="section"> +<span style="padding-top: 20px;display: block;"> + +<a id="dablack"></a><strong><a href="http://dablog.rubypal.com/">David A. Black</a></strong> – <a href="http://twitter.com/david_a_black">@david_a_black</a> + </span> + <div style="margin-left: 30px;"> + +Ruby core committer, published. + </div> + +</section> + + <section class="section"> +<span style="padding-top: 20px;display: block;"> + +<a id="jeg2"></a><strong><a href="http://blog.grayproductions.net/">James Edward Gray II</a></strong> – <a href="http://twitter.com/jeg2">@jeg2</a> + </span> + <div style="margin-left: 30px;"> + +Ruby core committer, conference organizer, published author and blogger. + </div> + +</section> + + <section class="section"> +<span style="padding-top: 20px;display: block;"> + +<a id="luislavena"></a><strong><a href="http://blog.mmediasys.com/">Luis Lavena</a></strong> – <a href="http://twitter.com/luislavena">@luislavena</a> + </span> + <div style="margin-left: 30px;"> + +Ruby core committer, maintainer of RubyInstaller for Windows. + </div> + +</section> + + <section class="section"> +<span style="padding-top: 20px;display: block;"> + +<a id="tenderlove"></a><strong><a href="http://tenderlovemaking.com/">Aaron Petterson</a></strong> – <a href="http://twitter.com/tenderlove">@tenderlove</a> + </span> + <div style="margin-left: 30px;"> + +Ruby core committer, blogger. + </div> + +</section> + + <section class="section"> +<span style="padding-top: 20px;display: block;"> + +<a id="greggpollack"></a><strong><a href="http://envylabs.com/">Gregg Pollack</a></strong> – <a href="http://twitter.com/greggpollack">@greggpollack</a> + </span> + <div style="margin-left: 30px;"> + +Founder of EnvyLabs, creator of many Ruby and Rails-related podcasts, including Ruby5. + </div> + +</section> + + <section class="section"> +<span style="padding-top: 20px;display: block;"> + +<a id="danbenjamin"></a><strong><a href="http://danbenjamin.com/">Dan Benjamin</a></strong> – <a href="http://twitter.com/danbenjamin">@danbenjamin</a> + </span> + <div style="margin-left: 30px;"> + +Founder of 5by5 Studios, creator and host of The Ruby Show podcast. + </div> + +</section> + + <section class="section"> +<span style="padding-top: 20px;display: block;"> + +<a id="jseifer"></a><strong><a href="http://jasonseifer.com/">Jason Seifer</a></strong> – <a href="http://twitter.com/jseifer">@jseifer</a> + </span> + <div style="margin-left: 30px;"> + +Co-host of The Ruby Show podcast. + </div> + +</section> + + <section class="section"> +<span style="padding-top: 20px;display: block;"> + +<a id="wayneeseguin"></a><strong><a href="http://beginrescueend.com/">Wayne E. Seguin</a></strong> – <a href="http://twitter.com/wayneeseguin">@wayneeseguin</a> + </span> + <div style="margin-left: 30px;"> + +Creator of Ruby Version Manager (RVM). + </div> + +</section> + + <section class="section"> +<span style="padding-top: 20px;display: block;"> + +<a id="steveklabnik"></a><strong><a href="http://www.steveklabnik.com/">Steve Klabnik</a></strong> – <a href="http://twitter.com/steveklabnik">@steveklabnik</a> + </span> + <div style="margin-left: 30px;"> + +Maintainer of Hackety Hack, creator of rstat.us. + </div> + +</section> +<nav class="navigation"><a href="/ruby-compendium/book/podcasts.html">← Podcasts and Screencasts</a> | <a href="/ruby-compendium/book/index.html">Contents</a> | </nav>
A
contents/ruby-compendium/book/syntax.html
@@ -0,0 +1,79 @@
+----- +title: "Ruby Compendium – Syntax" +content-type: page +----- +<nav class="navigation"><a href="/ruby-compendium/book/implementations.html">← Versions and Implementations</a> | <a href="/ruby-compendium/book/index.html">Contents</a> | <a href="/ruby-compendium/book/core-stdlib.html">The Core and the Standard Library →</a></nav> +<p> +Teaching you how to program in Ruby goes beyond the scope of this book, however, this section will show you at least what Ruby code looks like. If you know another programming language already, some things may already be familiar to you. If you don't, hopefully the following code will not appear too intimidating. +</p> +<div class="CodeRay"> + <div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span><span class="comment"># This is a comment and will not be executed </span> +<span class="line-numbers"> <a href="#n2" name="n2">2</a></span><span class="comment"># by the Ruby interpreter.</span> +<span class="line-numbers"> <a href="#n3" name="n3">3</a></span><span class="comment">#</span> +<span class="line-numbers"> <a href="#n4" name="n4">4</a></span><span class="comment"># This is not the usual 'Hello World' example, so </span> +<span class="line-numbers"> <a href="#n5" name="n5">5</a></span><span class="comment"># don't worry if you don't understand everything. </span> +<span class="line-numbers"> <a href="#n6" name="n6">6</a></span><span class="comment"># This example is meant to give you a general feeling </span> +<span class="line-numbers"> <a href="#n7" name="n7">7</a></span><span class="comment"># of what it is like to write Ruby programs.</span> +<span class="line-numbers"> <a href="#n8" name="n8">8</a></span> +<span class="line-numbers"> <a href="#n9" name="n9">9</a></span>require <span class="string"><span class="delimiter">'</span><span class="content">pathname</span><span class="delimiter">'</span></span> <span class="comment"># Here we're requiring an external library</span> +<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span> <span class="comment"># which is part of the Ruby Standard Library.</span> +<span class="line-numbers"><a href="#n11" name="n11">11</a></span> +<span class="line-numbers"><a href="#n12" name="n12">12</a></span><span class="keyword">class</span> <span class="class">FilePrinter</span> +<span class="line-numbers"><a href="#n13" name="n13">13</a></span> +<span class="line-numbers"><a href="#n14" name="n14">14</a></span> <span class="comment"># Constructor method</span> +<span class="line-numbers"><a href="#n15" name="n15">15</a></span> <span class="keyword">def</span> <span class="function">initialize</span>(path) +<span class="line-numbers"><a href="#n16" name="n16">16</a></span> <span class="comment"># This method expects a valid path, however Ruby is dynamically-typed</span> +<span class="line-numbers"><a href="#n17" name="n17">17</a></span> <span class="comment"># so anything can be passed to this method.</span> +<span class="line-numbers"><a href="#n18" name="n18">18</a></span> <span class="comment"># To check that the input value is valid, just check if if it behaves</span> +<span class="line-numbers"><a href="#n19" name="n19">19</a></span> <span class="comment"># like a path. This is called 'duck typing'.</span> +<span class="line-numbers"><strong><a href="#n20" name="n20">20</a></strong></span> raise <span class="constant">RuntimeError</span>, <span class="string"><span class="delimiter">"</span><span class="content">Invalid path: </span><span class="inline"><span class="inline-delimiter">#{</span>path<span class="inline-delimiter">}</span></span><span class="delimiter">"</span></span> <span class="keyword">unless</span> path.respond_to? <span class="symbol">:basename</span> +<span class="line-numbers"><a href="#n21" name="n21">21</a></span> <span class="instance-variable">@path</span> = path +<span class="line-numbers"><a href="#n22" name="n22">22</a></span> <span class="instance-variable">@name</span> = <span class="instance-variable">@path</span>.basename +<span class="line-numbers"><a href="#n23" name="n23">23</a></span> <span class="keyword">end</span> +<span class="line-numbers"><a href="#n24" name="n24">24</a></span> +<span class="line-numbers"><a href="#n25" name="n25">25</a></span> <span class="keyword">def</span> <span class="function">show</span> +<span class="line-numbers"><a href="#n26" name="n26">26</a></span> <span class="comment"># Ruby objects and expressions can be interpolated in strings</span> +<span class="line-numbers"><a href="#n27" name="n27">27</a></span> puts <span class="string"><span class="delimiter">"</span><span class="content"> </span><span class="escape">#</span><span class="instance-variable">@name</span><span class="content"> -- </span><span class="inline"><span class="inline-delimiter">#{</span><span class="instance-variable">@path</span>.stat.size<span class="inline-delimiter">}</span></span><span class="content"> bytes</span><span class="delimiter">"</span></span> +<span class="line-numbers"><a href="#n28" name="n28">28</a></span> <span class="keyword">end</span> +<span class="line-numbers"><a href="#n29" name="n29">29</a></span> +<span class="line-numbers"><strong><a href="#n30" name="n30">30</a></strong></span><span class="keyword">end</span> +<span class="line-numbers"><a href="#n31" name="n31">31</a></span> +<span class="line-numbers"><a href="#n32" name="n32">32</a></span><span class="keyword">class</span> <span class="class">DirPrinter</span> < <span class="constant">FilePrinter</span> <span class="comment"># Definition of a child class</span> +<span class="line-numbers"><a href="#n33" name="n33">33</a></span> +<span class="line-numbers"><a href="#n34" name="n34">34</a></span> <span class="keyword">def</span> <span class="function">initialize</span>(path) +<span class="line-numbers"><a href="#n35" name="n35">35</a></span> <span class="keyword">super</span> <span class="comment"># Call to the parent's constructur</span> +<span class="line-numbers"><a href="#n36" name="n36">36</a></span> <span class="instance-variable">@children</span> = <span class="instance-variable">@path</span>.children +<span class="line-numbers"><a href="#n37" name="n37">37</a></span> <span class="keyword">end</span> +<span class="line-numbers"><a href="#n38" name="n38">38</a></span> +<span class="line-numbers"><a href="#n39" name="n39">39</a></span> <span class="keyword">def</span> <span class="function">show</span> +<span class="line-numbers"><strong><a href="#n40" name="n40">40</a></strong></span> puts <span class="string"><span class="delimiter">"</span><span class="content"> </span><span class="escape">#</span><span class="instance-variable">@name</span><span class="content">/ -- </span><span class="inline"><span class="inline-delimiter">#{</span><span class="instance-variable">@children</span>.length<span class="inline-delimiter">}</span></span><span class="content"> item(s)</span><span class="delimiter">"</span></span> +<span class="line-numbers"><a href="#n41" name="n41">41</a></span> <span class="keyword">end</span> +<span class="line-numbers"><a href="#n42" name="n42">42</a></span> +<span class="line-numbers"><a href="#n43" name="n43">43</a></span><span class="keyword">end</span> +<span class="line-numbers"><a href="#n44" name="n44">44</a></span> +<span class="line-numbers"><a href="#n45" name="n45">45</a></span><span class="comment"># No parenthesis are required unless needed!</span> +<span class="line-numbers"><a href="#n46" name="n46">46</a></span>pwd = <span class="constant">Pathname</span>.new <span class="constant">Dir</span>.pwd +<span class="line-numbers"><a href="#n47" name="n47">47</a></span> +<span class="line-numbers"><a href="#n48" name="n48">48</a></span>puts <span class="string"><span class="delimiter">"</span><span class="content">Current Directory: </span><span class="inline"><span class="inline-delimiter">#{</span>pwd<span class="inline-delimiter">}</span></span><span class="delimiter">"</span></span> +<span class="line-numbers"><a href="#n49" name="n49">49</a></span> +<span class="line-numbers"><strong><a href="#n50" name="n50">50</a></strong></span><span class="comment"># Get the children items of the current directory, </span> +<span class="line-numbers"><a href="#n51" name="n51">51</a></span><span class="comment"># select only directories, </span> +<span class="line-numbers"><a href="#n52" name="n52">52</a></span><span class="comment"># sort them alphabetically,</span> +<span class="line-numbers"><a href="#n53" name="n53">53</a></span><span class="comment"># and for each one of them...</span> +<span class="line-numbers"><a href="#n54" name="n54">54</a></span>pwd.children.select{|i| i.directory? }.sort.each <span class="keyword">do</span> |item| +<span class="line-numbers"><a href="#n55" name="n55">55</a></span> <span class="comment"># Call the show method, printing the </span> +<span class="line-numbers"><a href="#n56" name="n56">56</a></span> <span class="comment"># directory name and the number of child items</span> +<span class="line-numbers"><a href="#n57" name="n57">57</a></span> <span class="constant">DirPrinter</span>.new(item).show +<span class="line-numbers"><a href="#n58" name="n58">58</a></span><span class="keyword">end</span> +<span class="line-numbers"><a href="#n59" name="n59">59</a></span> +<span class="line-numbers"><strong><a href="#n60" name="n60">60</a></strong></span>pwd.children.select{|i| !i.directory? }.sort.each <span class="keyword">do</span> |item| +<span class="line-numbers"><a href="#n61" name="n61">61</a></span> <span class="constant">FilePrinter</span>.new(item).show +<span class="line-numbers"><a href="#n62" name="n62">62</a></span><span class="keyword">end</span></pre></div> +</div> + +<aside class="box"> +<div class="box-title">Trying out Ruby...</div> +If your hands are itching to try writing Ruby code, but you don't want to install it just yet, head over to <a href="http://tryruby.org/">Try Ruby!</a>, a unique way to try the language right in your browser. Or, if you already installed Ruby, follow the <a href="http://www.ruby-lang.org/en/documentation/quickstart/">Ruby in 20 minutes</a> tutorial, using Interactive RuBy (IRB). + +</aside> +<nav class="navigation"><a href="/ruby-compendium/book/implementations.html">← Versions and Implementations</a> | <a href="/ruby-compendium/book/index.html">Contents</a> | <a href="/ruby-compendium/book/core-stdlib.html">The Core and the Standard Library →</a></nav>
A
contents/ruby-compendium/book/ten-good-things.html
@@ -0,0 +1,23 @@
+----- +title: "Ruby Compendium – 10 Good Things about Ruby" +content-type: page +----- +<nav class="navigation"><a href="/ruby-compendium/book/language.html">← Quick Tour</a> | <a href="/ruby-compendium/book/index.html">Contents</a> | <a href="/ruby-compendium/book/implementations.html">Versions and Implementations →</a></nav> +<ol> + <li>It’s free and open source.</li> + <li>It’s high-level, no need to worry about memory allocation or similar.</li> + <li>It’s fully cross platform, or at least most of its <a href="/ruby-compendium/book/implementations.html#implementations">implementations</a> are.</li> + <li>It’s elegant. Really, Ruby <a href="/ruby-compendium/book/syntax.html#syntax">syntax</a> is truly beautiful, with no semicolons or braces, generally.</li> + <li>It has a large <a href="/ruby-compendium/book/core-stdlib.html#core-stdlib">core and Standard Library</a>.</li> + <li>It has over 1300 user-contributed <a href="/ruby-compendium/book/gems.html#gems">libraries</a> for almost anything you can think of.</li> + <li>It is multi-paradigm and offers many advanced language <a href="/ruby-compendium/book/features.html#features">features</a>.</li> + <li>It has a friendly and supportive community and plenty of useful <a href="/ruby-compendium/book/resources.html#resources">resources</a>.</li> + <li>There are loads of <a href="/ruby-compendium/book/web-sites.html#websites">web sites</a> about it and free online learning material.</li> + <li>A lot of <a href="/ruby-compendium/book/books.html#books">books</a> have been written about it.</li> +</ol> +<aside class="box"> +<div class="box-title">If you want to know more...</div> +For general information on Ruby and more introductory material, head over to the <a href="http://www.ruby-lang.org/">Official Ruby Web Site</a>, in particular to the <a href="http://www.ruby-lang.org/en/documentation/ruby-from-other-languages/">Ruby from Other Languages</a> articles, if you are already familiar with C, C++, Java, PHP, Perl, or Python. + +</aside> +<nav class="navigation"><a href="/ruby-compendium/book/language.html">← Quick Tour</a> | <a href="/ruby-compendium/book/index.html">Contents</a> | <a href="/ruby-compendium/book/implementations.html">Versions and Implementations →</a></nav>
A
contents/ruby-compendium/book/web-sites.html
@@ -0,0 +1,31 @@
+----- +title: "Ruby Compendium – Web Sites" +content-type: page +----- +<nav class="navigation"><a href="/ruby-compendium/book/resources.html">← Resources</a> | <a href="/ruby-compendium/book/index.html">Contents</a> | <a href="/ruby-compendium/book/books.html">Books →</a></nav> + + <p><strong><a href="http://www.ruby-lang.org/">Ruby-Lang.org</a></strong> – The official Ruby web site, completely maintained by members of the Ruby community and available in several languages.</p> + + <p><strong><a href="https://rubygems.org/">RubyGems.org</a></strong> – The home of all Ruby gems.</p> + + <p><strong><a href="http://rubykoans.com/">Ruby Koans</a></strong> – Learn Ruby (and testing) through Koans. Probably the coolest way to learn Ruby right now.</p> + + <p><strong><a href="http://rubylearning.com/">Ruby Learning</a></strong> – Ruby guru <a href="/ruby-compendium/book/rubyists.html#satish">Satish Talim</a>’s web site about learning the Ruby language. It contains tutorials, study notes, and even <a href="http://rubylearning.org/class/">online classes</a>.</p> + + <p><strong><a href="http://rubycorner.com/">Ruby Corner</a></strong> – The most comprehensive Ruby blog aggregator.</p> + + <p><strong><a href="http://www.rubyinside.com/">Ruby Inside</a></strong> – <em>The</em> Ruby blog, by <a href="/ruby-compendium/book/rubyists.html#peterc">Peter Cooper</a>.</p> + + <p><strong><a href="http://www.ruby-forum.com/">Ruby Forum</a></strong> – A mirror of the most important Ruby-related mailing lists.</p> + + <p><strong><a href="http://rubydoc.info/">RubyDoc.info</a></strong> – Your one-stop resource for reference documentation. Everything from Ruby core, Standard Library, gems, and even Github-hosted Ruby projects.</p> + + <p><strong><a href="http://www.rubyflow.com/">RubyFlow</a></strong> – Community-powered link blog. Created by <a href="/ruby-compendium/book/rubyists.html#peterc">Peter Cooper</a></p> + + <p><strong><a href="http://ruby-toolbox.com/">The Ruby Toolbox</a></strong> – A collection of ruby resources and libraries, organized by category and popularity.</p> + + <p><strong><a href="http://rubycommitters.org/">RubyCommitters.org</a></strong> – List of all the Ruby core committers. Created by <a href="/ruby-compendium/book/rubyists.html#tenderlove">Aaron Petterson</a>.</p> + + <p><strong><a href="http://rubylang.info/">RubyLang.info</a></strong> – <em>“RubyLang.info is a community driven web site, dedicated to helping both new and experienced Ruby developers.”</em></p> + +<nav class="navigation"><a href="/ruby-compendium/book/resources.html">← Resources</a> | <a href="/ruby-compendium/book/index.html">Contents</a> | <a href="/ruby-compendium/book/books.html">Books →</a></nav>
M
rules.min
→
rules.min
@@ -6,6 +6,7 @@ () =ARCHIVES
() =ARCHIVE-COLUMNS () =ARTICLES () =HOME +() =PROJECTS ; Populates the ARCHIVE-COLUMNS array containing tags in groups@@ -92,6 +93,18 @@ dup "page" swap mustache %contents
output-fwrite ) :create-archives-page +; Create the Projects page +( + () + "projects/index" %id + "projects.html" %path + ".html" %ext + "Projects" %title + "page" %content-type + PROJECTS (?active) sort %projects + dup "projects" swap mustache %contents + output-fwrite +) :create-projects-page ; Create the Tags page. ;(@@ -254,6 +267,7 @@ content /id :id
content /content-type :ct "page" :tpl (ct "article" ==) ("article" @tpl) when + (ct "project" ==) ("project" @tpl) when (id "index" ==) (content #HOME "home" @tpl) when "" :page "" :contents@@ -312,6 +326,7 @@ contents (
=content content /id :id content + (/content-type "project" ==) (content PROJECTS append #PROJECTS content) when process-tags process-timestamp process-content@@ -325,6 +340,7 @@ ;TAGS 'create-tag-page foreach
; Generate archive pages ;prepare-archive-data +create-projects-page create-archives-page ;ARCHIVES 'create-archive-page foreach
M
templates/_head.mustache
→
templates/_head.mustache
@@ -13,7 +13,7 @@ <link rel="stylesheet" type="text/css" href="/styles/entypo.css" />
<link rel="stylesheet" type="text/css" href="/styles/fonts.css" /> <link rel="stylesheet" type="text/css" href="/styles/spectre.min.css" /> <link rel="stylesheet" type="text/css" href="/styles/spectre-exp.min.css" /> - <link rel="stylesheet" type="text/css" href="/styles/github.css" /> + <link rel="stylesheet" type="text/css" href="/styles/atom-one-light.css" /> <link rel="stylesheet" type="text/css" href="/styles/style.css" /> <script src="/js/es6-shim.min.js" type="text/javascript"></script> <script src="/js/axios.min.js" type="text/javascript"></script>
A
templates/_project.mustache
@@ -0,0 +1,37 @@
+ <div class="card project-card"> + <div class="card-header"> + <div class="card-title h5"> + {{#active}} + <small class="label label-success">active</small> + {{/active}} + {{#inactive}} + <small class="label label-warning">inactive</small> + {{/inactive}} + {{title}} + <span class="badge" data-badge="v{{version}}"></span> + </div> + </div> + <div class="card-body"> + {{summary}} + </div> + <div class="card-footer"> + {{#home}} + <a href="{{home}}" class="btn btn-link"> + info + </a> + {{/home}} + {{#github}} + <a href="https://github.com/h3rald/{{github}}" class="btn btn-link"> + source + </a> + <a href="https://github.com/h3rald/{{github}}/issues" class="btn btn-link"> + issues + </a> + {{/github}} + {{#docs}} + <a href="{{docs}}" class="btn btn-link"> + docs + </a> + {{/docs}} + </div> + </div>
M
templates/article.mustache
→
templates/article.mustache
@@ -17,5 +17,10 @@ </article>
</main> {{> _footer}} </div> + <script src="/js/highlight.pack.js"></script> + <script> + hljs.configure({tabReplace: ' '}); + hljs.initHighlightingOnLoad(); + </script> </body> </html>
A
templates/project.mustache
@@ -0,0 +1,46 @@
+<!DOCTYPE html> +<html lang="en"> + {{> _head}} + <body> + <div id="wrap"> + {{> _header}} + <main class="container"> + <article class="{{content-type}}"> + <div class="row"> + {{> _page_header}} + </div> + {{#github}} + <div class="card project-card"> + <div class="card-footer"> + <a href="https://github.com/h3rald/{{github}}" class="btn btn-link"> + source + </a> + <a href="https://github.com/h3rald/{{github}}/issues" class="btn btn-link"> + issues + </a> + {{#docs}} + <a href="{{docs}}" class="btn btn-link"> + docs + </a> + {{/docs}} + <br/> + <img src="https://img.shields.io/github/release/h3rald/{{github}}/all.svg" style="vertical-align: middle;"/> + <img src="https://img.shields.io/github/license/h3rald/{{github}}.svg" style="vertical-align: middle;"/> + <img src="https://img.shields.io/github/last-commit/h3rald/{{github}}.svg" style="vertical-align: middle;"/> + </div> + </div> + {{/github}} + <div class="body-text" class="hyphenate"> + {{{contents}}} + </div> + </article> + </main> + {{> _footer}} + </div> + <script src="/js/highlight.pack.js"></script> + <script> + hljs.configure({tabReplace: ' '}); + hljs.initHighlightingOnLoad(); + </script> + </body> +</html>
A
templates/projects.mustache
@@ -0,0 +1,22 @@
+<!DOCTYPE html> +<html lang="en"> + {{> _head}} + <body> + <div id="wrap"> + {{> _header}} + <main id="main" class="container"> + <article class="projects"> + <div class="row"> + {{> _page_header}} + </div> + <div class="body-text hyphenate"> + {{#projects}} + {{> _project}} + {{/projects}} + </div> + </article> + </main> + {{> _footer}} + </div> + </body> +</html>