all repos — h3rald @ bd721ea443718187ceb4c0cb94feaaa6e01ea70c

The sources of https://h3rald.com

content/glyph/book/text_editing/inclusions.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
-----
permalink: incl
title: Glyph – Content Reuse
type: page
-----
<nav class="navigation"><a href="/glyph/book/text_editing/stylesheets.html">← Adding Stylesheets</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/conditionals.html">Conditional Macros →</a></nav>
  <section class="section">
<header><h1 id="file-inclusions" class="toc">File inclusions</h1></header>
<p>If you&#8217;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> &rarr; <a href="/glyph/book/macros/macros_filters.html#m_textile"><code>textile</code></a> macro</li>
	<li><code>.markdown</code> or <code>.md</code> &rarr; <a href="/glyph/book/macros/macros_filters.html#m_markdown"><code>markdown</code></a> macro</li>
</ul>
<p>You can override this behavior by setting the <code>filters.by_file_extensions</code> configuration setting to <code>false</code>. If no extension is specified, <code>.glyph</code> is assumed.</p>
    <section class="section">
<header><h1 id="h_39" class="toc">Remarks</h1></header>
<ul>
	<li>The <a href="/glyph/book/macros/macros_core.html#m_include"><code>include</code></a> macro can also be used to include (and evaluate) ruby files (with a <code>.rb</code> extension). In this case, the ruby file must be placed within the <code>lib/</code> directory of the current project.</li>
	<li>The <a href="/glyph/book/macros/macros_core.html#m_load"><code>load</code></a> macro macro can be used to include the content of any file <em>without</em> performing any evaluation.</li>
</ul>

</section>

</section>
  <section class="section">
<header><h1 id="snippets" class="toc">Snippets</h1></header>
<p>While including the context of an entire file is definitely a useful feature for content reuse, sometimes it can be an overkill. What if, for example, you just want to reuse a short procedure or even a sentence or a single word? In this case, you may want to consider using a <em>snippet</em> instead.</p>
<p>Snippets can be defined using the <a href="/glyph/book/macros/macros_core.html#m_snippet_"><code>snippet:</code></a> macro (aliased by <code>&amp;:</code>) and called by using the <a href="/glyph/book/macros/macros_core.html#m_snippet"><code>snippet</code></a> macro (aliased by <code>&amp;</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>&amp;:[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 &amp;[markups].</pre></div>
</div>

    <p>You can use <code>&amp;[markups]</code> anywhere in your document instead of having to type "Textile or Markdown" every time. Additionally, later on you can change the value of the  <code>markups</code> to change it everywhere else in the document.</p>

</section> 
    <aside class="tip">
<span class="note-title">Tip</span>Snippets (or any other macro) can be nested within other snippets. Glyph takes care of checking if you nested snippets or macros mutually and warns you as necessary.

</aside>
  
<nav class="navigation"><a href="/glyph/book/text_editing/stylesheets.html">← Adding Stylesheets</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/conditionals.html">Conditional Macros →</a></nav>