all repos — h3rald @ 6b243ded05a7593922d198634c681075de1c12e2

The sources of https://h3rald.com

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&#8217;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">&quot;</span><span class="content">Create output for h3rald.com integration</span><span class="delimiter">&quot;</span></span>
<span class="line-numbers"> <a href="#n3" name="n3">3</a></span>  task <span class="symbol">:h3rald</span> =&gt; [<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">&quot;</span><span class="content">glyph/book</span><span class="delimiter">&quot;</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">&quot;</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">&quot;</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">&quot;</span><span class="content">glyph.textile</span><span class="delimiter">&quot;</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>