Fixing glyph book.
h3rald h3rald@h3rald.com
Fri, 23 Feb 2024 12:05:16 +0100
60 files changed,
5541 insertions(+),
4071 deletions(-)
jump to
M
assets/styles/style.css
→
assets/styles/style.css
@@ -369,16 +369,17 @@ box-shadow: 0 16px 16px -16px #000;
margin-top: -30px; } -.main-content { - margin-top: 20px; +footer, +.main-content, +.sidebar { max-width: 1024px; margin: auto; } -footer { - max-width: 1024px; - margin: auto; +.main-content { + margin-top: 20px; } + @media screen and (max-width: 385px) { .header-counter {@@ -647,6 +648,12 @@ width: 16px;
height: 16px; border: none; vertical-align: text-top; +} + +/* Used only in Glyph Book */ + +.line-numbers { + display: none; } /* iPad Fix */
M
contents/glyph/book/acknowledgements.html
→
contents/glyph/book/acknowledgements.html
@@ -1,10 +1,12 @@
----- -title: "Glyph – Acknowledgements" +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> +<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> +<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>@@ -14,5 +16,6 @@ <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> + +<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>
M
contents/glyph/book/changelog.html
→
contents/glyph/book/changelog.html
@@ -1,891 +1,1017 @@
----- -title: "Glyph – Changelog" +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> +<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> + <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> -</section> + + <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> + <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> -</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> + + <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> -</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> + <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> - <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> + <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> + -</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> + <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> - <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> + <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> -</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> + <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> -</section> + <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_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> + <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> -</section> + </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> + <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> -</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> + </table> -</section> + </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> + <header> + <h1 id="h_310" class="toc">1 Bug Fixed</h1> + </header> + <table> + <tr> + <th>ID</th> + <th>Description</th> + </tr> -</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> + + <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> - <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> + <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_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 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_322" class="toc">v0.1.0 – April 8th 2010</h1></header> -Initial release. + <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> +<nav class="navigation"><a href="/glyph/book/config/output.html">← <code>output.*</code></a> | <a + href="/glyph/book/index.html">Contents</a> | </nav>
M
contents/glyph/book/compiling/compiling.html
→
contents/glyph/book/compiling/compiling.html
@@ -1,82 +1,130 @@
----- -title: "Glyph – Compiling a project" +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> +<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> + <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> + <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> + <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> + <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> + <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> + <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). + <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> + </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> + <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> + <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> + <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. + <span class="note-title">Tip</span>Giving the command <code> glyph compile -f ebooks </code> will generate both mobi + and epub files. -</aside> + </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> + <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> + <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. + <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> + </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> +<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>
M
contents/glyph/book/compiling/lite_mode.html
→
contents/glyph/book/compiling/lite_mode.html
@@ -1,25 +1,45 @@
----- -title: "Glyph – Compiling single Glyph files" +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> +<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> +<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> +<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>
M
contents/glyph/book/compiling/programmatic_usage.html
→
contents/glyph/book/compiling/programmatic_usage.html
@@ -1,99 +1,120 @@
----- -title: "Glyph – Using Glyph programmatically" +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> +<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> + <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> +<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 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> +<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>
M
contents/glyph/book/config/document.html
→
contents/glyph/book/config/document.html
@@ -1,23 +1,26 @@
----- -title: "Glyph – <code>document.*</code>" +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. +<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> + <tr> + <th>Name</th> + <th>Description</th> + <th>Default</th> + </tr> + <tr> <td> -<code>document.author</code> <a id="s_document_author"></a> -</td> + <code>document.author</code> <a id="s_document_author"></a> + </td> <td> -<p>The author of the document.</p> -</td> + <p>The author of the document.</p> + </td> <td> <code> ""@@ -26,11 +29,11 @@ </td>
</tr> <tr> <td> -<code>document.cover</code> <a id="s_document_cover"></a> -</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> + <p>The image used as the document cover (used only for e-book generation).</p> + </td> <td> <code> false@@ -39,11 +42,13 @@ </td>
</tr> <tr> <td> -<code>document.draft</code> <a id="s_document_draft"></a> -</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> + <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@@ -52,11 +57,11 @@ </td>
</tr> <tr> <td> -<code>document.filename</code> <a id="s_document_filename"></a> -</td> + <code>document.filename</code> <a id="s_document_filename"></a> + </td> <td> -<p>The name of the output file.</p> -</td> + <p>The name of the output file.</p> + </td> <td> <code> ""@@ -65,20 +70,20 @@ </td>
</tr> <tr> <td> -<code>document.output</code> <a id="s_document_output"></a> -</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> + <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"@@ -87,11 +92,11 @@ </td>
</tr> <tr> <td> -<code>document.revision</code> <a id="s_document_revision"></a> -</td> + <code>document.revision</code> <a id="s_document_revision"></a> + </td> <td> -<p>The document’s revision.</p> -</td> + <p>The document’s revision.</p> + </td> <td> <code> ""@@ -100,11 +105,13 @@ </td>
</tr> <tr> <td> -<code>document.source</code> <a id="s_document_source"></a> -</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> + <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"@@ -113,16 +120,17 @@ </td>
</tr> <tr> <td> -<code>document.styles</code> <a id="s_document_styles"></a> -</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> + <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"@@ -131,11 +139,12 @@ </td>
</tr> <tr> <td> -<code>document.subtitle</code> <a id="s_document_subtitle"></a> -</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> + <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> ""@@ -144,11 +153,12 @@ </td>
</tr> <tr> <td> -<code>document.title</code> <a id="s_document_title"></a> -</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> + <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> ""@@ -157,16 +167,18 @@ </td>
</tr> <tr> <td> -<code>document.isbn</code> <a id="s_document_isbn"></a> -</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> + <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> +</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>
M
contents/glyph/book/config/filters.html
→
contents/glyph/book/config/filters.html
@@ -1,23 +1,26 @@
----- -title: "Glyph – <code>filters.*</code>" +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> +<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> + <tr> + <th>Name</th> + <th>Description</th> + <th>Default</th> + </tr> + <tr> <td> -<code>filters.coderay.*</code> <a id="s_filters_coderay_"></a> -</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> + <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@@ -26,11 +29,11 @@ </td>
</tr> <tr> <td> -<code>filters.highlighter</code> <a id="s_filters_highlighter"></a> -</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> + <p>The current highlighter to use. It can be set to <code>coderay</code> or <code>ultraviolet</code></p> + </td> <td> <code> "coderay"@@ -39,18 +42,20 @@ </td>
</tr> <tr> <td> -<code>filters.markdown.converter</code> <a id="s_filters_markdown_converter"></a> -</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> + <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"@@ -59,11 +64,14 @@ </td>
</tr> <tr> <td> -<code>filters.redcloth.restrictions</code> <a id="s_filters_redcloth_restrictions"></a> -</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> + <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> []@@ -72,11 +80,12 @@ </td>
</tr> <tr> <td> -<code>filters.ultraviolet.line_numbers</code> <a id="s_filters_ultraviolet_line_numbers"></a> -</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> + <p>Whether the <a href="http://ultraviolet.rubyforge.org/">Ultraviolet</a> highlighter should display line + numbers or not.</p> + </td> <td> <code> true@@ -85,16 +94,18 @@ </td>
</tr> <tr> <td> -<code>filters.ultraviolet.theme</code> <a id="s_filters_ultraviolet_theme"></a> -</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> + <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> +</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>
M
contents/glyph/book/config/options.html
→
contents/glyph/book/config/options.html
@@ -1,5 +1,5 @@
----- -title: "Glyph – <code>options.*</code>" +title: "Glyph - <code>options.*</code>" content-type: page ----- <nav class="navigation"><a href="/glyph/book/config/filters.html">← <code>filters.*</code></a> | <a
M
contents/glyph/book/config/output.html
→
contents/glyph/book/config/output.html
@@ -1,8 +1,9 @@
----- -title: "Glyph – <code>output.*</code>" +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> +<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>@@ -17,626 +18,663 @@ 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> + <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> + </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> + <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> + </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> + <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> + </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> + </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> + <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> + </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> + <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> + </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> + <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> + </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> + <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> + </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> + <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> + </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> + </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> + <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> + </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> + <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> + </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> + <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> + </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> + <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> + </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> + </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> + <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> + </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> + <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> + </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> + <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> + </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> + <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> + </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> + <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> + </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> + <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> + </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> + <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> + </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> + <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> + </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> + <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> + </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> + <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> + </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> + <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> + </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> + <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> + </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> + <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> + </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> + <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> + </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> + <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> + </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> + <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> + </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> + <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> + </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> + <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> + </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> + <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> + </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> + <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> + </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> + <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> + </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> + <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> + </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> + <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> + </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> + <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> + </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> + <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> + </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> + <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> + </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> + <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> + </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> +<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>
M
contents/glyph/book/extending/bookmarks_headers.html
→
contents/glyph/book/extending/bookmarks_headers.html
@@ -1,21 +1,32 @@
----- -title: "Glyph – Bookmarks and Headers" +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> +<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> +<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> +<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> +<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>
M
contents/glyph/book/extending/command.html
→
contents/glyph/book/extending/command.html
@@ -1,16 +1,26 @@
----- -title: "Glyph – Defining Custom Commands" +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> +<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> + <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> + <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|@@ -20,12 +30,15 @@ <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> +<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> + <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 + <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>=====================================@@ -43,15 +56,20 @@ <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> +<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 + <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> +<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> +<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>
M
contents/glyph/book/extending/commands_tasks.html
→
contents/glyph/book/extending/commands_tasks.html
@@ -1,43 +1,62 @@
----- -title: "Glyph – Defining Custom Commands and Tasks" +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> +<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> + <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> + <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> + <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> + </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> +<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>
M
contents/glyph/book/extending/further_reading.html
→
contents/glyph/book/extending/further_reading.html
@@ -1,9 +1,12 @@
----- -title: "Glyph – Further Reading" +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> +<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>@@ -12,4 +15,6 @@ <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> +<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>
M
contents/glyph/book/extending/internals.html
→
contents/glyph/book/extending/internals.html
@@ -1,33 +1,55 @@
----- -title: "Glyph – A quick look at Glyph's internals" +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> +<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> + <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] +<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> +<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>} + <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>}@@ -50,39 +72,52 @@ <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> +<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‡‡‡‡‡ + <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> +<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, + <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> +<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> +<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>
M
contents/glyph/book/extending/interpreting.html
→
contents/glyph/book/extending/interpreting.html
@@ -1,34 +1,49 @@
----- -title: "Glyph – Interpreting Glyph Code" +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> +<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> +<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> +<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> +<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> +<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> + <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> +<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>]@@ -51,41 +66,63 @@ <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> +<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> + <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> +<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> +<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| + <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> +<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> + <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> +<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>
M
contents/glyph/book/extending/layouts.html
→
contents/glyph/book/extending/layouts.html
@@ -1,19 +1,28 @@
----- -title: "Glyph – Layouts" +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> +<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> +<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> + <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[ + <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> ]@@ -27,22 +36,27 @@ <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> +<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> + <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> + <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[ + <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> ]@@ -57,25 +71,35 @@ <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> +<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> + <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> + <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. + <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> + </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> +<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>
M
contents/glyph/book/extending/macro_def.html
→
contents/glyph/book/extending/macro_def.html
@@ -1,115 +1,151 @@
----- -title: "Glyph – Defining Custom Macros" +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> +<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> + <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> +<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> +<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> +<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> + <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> +<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> +<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| + <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> +<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| + <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> +<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. + 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> +<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>
M
contents/glyph/book/extending/output_format.html
→
contents/glyph/book/extending/output_format.html
@@ -1,5 +1,5 @@
----- -title: "Glyph – Custom Output Formats" +title: "Glyph - Custom Output Formats" content-type: page ----- <nav class="navigation"><a href="/glyph/book/extending/task.html">← Defining Custom Tasks</a> | <a@@ -7,12 +7,14 @@ 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> + 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> + <a href="http://www.h3rald.com">H3RALD.com</a> website. +</p> <section class="section"> <header> <h1 id="h_105" class="toc">Output Configuration</h1>
M
contents/glyph/book/extending/params_attrs.html
→
contents/glyph/book/extending/params_attrs.html
@@ -1,27 +1,43 @@
----- -title: "Glyph – Parameters and Attributes" +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> +<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> +<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>@@ -29,22 +45,26 @@ <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> +<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[ + <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> +<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> + <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>@@ -53,22 +73,33 @@ <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> +<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. + <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> + </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> +<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>
M
contents/glyph/book/extending/placeholders.html
→
contents/glyph/book/extending/placeholders.html
@@ -1,12 +1,19 @@
----- -title: "Glyph – Using Placeholders" +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> +<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>@@ -35,9 +42,17 @@ <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> +<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> +<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>
M
contents/glyph/book/extending/task.html
→
contents/glyph/book/extending/task.html
@@ -1,23 +1,33 @@
----- -title: "Glyph – Defining Custom Tasks" +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> +<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> + <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> + <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>@@ -36,11 +46,17 @@ <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> +<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> + <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> +<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>
M
contents/glyph/book/extending/validators.html
→
contents/glyph/book/extending/validators.html
@@ -1,20 +1,36 @@
----- -title: "Glyph – Using Validators" +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> +<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> +<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>
M
contents/glyph/book/getting_started/configuration.html
→
contents/glyph/book/getting_started/configuration.html
@@ -1,5 +1,5 @@
----- -title: "Glyph – Project Configuration" +title: "Glyph - Project Configuration" content-type: page ----- <nav class="navigation"><a href="/glyph/book/getting_started/structure.html">← Document Structure</a> | <a@@ -11,7 +11,8 @@ <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> + <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>@@ -31,7 +32,8 @@ 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> + 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">
M
contents/glyph/book/getting_started/create_project.html
→
contents/glyph/book/getting_started/create_project.html
@@ -1,29 +1,36 @@
----- -title: "Glyph – Creating your first Glyph Project" +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> +<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> + <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>@@ -35,7 +42,11 @@ <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> + <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> +<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>
M
contents/glyph/book/getting_started/structure.html
→
contents/glyph/book/getting_started/structure.html
@@ -1,13 +1,18 @@
----- -title: "Glyph – Document Structure" +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> +<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> +<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[ +<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[@@ -35,14 +40,25 @@ <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> +<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> +<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>@@ -50,8 +66,17 @@ <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> + <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> +<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>
M
contents/glyph/book/introduction.html
→
contents/glyph/book/introduction.html
@@ -1,5 +1,5 @@
----- -title: "Glyph – Introduction" +title: "Glyph - Introduction" content-type: page ----- <nav class="navigation"> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/license.html">License@@ -26,7 +26,8 @@ <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> + <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@@ -158,7 +159,8 @@ <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> + <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>@@ -171,7 +173,8 @@ <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> + 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>
M
contents/glyph/book/license.html
→
contents/glyph/book/license.html
@@ -1,23 +1,28 @@
----- -title: "Glyph – License" +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> +<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> + 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> + 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. + 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> +<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>
M
contents/glyph/book/macros/macros_block.html
→
contents/glyph/book/macros/macros_block.html
@@ -1,320 +1,391 @@
----- -title: "Glyph – Block Macros" +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> +<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?| + + <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> +<span class="line-numbers"><a href="#n3" name="n3">3</a></span>]</pre> + </div> + </div> -</section> - + </section> - <section class="section"> -<header><h1 id="h_218" class="notoc">Parameters</h1></header> -<table style="width:100%;"> + + <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> + <tr> + <td>0</td> + <td>The box title.</td> + </tr> + + + <tr> + <td>1</td> + <td>The box text.</td> + </tr> </table> + + </section> </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="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[ + <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> +<span class="line-numbers"><a href="#n5" name="n5">5</a></span>]</pre> + </div> + </div> + + </section> -</section> - - <section class="section"> -<header><h1 id="h_221" class="notoc">Parameters</h1></header> -<table style="width:100%;"> + <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> + <tr> + <td>0</td> + <td>The code to be formatted.</td> + </tr> </table> -</section> - + </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 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="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[ + <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> +<span class="line-numbers"><a href="#n4" name="n4">4</a></span>]</pre> + </div> + </div> + + </section> -</section> - - <section class="section"> -<header><h1 id="h_225" class="notoc">Parameters</h1></header> -<table style="width:100%;"> + <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> + <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> - <section class="section"> -<header><h1 id="h_226" class="notoc">Attributes</h1></header> -<table style="width:100%;"> + + <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> + <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> - + - - <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="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[ + <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> +<span class="line-numbers"><a href="#n5" name="n5">5</a></span>]</pre> + </div> + </div> -</section> - + </section> + - <section class="section"> -<header><h1 id="h_229" class="notoc">Parameters</h1></header> -<table style="width:100%;"> + <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> + <tr> + <td>0</td> + <td>The name of the image file (relative to the <code>images/</code> folder).</td> + </tr> </table> -</section> - + </section> + - <section class="section"> -<header><h1 id="h_230" class="notoc">Attributes</h1></header> -<table style="width:100%;"> + <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> + <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> - + + - - <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="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%;"> + <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> + <tr> + <td>0</td> + <td>The ID of the current topic.</td> + </tr> </table> + </section> + </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="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%;"> + <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> + <tr> + <td>0</td> + <td>The text of the note.</td> + </tr> </table> -</section> + </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="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%;"> + + <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> + <tr> + <td>0</td> + <td>An alternative content for the _pubdate_ @div@.</td> + </tr> </table> -</section> + </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> + + +<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> + <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 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> + +<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> + <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> + +<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>
M
contents/glyph/book/macros/macros_core.html
→
contents/glyph/book/macros/macros_core.html
@@ -1,862 +1,1005 @@
----- -title: "Glyph – Core Macros" +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> +<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 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="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%;"> + + + <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> + <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> - - - <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> + + +<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> + <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%;"> + <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> + <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> - - - <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="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%;"> + + + <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> + <tr> + <td>0</td> + <td>The name of the attribute to retrieve.</td> + </tr> </table> -</section> + </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="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%;"> + <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> + <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> - + - - <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="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%;"> + <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> + <tr> + <td>0</td> + <td>The contents to comment out</td> + </tr> </table> -</section> - + </section> -<section class="section"> -<header><h1 id="h_151" class="notoc">Remarks</h1></header> -<p>Macros are not expanded within comments.</p> -</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="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%;"> + <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> + <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> + + + <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 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> - - - <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="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%;"> + <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> + <tr> + <td>0</td> + <td>The full name of a configuration setting.</td> + </tr> </table> -</section> + </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="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%;"> + + + <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> + <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> -<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 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="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> - <section class="section"> -<header><h1 id="h_161" class="notoc">Parameters</h1></header> -<table style="width:100%;"> + <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> + <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> - - - <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="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%;"> + <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> + <tr> + <td>0</td> + <td>The contents to escape.</td> + </tr> </table> -</section> + </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="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%;"> + + + <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> + <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> - - - <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="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%;"> + + + <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> + <tr> + <td>0</td> + <td>The ID of the fragment.</td> + </tr> </table> -</section> + </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%;"> +<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> + <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> - - - - - <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> + + + + +<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> + <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%;"> + <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> + <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> - - + - - <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="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%;"> + <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> + <tr> + <td>0</td> + <td>The file to include.</td> + </tr> </table> -</section> - + </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 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="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[ + <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> +<span class="line-numbers"><a href="#n8" name="n8">8</a></span>]</pre> + </div> + </div> -</section> - + </section> - <section class="section"> -<header><h1 id="h_177" class="notoc">Parameters</h1></header> -<table style="width:100%;"> + + <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> + <tr> + <td>0</td> + <td>Any content.</td> + </tr> </table> -</section> + </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="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%;"> + + + <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> + <tr> + <td>0</td> + <td>The file to embed, relative to the Glyph project folder.</td> + </tr> </table> -</section> + </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="m_lt" class="toc"><code>lt</code></h1> + </header> + <p>Returns <em>true</em> if the first parameter is lt the second one.</p> - <section class="section"> -<header><h1 id="h_181" class="notoc">Parameters</h1></header> -<table style="width:100%;"> + <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> + <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> - - - - - <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%;"> +<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> + <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> - - - - <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="m_match" class="toc"><code>match</code></h1> + </header> + <p>Checks a string against a regular expression.</p> - <section class="section"> -<header><h1 id="h_185" class="notoc">Parameters</h1></header> -<table style="width:100%;"> + <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> + <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> -<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 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="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%;"> + + + <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> + <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="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> + <header> + <h1 id="m_multiply" class="toc"><code>multiply</code></h1> + </header> + <p>Multiplies two or more integers together.</p> -</section> + <p><strong>Example:</strong> <code>add[3|5|9]</code></p> </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> +<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> + <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%;"> + <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> + <tr> + <td>0</td> + <td>The expression to negate</td> + </tr> </table> -</section> + </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="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%;"> + + + <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> + <tr> + <td>0, ...</td> + <td>a valid output target.</td> + </tr> </table> -</section> + </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> + +<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> + <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%;"> + <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> + <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> - - - <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| +<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[@@ -864,199 +1007,235 @@ <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> +<span class="line-numbers"> <a href="#n9" name="n9">9</a></span>factorial[5]</pre> + </div> + </div> -</section> - + </section> - <section class="section"> -<header><h1 id="h_199" class="notoc">Parameters</h1></header> -<table style="width:100%;"> + + <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> + <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> + + + <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 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> - + - - <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> +<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> + <examples> + %[Time.now] + %[Glyph::VERSION] + </examples> - <section class="section"> -<header><h1 id="h_202" class="notoc">Parameters</h1></header> -<table style="width:100%;"> + <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> + <tr> + <td>0</td> + <td>The Ruby code to evaluate.</td> + </tr> </table> -</section> - + </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 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> - + - - <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> +<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> + <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="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%;"> + + + <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> + <tr> + <td>0</td> + <td>The ID of the snippet to retrieve.</td> + </tr> </table> -</section> + </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="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%;"> + <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> + <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="h_209" class="notoc">Remarks</h1></header> -<p>The new snippet can only be used <em>after</em> its declaration.</p> + <header> + <h1 id="m_subtract" class="toc"><code>subtract</code></h1> + </header> + <p>Subtracts two or more integers together.</p> -</section> + <p><strong>Example:</strong> <code>add[10|5|2]</code></p> </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 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_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="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[ + <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]|@@ -1064,34 +1243,39 @@ <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> +<span class="line-numbers"> <a href="#n9" name="n9">9</a></span>]</pre> + </div> + </div> -</section> - + </section> - <section class="section"> -<header><h1 id="h_214" class="notoc">Parameters</h1></header> -<table style="width:100%;"> + + <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> + <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> -</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> +<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>
M
contents/glyph/book/macros/macros_filters.html
→
contents/glyph/book/macros/macros_filters.html
@@ -1,243 +1,299 @@
----- -title: "Glyph – Filter Macros" +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> +<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="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%;"> + <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> + <tr> + <td>0</td> + <td>The Markdown text to filter.</td> + </tr> </table> -</section> + </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[ + +<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> +<span class="line-numbers"><a href="#n5" name="n5">5</a></span>]</pre> + </div> + </div> -</section> - + </section> + - <section class="section"> -<header><h1 id="h_255" class="notoc">Parameters</h1></header> -<table style="width:100%;"> + <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> + <tr> + <td>0</td> + <td>The text of the section</td> + </tr> </table> -</section> - + </section> + - <section class="section"> -<header><h1 id="h_256" class="notoc">Attributes</h1></header> -<table style="width:100%;"> + <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> + <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> - - - <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="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%;"> + + + <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> + <tr> + <td>0</td> + <td>The Textile text to filter.</td> + </tr> </table> -</section> + </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="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[ + <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> +<span class="line-numbers"><a href="#n5" name="n5">5</a></span>]</pre> + </div> + </div> + + </section> -</section> - - <section class="section"> -<header><h1 id="h_261" class="notoc">Parameters</h1></header> -<table style="width:100%;"> + <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> + <tr> + <td>0</td> + <td>The text of the section</td> + </tr> </table> -</section> - + </section> - <section class="section"> -<header><h1 id="h_262" class="notoc">Attributes</h1></header> -<table style="width:100%;"> + + <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> + <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> - + - - <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="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| + <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> +<span class="line-numbers"><a href="#n5" name="n5">5</a></span>]</pre> + </div> + </div> + + </section> -</section> - - <section class="section"> -<header><h1 id="h_265" class="notoc">Parameters</h1></header> -<table style="width:100%;"> + <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> + <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> -</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> +<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>
M
contents/glyph/book/macros/macros_inline.html
→
contents/glyph/book/macros/macros_inline.html
@@ -1,141 +1,169 @@
----- -title: "Glyph – Inline Macros" +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> +<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%;"> + <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> + <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> - + - - <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="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%;"> + <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> + <tr> + <td>0</td> + <td>The text of the comment.</td> + </tr> </table> -</section> + </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="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%;"> + + + <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> + <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> - + - - <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="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%;"> + <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> + <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> - + - - <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 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> + +<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>
M
contents/glyph/book/macros/macros_structure.html
→
contents/glyph/book/macros/macros_structure.html
@@ -1,371 +1,431 @@
----- -title: "Glyph – Structure Macros" +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> +<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>head</code> - <ul> - <li><code>style[default.css]</code></li> - </ul></li> - <li><code>body</code> - <ul> - <li><code>halftitlepage</code> + <li><code>document</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> + <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%;"> + <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> + <tr> + <td>0</td> + <td>The article contents.</td> + </tr> </table> -</section> - + </section> + - <section class="section"> -<header><h1 id="h_269" class="notoc">Attributes</h1></header> -<table style="width:100%;"> + <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> + <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> - - - <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> + + +<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>head</code> - <ul> - <li><code>style[default.css]</code></li> - </ul></li> - <li><code>body</code> - <ul> - <li><code>titlepage</code> + <li><code>document</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> + <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%;"> + <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> + <tr> + <td>0</td> + <td>The article contents.</td> + </tr> </table> -</section> - + </section> + - <section class="section"> -<header><h1 id="h_272" class="notoc">Attributes</h1></header> -<table style="width:100%;"> + <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> + <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> - - - <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="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%;"> + + + <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> + <tr> + <td>0</td> + <td>The document contents.</td> + </tr> </table> -</section> + </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="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%;"> + <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> + <tr> + <td>0</td> + <td>The head contents.</td> + </tr> </table> -</section> + </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[ +<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> +<span class="line-numbers"><a href="#n5" name="n5">5</a></span>]</pre> + </div> + </div> + + </section> -</section> - - <section class="section"> -<header><h1 id="h_279" class="notoc">Parameters</h1></header> -<table style="width:100%;"> + <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> + <tr> + <td>0</td> + <td>The text of the section</td> + </tr> </table> -</section> - + </section> + - <section class="section"> -<header><h1 id="h_280" class="notoc">Attributes</h1></header> -<table style="width:100%;"> + <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> + <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> - + - - <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> + +<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> + <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%;"> + <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> + <tr> + <td>0</td> + <td>The stylesheet file to embed.</td> + </tr> </table> -</section> + </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> + + +<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> + <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%;"> + <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> + <tr> + <td>0</td> + <td>The maximum header depth of the TOC <em>(optional)</em>.</td> + </tr> </table> -</section> + </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> + +<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>
M
contents/glyph/book/ref_commands.html
→
contents/glyph/book/ref_commands.html
@@ -1,5 +1,5 @@
----- -title: "Glyph – Command Reference" +title: "Glyph - Command Reference" content-type: page ----- <nav class="navigation"><a href="/glyph/book/troubleshooting/errors_macro.html">← Macro Errors</a> | <a
M
contents/glyph/book/stats/bookmarks.html
→
contents/glyph/book/stats/bookmarks.html
@@ -1,14 +1,19 @@
----- -title: "Glyph – Bookmark Statistics" +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> +<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 +<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@@ -30,38 +35,50 @@ <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> +<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 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> - <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) +<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> +<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 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> </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> +<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>
M
contents/glyph/book/stats/links.html
→
contents/glyph/book/stats/links.html
@@ -1,14 +1,20 @@
----- -title: "Glyph – Link Statistics" +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> +<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 +<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@@ -39,24 +45,32 @@ <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> +<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 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> - <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_/ +<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@@ -93,16 +107,21 @@ <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> +<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 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> </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> +<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>
M
contents/glyph/book/stats/macros.html
→
contents/glyph/book/stats/macros.html
@@ -1,14 +1,20 @@
----- -title: "Glyph – Macro Statistics" +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> +<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 +<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@@ -40,26 +46,36 @@ <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> +<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 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> - <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' +<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)@@ -74,18 +90,27 @@ <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> +<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 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> </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> +<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>
M
contents/glyph/book/stats/snippets.html
→
contents/glyph/book/stats/snippets.html
@@ -1,14 +1,20 @@
----- -title: "Glyph – Snippet Statistics" +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> +<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 +<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@@ -23,24 +29,32 @@ <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> +<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 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> - <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' +<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@@ -53,16 +67,21 @@ <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> +<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 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> </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> +<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>
M
contents/glyph/book/stats/stats.html
→
contents/glyph/book/stats/stats.html
@@ -1,13 +1,18 @@
----- -title: "Glyph – Using the stats command" +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> +<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>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 + <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]@@ -22,7 +27,8 @@ <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> +<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>@@ -35,7 +41,8 @@ <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>===================================== + <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>@@ -65,7 +72,10 @@ <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> +<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> +<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>
M
contents/glyph/book/text_editing/attribute_intro.html
→
contents/glyph/book/text_editing/attribute_intro.html
@@ -1,32 +1,44 @@
----- -title: "Glyph – Macro attributes" +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> +<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 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> +<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> + <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 +<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> +<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. +<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> +<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>
M
contents/glyph/book/text_editing/code.html
→
contents/glyph/book/text_editing/code.html
@@ -1,24 +1,36 @@
----- -title: "Glyph – Source Code" +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> +<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) +<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> +<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| +<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|@@ -27,28 +39,37 @@ <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> +<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) +<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> +<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 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> +<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>
M
contents/glyph/book/text_editing/conditionals.html
→
contents/glyph/book/text_editing/conditionals.html
@@ -1,10 +1,16 @@
----- -title: "Glyph – Conditional Macros" +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> +<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>@@ -12,38 +18,55 @@ <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]| +<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> +<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> +<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[ +<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> +<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> +<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> +<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>
M
contents/glyph/book/text_editing/esc_quot.html
→
contents/glyph/book/text_editing/esc_quot.html
@@ -1,14 +1,29 @@
----- -title: "Glyph – Escaping and Quoting" +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> +<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[= +<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]@@ -18,79 +33,85 @@ <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> +<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 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> +<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> +<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>
M
contents/glyph/book/text_editing/evaluation.html
→
contents/glyph/book/text_editing/evaluation.html
@@ -1,70 +1,112 @@
----- -title: "Glyph – Simple Programming and Code Evaluation" +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> +<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> +<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> + <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| + <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> +<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> + <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 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[ +<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> +<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> +<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> +<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>
M
contents/glyph/book/text_editing/glyph_files.html
→
contents/glyph/book/text_editing/glyph_files.html
@@ -1,9 +1,17 @@
----- -title: "Glyph – <code>.glyph</code> files" +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> +<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>
M
contents/glyph/book/text_editing/images.html
→
contents/glyph/book/text_editing/images.html
@@ -1,41 +1,56 @@
----- -title: "Glyph – Images and Figures" +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> +<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 +<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> +<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> + <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> +<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> + <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 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> +<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>
M
contents/glyph/book/text_editing/inclusions.html
→
contents/glyph/book/text_editing/inclusions.html
@@ -1,45 +1,77 @@
----- -title: "Glyph – Content Reuse" +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> +<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="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> + <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> - <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] +<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> +<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> + <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. +</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> + +<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>
M
contents/glyph/book/text_editing/links.html
→
contents/glyph/book/text_editing/links.html
@@ -1,66 +1,94 @@
----- -title: "Glyph – Links and Bookmarks" +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> +<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> + <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]. +<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> +<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> + <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> +<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 + <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> +<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> +<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>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> + <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[ +<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> +<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. +<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> +<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>
M
contents/glyph/book/text_editing/macro_composition.html
→
contents/glyph/book/text_editing/macro_composition.html
@@ -1,32 +1,47 @@
----- -title: "Glyph – Macro Composition" +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> +<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>?[ + <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> +<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>?[ + <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> +<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> +<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> + <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> +<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>
M
contents/glyph/book/text_editing/macro_intro.html
→
contents/glyph/book/text_editing/macro_intro.html
@@ -1,20 +1,34 @@
----- -title: "Glyph – Introducing Glyph Macros" +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> +<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> +<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> + <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> +<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> +<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>
M
contents/glyph/book/text_editing/raw_html.html
→
contents/glyph/book/text_editing/raw_html.html
@@ -1,39 +1,52 @@
----- -title: "Glyph – Textile or Markdown" +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>). +<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[ +<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> +<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> + <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> +<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 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> +<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>
M
contents/glyph/book/text_editing/section_aliases.html
→
contents/glyph/book/text_editing/section_aliases.html
@@ -1,46 +1,64 @@
----- -title: "Glyph – Section Aliases" +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> +<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> + <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> + <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> + <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> + <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 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> +<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>
M
contents/glyph/book/text_editing/sections.html
→
contents/glyph/book/text_editing/sections.html
@@ -1,64 +1,98 @@
----- -title: "Glyph – Sections and Headers" +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> +<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> +<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[ +<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> +<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> +<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> +<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> +<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[ +<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> +<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[ + <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> +<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 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> + </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> +<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>
M
contents/glyph/book/text_editing/stylesheets.html
→
contents/glyph/book/text_editing/stylesheets.html
@@ -1,53 +1,72 @@
----- -title: "Glyph – Adding Stylesheets" +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> +<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. +<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> +<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> + </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> +<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>
M
contents/glyph/book/text_editing/topics.html
→
contents/glyph/book/text_editing/topics.html
@@ -1,38 +1,58 @@
----- -title: "Glyph – Topics" +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> +<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>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> +<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[ + <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> +<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> +<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[ + <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> +<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> +<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 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> + <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> +<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>
M
contents/glyph/book/text_editing/xml_fallback.html
→
contents/glyph/book/text_editing/xml_fallback.html
@@ -1,18 +1,26 @@
----- -title: "Glyph – XML Fallback" +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] +<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]@@ -35,14 +43,16 @@ <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> +<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> + <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>@@ -65,38 +75,51 @@ <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> +<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. +<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> +<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> +<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>
M
contents/glyph/book/troubleshooting/errors_command.html
→
contents/glyph/book/troubleshooting/errors_command.html
@@ -1,76 +1,93 @@
----- -title: "Glyph – Command Errors" +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: +<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> + </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>
M
contents/glyph/book/troubleshooting/errors_generic.html
→
contents/glyph/book/troubleshooting/errors_generic.html
@@ -1,5 +1,5 @@
----- -title: "Glyph – Generic Errors" +title: "Glyph - Generic Errors" content-type: page ----- <nav class="navigation"><a href="/glyph/book/extending/command.html">← Defining Custom Commands</a> | <a@@ -43,7 +43,8 @@ <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> + <code>prince</code> and <code>wkhtmltopdf</code>. + </td> </tr>@@ -63,7 +64,8 @@
<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> + <code>Hash</code>. + </td> </tr>
M
contents/glyph/book/troubleshooting/errors_macro.html
→
contents/glyph/book/troubleshooting/errors_macro.html
@@ -1,5 +1,5 @@
----- -title: "Glyph – Macro Errors" +title: "Glyph - Macro Errors" content-type: page ----- <nav class="navigation"><a href="/glyph/book/troubleshooting/errors_command.html">← Command Errors</a> | <a@@ -16,7 +16,8 @@ <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> + 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>@@ -171,14 +172,16 @@ <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> + <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> + <code>.sass</code> file was passed as parameter but the Haml gem is not installed. + </td> </tr>
M
contents/glyph/book/troubleshooting/errors_parser.html
→
contents/glyph/book/troubleshooting/errors_parser.html
@@ -1,60 +1,64 @@
----- -title: "Glyph – Parsing Errors" +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> +<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>