all repos — h3rald @ ebd415d3ecd14483862eb49dde0569e14ffef979

The sources of https://h3rald.com

contents/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
-----
title: "Glyph – Topics"
content-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>