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 — 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> <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> </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> |