contents/glyph/book/extending/output_format.html
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 |
-----
title: "Glyph - Custom Output Formats"
content-type: page
-----
<nav class="navigation"><a href="/glyph/book/extending/task.html">← Defining Custom Tasks</a> | <a
href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/command.html">Defining Custom
Commands →</a></nav>
<p>As shown in <a href="/glyph/book/extending/commands_tasks.html#cmd_tasks_arch">How Commands and Tasks work</a>, the
<a href="/glyph/book/ref_commands.html#c_compile"><code>compile</code></a> command command calls specific tasks
defined in the <code>generate:</code> Rake namespace to generate output files in a particular format.
</p>
<p>More specifically, when a <code>--format</code> option is specified, the command looks for a task with the same name
within the <code>generate:</code> namespace. This makes adding new output formats to Glyph a fairly easy task,
without the need to specify custom commands or similar.</p>
<p>The following sections explain how the <code>h3rald</code> output format was created to integrate this book into the
<a href="http://www.h3rald.com">H3RALD.com</a> website.
</p>
<section class="section">
<header>
<h3 id="h_105" class="toc">Output Configuration</h1>
</header>
<p>The first step required to add a new output format to Glyph is extending Glyph’s configuration by adding
the appropriate output hash, as follows:</p>
<div class="CodeRay">
<div class="code">
<pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span><span class="symbol">:output</span>:
<span class="line-numbers"> <a href="#n2" name="n2">2</a></span> <span class="symbol">:h3rald</span>:
<span class="line-numbers"> <a href="#n3" name="n3">3</a></span> <span class="symbol">:multifile</span>: <span class="error">true</span>
<span class="line-numbers"> <a href="#n4" name="n4">4</a></span> <span class="symbol">:extension</span>: <span class="error">'.html'</span>
<span class="line-numbers"> <a href="#n5" name="n5">5</a></span> <span class="symbol">:filter_target</span>: <span class="error">'html'</span>
<span class="line-numbers"> <a href="#n6" name="n6">6</a></span> <span class="symbol">:base</span>: <span class="error">'/glyph/book/'</span>
<span class="line-numbers"> <a href="#n7" name="n7">7</a></span> <span class="symbol">:macro_dirs</span>: [<span class="error">'html', 'html5']</span>
<span class="line-numbers"> <a href="#n8" name="n8">8</a></span> <span class="symbol">:layout_dirs</span>: [<span class="error">'web5']</span>
<span class="line-numbers"> <a href="#n9" name="n9">9</a></span> <span class="symbol">:layouts</span>:
<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span> <span class="symbol">:topic</span>: <span class="error">bookpage</span>
<span class="line-numbers"><a href="#n11" name="n11">11</a></span> <span class="symbol">:index</span>: <span class="error">bookindex</span></pre>
</div>
</div>
<p>In particular, the following keys are mandatory:</p>
<ul>
<li>multifile</li>
<li>extension</li>
<li>filter_target</li>
<li>base</li>
<li>macro_dirs</li>
<li>layout_dirs</li>
</ul>
</section>
<section class="section">
<header>
<h3 id="h_106" class="toc">Creating a 'generate:h3rald' task</h1>
</header>
<p>The next (and final) step involves creating a custom <code>h3rald</code> task within the <code>generate:</code>
namespace. This task can be placed in any <code>.rake</code> file within the <code>lib/tasks</code> directory:
</p>
<div class="CodeRay">
<div class="code">
<pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span>namespace <span class="symbol">:generate</span> <span class="keyword">do</span>
<span class="line-numbers"> <a href="#n2" name="n2">2</a></span> desc <span class="string"><span class="delimiter">"</span><span class="content">Create output for h3rald.com integration</span><span class="delimiter">"</span></span>
<span class="line-numbers"> <a href="#n3" name="n3">3</a></span> task <span class="symbol">:h3rald</span> => [<span class="symbol">:web5</span>] <span class="keyword">do</span>
<span class="line-numbers"> <a href="#n4" name="n4">4</a></span> dir = <span class="constant">Glyph</span>::<span class="constant">PROJECT</span>/<span class="string"><span class="delimiter">'</span><span class="content">output/h3rald</span><span class="delimiter">'</span></span>
<span class="line-numbers"> <a href="#n5" name="n5">5</a></span> (dir/<span class="string"><span class="delimiter">"</span><span class="content">glyph/book</span><span class="delimiter">"</span></span>).mkpath
<span class="line-numbers"> <a href="#n6" name="n6">6</a></span> <span class="comment"># Copy files in subdir</span>
<span class="line-numbers"> <a href="#n7" name="n7">7</a></span> (dir).find <span class="keyword">do</span> |i|
<span class="line-numbers"> <a href="#n8" name="n8">8</a></span> <span class="keyword">if</span> i.file? <span class="keyword">then</span>
<span class="line-numbers"> <a href="#n9" name="n9">9</a></span> <span class="keyword">next</span> <span class="keyword">if</span> i.to_s.match(<span class="constant">Regexp</span>.escape(dir/<span class="string"><span class="delimiter">'</span><span class="content">glyph</span><span class="delimiter">'</span></span>))
<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span> dest = dir/<span class="string"><span class="delimiter">"</span><span class="content">glyph/book/</span><span class="inline"><span class="inline-delimiter">#{</span>i.relative_path_from(<span class="constant">Glyph</span>::<span class="constant">PROJECT</span>/dir)<span class="inline-delimiter">}</span></span><span class="delimiter">"</span></span>
<span class="line-numbers"><a href="#n11" name="n11">11</a></span> src = i.to_s
<span class="line-numbers"><a href="#n12" name="n12">12</a></span> <span class="constant">Pathname</span>.new(dest).parent.mkpath
<span class="line-numbers"><a href="#n13" name="n13">13</a></span> file_copy src, dest
<span class="line-numbers"><a href="#n14" name="n14">14</a></span> <span class="keyword">end</span>
<span class="line-numbers"><a href="#n15" name="n15">15</a></span> <span class="keyword">end</span>
<span class="line-numbers"><a href="#n16" name="n16">16</a></span> <span class="comment"># Remove files from output dir</span>
<span class="line-numbers"><a href="#n17" name="n17">17</a></span> dir.children.each <span class="keyword">do</span> |c|
<span class="line-numbers"><a href="#n18" name="n18">18</a></span> <span class="keyword">unless</span> c == dir/<span class="string"><span class="delimiter">'</span><span class="content">glyph</span><span class="delimiter">'</span></span> <span class="keyword">then</span>
<span class="line-numbers"><a href="#n19" name="n19">19</a></span> c.directory? ? c.rmtree : c.unlink
<span class="line-numbers"><strong><a href="#n20" name="n20">20</a></strong></span> <span class="keyword">end</span>
<span class="line-numbers"><a href="#n21" name="n21">21</a></span> <span class="keyword">end</span>
<span class="line-numbers"><a href="#n22" name="n22">22</a></span> (dir/<span class="string"><span class="delimiter">'</span><span class="content">glyph/book/images/glyph/glyph.eps</span><span class="delimiter">'</span></span>).unlink
<span class="line-numbers"><a href="#n23" name="n23">23</a></span> (dir/<span class="string"><span class="delimiter">'</span><span class="content">glyph/book/images/glyph/glyph.svg</span><span class="delimiter">'</span></span>).unlink
<span class="line-numbers"><a href="#n24" name="n24">24</a></span> <span class="comment"># Create project page</span>
<span class="line-numbers"><a href="#n25" name="n25">25</a></span> project = <span class="constant">Glyph</span>.filter <span class="string"><span class="delimiter">%{</span><span class="content">layout:project[</span></span>
<span class="line-numbers"><a href="#n26" name="n26">26</a></span><span class="string"><span class="content"> @contents[</span><span class="inline"><span class="inline-delimiter">#{</span>file_load(<span class="constant">Glyph</span>::<span class="constant">PROJECT</span>/<span class="string"><span class="delimiter">'</span><span class="content">text/introduction.glyph</span><span class="delimiter">'</span></span>)<span class="inline-delimiter">}</span></span><span class="content">]</span></span>
<span class="line-numbers"><a href="#n27" name="n27">27</a></span><span class="string"><span class="content"> ]</span><span class="delimiter">}</span></span>
<span class="line-numbers"><a href="#n28" name="n28">28</a></span> file_write dir/<span class="string"><span class="delimiter">"</span><span class="content">glyph.textile</span><span class="delimiter">"</span></span>, project
<span class="line-numbers"><a href="#n29" name="n29">29</a></span> <span class="keyword">end</span>
<span class="line-numbers"><strong><a href="#n30" name="n30">30</a></strong></span><span class="keyword">end</span></pre>
</div>
</div>
<p>In this case, this task does not actually renders files in a different format, it just moves the files generated
by the @generate:web5@ task in different subdirectories.</p>
<p>Additionally, it also generates the <a href="/glyph/">Glyph project page</a> from the book's introduction (note
the usage of a raw custom layout macro).</p>
</section>
<nav class="navigation"><a href="/glyph/book/extending/task.html">← Defining Custom Tasks</a> | <a
href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/command.html">Defining Custom
Commands →</a></nav>
|