all repos — h3rald @ b3442cd80d633f1412303de98a8301e8b8fd86c0

The sources of https://h3rald.com

contents/glyph/book/getting_started/structure.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
-----
title: "Glyph - Document Structure"
content-type: page
-----
<nav class="navigation"><a href="/glyph/book/getting_started/create_project.html">← Creating your first Glyph
		Project</a> | <a href="/glyph/book/index.html">Contents</a> | <a
		href="/glyph/book/getting_started/configuration.html">Project Configuration →</a></nav>

<p>Every Glyph project contains a <code>document.glyph</code> file that is typically used to define the document
	structure. The default <code>document.glyph</code> generated automatically when creating a new project is the
	following:</p>

<div class="CodeRay">
	<div class="code">
		<pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span>book[
<span class="line-numbers"> <a href="#n2" name="n2">2</a></span>  @frontmatter[
<span class="line-numbers"> <a href="#n3" name="n3">3</a></span>    toc[]
<span class="line-numbers"> <a href="#n4" name="n4">4</a></span>    preface[
<span class="line-numbers"> <a href="#n5" name="n5">5</a></span>      @title[Preface]
<span class="line-numbers"> <a href="#n6" name="n6">6</a></span>      todo[Write the preface]
<span class="line-numbers"> <a href="#n7" name="n7">7</a></span>      include[preface]
<span class="line-numbers"> <a href="#n8" name="n8">8</a></span>    ]
<span class="line-numbers"> <a href="#n9" name="n9">9</a></span>  ]
<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span>  @bodymatter[  
<span class="line-numbers"><a href="#n11" name="n11">11</a></span>    chapter[ 
<span class="line-numbers"><a href="#n12" name="n12">12</a></span>      @title[Chapter 1]
<span class="line-numbers"><a href="#n13" name="n13">13</a></span>      todo[Write chapter 1]
<span class="line-numbers"><a href="#n14" name="n14">14</a></span>      include[chapter_1]
<span class="line-numbers"><a href="#n15" name="n15">15</a></span>    ]
<span class="line-numbers"><a href="#n16" name="n16">16</a></span>    chapter[
<span class="line-numbers"><a href="#n17" name="n17">17</a></span>      @title[Chapter 2]
<span class="line-numbers"><a href="#n18" name="n18">18</a></span>      todo[Write chapter 2]
<span class="line-numbers"><a href="#n19" name="n19">19</a></span>      include[chapter_2]
<span class="line-numbers"><strong><a href="#n20" name="n20">20</a></strong></span>    ]
<span class="line-numbers"><a href="#n21" name="n21">21</a></span>  ]
<span class="line-numbers"><a href="#n22" name="n22">22</a></span>  @backmatter[
<span class="line-numbers"><a href="#n23" name="n23">23</a></span>    appendix[
<span class="line-numbers"><a href="#n24" name="n24">24</a></span>      @title[Appendix A]
<span class="line-numbers"><a href="#n25" name="n25">25</a></span>      todo[Write appendix A]
<span class="line-numbers"><a href="#n26" name="n26">26</a></span>      include[appendix_a]
<span class="line-numbers"><a href="#n27" name="n27">27</a></span>    ]
<span class="line-numbers"><a href="#n28" name="n28">28</a></span>  ]
<span class="line-numbers"><a href="#n29" name="n29">29</a></span>]</pre>
	</div>
</div>


<p>Even without knowing anything about Glyph Language, you can easily figure out that this file defines a document with
	a Table of Contents, a Preface some Chapters and an Appendix.</p>
<p>As you can see, Glyph wraps portions of text within square brackets preceded by an identifier. These identifiers are
	used for <em><a href="/glyph/book/text_editing/macro_intro.html#macro_intro">macros</a></em> and <em><a
			href="/glyph/book/text_editing/attribute_intro.html#attribute_intro">attributes</a></em>. The only syntactic
	difference between macros and attributes is that attributes are preceded by a <code>@</code>.</p>
<p>For now, think about a macro as something that performs a certain action and &#8212; generally &#8212; 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 &#8220;belong&#8221; to the macro they&#8217;re in, so in this case the <a
		href="/glyph/book/macros/macros_structure.html#m_book"><code>book</code></a> macro has the following attributes:
</p>
<ul>
	<li><code>@frontmatter</code></li>
	<li><code>@bodymatter</code></li>
	<li><code>@backmatter</code></li>
</ul>
<p>More specifically, in this <code>document.glyph</code> file:</p>
<ul>
	<li>The <a href="/glyph/book/macros/macros_structure.html#m_book"><code>book</code></a> macro wraps every other
		macro and is used to create the document header and default title page.</li>
	<li>Then, the <code>@frontmatter</code>, <code>@bodymatter</code>, and <code>@backmatter</code> attributes are used
		to divide the portions of your document according to the rules of <a
			href="http://en.wikipedia.org/wiki/Book_design">book design</a>. They are not mandatory, but they can be
		used, for example, to number your appendixes with letters instead of numbers and similar.</li>
	<li><code>preface</code>, <code>chapter</code>, <code>appendix</code> are just a way to wrap content in
		<code>&lt;div&gt;</code> tags, from an <span class="caps">HTML</span> point of view (or
		<code>&lt;section&gt;</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>