content/glyph/book/text_editing/topics.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 |
----- permalink: topics title: Glyph – Topics type: page ----- <nav class="navigation"><a href="/glyph/book/text_editing/section_aliases.html">← Section Aliases</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/links.html">Links and Bookmarks →</a></nav> <p>Sections can also be used to create <em>topics</em>. In a technical writing context, the term topic identifies a single page of an online help (e.g. a Compiled <span class="caps">HTML</span> file, or <span class="caps">CHM</span>). Topics should generally be:</p> <ul> <li>self-contained, in the sense that they should make sense on their own, ideally without the need to be read in sequence</li> <li>be used for either <em>concepts</em>, <em>tasks</em> or <em>references</em></li> <li>be divided into meaningful sections like <em>Introduction</em>, <em>Procedure</em>, <em>Result</em></li> </ul> <p>Glyph does not formally enforce the correctness of topic composition and usage, but it does enable authors to create them as a sort of external sections. Consider the following Glyph code:</p> <div class="CodeRay"> <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>section[ <span class="line-numbers"><a href="#n2" name="n2">2</a></span> @title[My First Topic] <span class="line-numbers"><a href="#n3" name="n3">3</a></span> @id[first_topic] <span class="line-numbers"><a href="#n4" name="n4">4</a></span> @src[test/first_topic.glyph] <span class="line-numbers"><a href="#n5" name="n5">5</a></span>]</pre></div> </div> <p>This is an ordinary section with a title and an explicit ID, but it has no contents. Instead, its <code>@src</code> attribute references an external file. If you are generating a single-file document, like a standalone <span class="caps">HTML</span> file or a <span class="caps">PDF</span> file, the code snippet above is exactly the same as the following:</p> <div class="CodeRay"> <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>section[ <span class="line-numbers"><a href="#n2" name="n2">2</a></span> @title[My First Topic] <span class="line-numbers"><a href="#n3" name="n3">3</a></span> @id[first_topic] <span class="line-numbers"><a href="#n4" name="n4">4</a></span> include[test/first_topic.glyph] <span class="line-numbers"><a href="#n5" name="n5">5</a></span>]</pre></div> </div> <p>On the other hand, if you are planning on producing a document comprised of multiple files (see <a href="/glyph/book/compiling/compiling.html#web_output">Web/Web5 Output</a>), the <code>@src</code> attribute tells Glyph to create a <em>topic</em> for the section. In this case:</p> <ul> <li>The <code>@title</code> attribute must be specified and is used as the topic title</li> <li>The body of the topic is constituted by the contents of the file referenced by the <code>@src</code> attribute.</li> <li>The topic file is rendered according to a specific <a href="/glyph/book/extending/layouts.html#layouts">layout</a>.</li> <li>The location of the topic is the same as the location of the included file, mirrored in the output folder.</li> <li>Glyph takes care of changing the file extensions and resolving links automatically, regardless of the output target.</li> </ul> <nav class="navigation"><a href="/glyph/book/text_editing/section_aliases.html">← Section Aliases</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/links.html">Links and Bookmarks →</a></nav> |