all repos — h3rald @ b3442cd80d633f1412303de98a8301e8b8fd86c0

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
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 
-----
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>