all repos — h3rald @ 2bf1f56e7be0afc6a290cab48a51d628e8ae3e61

The sources of https://h3rald.com

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
 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
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111
 112
 113
 114
 115
 116
 117
 118
 119
 120
 121
 122
 123
 124
 125
 126
 127
 128
 129
 130
 131
 132
 133
 134
 135
 136
 137
 138
 139
 
<!DOCTYPE html> 
<html lang="en"> 
	<head> 
    <title>Topics - Glyph</title> 
		
		<meta charset="utf-8" />
		<meta name="author" content="Fabio Cevasco" />
		<meta name="copyright" content="Fabio Cevasco" />
		<meta name="robots" content="all, follow" />
		<meta name="Revisit-After" content="2 Days" />
		<meta name="language" content="en" />
		<meta name="target_country" content="en-us" />
		<meta name="country" content="United States" />
                <meta name="readability-verification" content="XmaVzRjmcFL5Bb2Fu9TZVdDKzhA3apQdxexTB2rK"/>
		<meta name="description" content="H3RALD - Fabio Cevasco's Web Site" />
		
		<meta name="keywords" content="h3rald, fabio cevasco, glyph" />
		<link rel="shortcut icon" href="/favicon.png" type="image/png" /> 
		<meta content="44.388041;9.073248" name="ICBM" />

		<link rel="stylesheet" type="text/css" href="/styles/html5reset.css" />
		<link rel="stylesheet" type="text/css" href="/styles/style.css" />

    <script src="http://www.google.com/jsapi?key=ABQIAAAAr6RY1Z6dchG_sX9WDLSy3xRlq2n1sm52B5HDRR5tm6o8XM18FhR56xHNNH6CsX86uN5VoTrglpyOyQ" type="text/javascript"></script>
		<script src="/js/sevenup.js" type="text/javascript"></script>
		<script src="/js/sevenup_black.js" type="text/javascript"></script>
		<script type="text/javascript">google.load("jquery", "1");</script>
		<script src="/js/jquery-timeago.js" type="text/javascript"></script>
		<script src="/js/jquery-easing.js" type="text/javascript"></script>
		<script src="/js/jquery-fancybox.js" type="text/javascript"></script>
		<script src="/js/date.js" type="text/javascript"></script>
		<script src="/js/feeds.js" type="text/javascript"></script>
		<script src="/js/hyphenator.js" type="text/javascript"></script>
		<script src="/js/init.js" type="text/javascript"></script>
		<script src="/js/search.js" type="text/javascript"></script>
	</head>
	<body>
		<section id="container">
			
				<header class="page">
	<nav class="home-link">
		<a href="/">
      <span class="logo">
        <span class="hrald"><span class="h">H</span>&nbsp;<span class="rald">RALD</span></span>
        <span class="three">3</span>
      </span>
		</a>
	</nav>
	
	<nav class="section">
		/<a href="/glyph/" rel="glyph">GLYPH</a>
	</nav>
	
</header>
				<article class="page glyph-book">
					<header>
	<hgroup>
		<h1>Topics</h1> 
		<h2>Glyph</h2>
	</hgroup>
  </header>
					<section id="body-text" class="hyphenate glyph-book">

							<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>
										<nav id="sharing-buttons">
<a href="http://twitter.com/share" class="twitter-share-button" data-count="horizontal" data-via="h3rald">Tweet</a>
<script type="text/javascript" src="http://platform.twitter.com/widgets.js"></script>
</nav>
					</section>
				</article>
					
			
			<footer>
				<section>
					<nav>
						<a href="/about/">ABOUT</a>|<a href="/contact/">CONTACT</a>
					</nav>
					<p>H3RALD Web Site v8.1.2 &copy; 2004 &mdash; 2012 <em>Fabio Cevasco</em></p>
				</section>
			</footer>
		</section><!-- #container end -->
		
		
 <!-- Start Google Analytics --> 
 <script type="text/javascript">
  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'UA-18587377-1']);
  _gaq.push(['_trackPageview']);

  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();
 </script> 
 <!-- End Google Analytics --> 
 <!-- Start of StatCounter Code --> 
  <script type="text/javascript"> 
	var sc_project=6193656; 
	var sc_invisible=1; 
	var sc_security="57f7ee2a"; 
	</script> 
	<script type="text/javascript" src="http://www.statcounter.com/counter/counter_xhtml.js"></script> 
	<!-- End of StatCounter Code --> 
	</body>
</html>