-
Notifications
You must be signed in to change notification settings - Fork 4
/
part2-1-1.xml
228 lines (227 loc) · 8.3 KB
/
part2-1-1.xml
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
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
<?xml version="1.0" encoding="UTF-8"?>
<html>
<head>
<meta http-equiv="Content-Type" content="text/xml; charset=utf-8"/>
<title>Input Encoding</title>
<link rel="stylesheet" href="css/book.css" type="text/css"/>
</head>
<body>
<h3>
Input Encoding
</h3>
<p>
Without exception, a well-formed <span class="lang">mdoc</span> document consists only of <a class="term"
href="glossary.xml#ascii">ASCII</a> printable characters, the space character, the newline character, and in
some cases the tab character. Most modern formatters allow for CR+LF newlines <span class="screen">\r\n</span>, but
this is not portable. Modern formatters also accomodate for unlimit to line length; this is not necessarily the case
for legacy formatters.
</p>
<p>
Unilaterally, the backslash <span class="screen">\</span> is always interpreted as the beginning of an <a
href="part2-1-2.xml#escape_sequences">escape sequence</a>. If an escape precedes a newline, it escapes the
current line:
</p>
<div class="mdocin">
.Em This is considered one \
<br />
line of input.
</div>
<h4 id="macro_line">
Macro Line
</h4>
<p>
Formally speaking, a macro line is one beginning with a control character. In <span class="lang">mdoc</span>, this is
traditionally the <span class="screen">.</span> character, although historical documents may also use the <span
class="screen">'</span> character. This notation extends back to the historical <a class="term"
href="glossary.xml#runoff">RUNOFF</a> utility.
</p>
<blockquote cite="http://mit.edu/Saltzer/www/publications/CC-244.html">
<p>
<span class="under">Control Words</span>:
</p>
<p>
Input generally consists of English text, 360 or fewer characters to a line. Control words must begin a new
line, and begin with a period so that they may be distinguished from other text. RUNOFF does not print the
control words.
</p>
</blockquote>
<p>
A line with only a control character followed by zero or more whitespace characters is stripped from input.
</p>
<p>
A macro line may, in some circumstances, contain more macros. The first macro — the one following the control
character — may then be distinguished as the line macro.
</p>
<p>
On macro lines the following non-alphanumeric characters are syntactically meaningful as follows. These characters are
collectively called reserved characters.
</p>
<table id="reserved" class="tbl">
<col style="width: 5em;" />
<col />
<tbody>
<tr>
<td><span class="screen">!</span></td>
<td><a href="part2-1-5.xml#punctuation">punctuation</a></td>
</tr>
<tr>
<td><span class="screen">"</span></td>
<td>control character (<a href="part2-1-6.xml#quotation">quotation</a>)</td>
</tr>
<tr>
<td><span class="screen">(</span></td>
<td><a href="part2-1-5.xml#punctuation">punctuation</a></td>
</tr>
<tr>
<td><span class="screen">)</span></td>
<td><a href="part2-1-5.xml#punctuation">punctuation</a></td>
</tr>
<tr>
<td><span class="screen">,</span></td>
<td><a href="part2-1-5.xml#punctuation">punctuation</a></td>
</tr>
<tr>
<td><span class="screen">-</span></td>
<td>control character (<a href="part2-1-4.xml#macros">macro argument</a>)</td>
</tr>
<tr>
<td><span class="screen">.</span></td>
<td><a href="part2-1-5.xml#punctuation">punctuation</a></td>
</tr>
<tr>
<td><span class="screen">:</span></td>
<td><a href="part2-1-5.xml#punctuation">punctuation</a></td>
</tr>
<tr>
<td><span class="screen">;</span></td>
<td><a href="part2-1-5.xml#punctuation">punctuation</a></td>
</tr>
<tr>
<td><span class="screen">?</span></td>
<td><a href="part2-1-5.xml#punctuation">punctuation</a></td>
</tr>
<tr>
<td><span class="screen">[</span></td>
<td><a href="part2-1-5.xml#punctuation">punctuation</a></td>
</tr>
<tr>
<td><span class="screen">\</span></td>
<td>control character (<a href="part2-1-2.xml#escape_sequences">escape sequence</a>)</td>
</tr>
<tr>
<td><span class="screen">]</span></td>
<td><a href="part2-1-5.xml#punctuation">punctuation</a></td>
</tr>
<tr>
<td><span class="screen">|</span></td>
<td><a href="part2-1-5.xml#punctuation">punctuation</a></td>
</tr>
</tbody>
</table>
<p>
To pass these characters along as literal text, you must either escape or quote them.
</p>
<p>
If an unescaped space character is encountered on a macro line, it is used to delimit macros, macro arguments, and
flags. Multiple consecutive space characters have no effect on output.
</p>
<div class="mdocin">
.Em Hello, World
<br />
.Em Hello, World
</div>
<p>
The spaces between <span class="screen">Hello,</span> and <span class="screen">world</span> delimit arguments in this
case, and produce the same output of <i>Hello, World</i> without extra spaces.
</p>
<h4 id="text_line">
Text Line
</h4>
<p>
A text line is any line <i>not</i> beginning with a control character. Text lines are never parsed for macros and may
consist of printable ASCII character. Text lines are concatenated together when forming output, so unless in certain
circumstances, newlines are stripped from input. Using a blank text line as a vertical separator is not portable.
</p>
<p>
If a space character is encountered on a text line, it is reproduced verbatim in the output.
</p>
<div class="mdocin">
Hello, World
<br />
Hello, World
</div>
<p>
The spaces between <span class="screen">Hello,</span> and <span class="screen">world</span> will be reproduced in both
cases as-is. However, it is considered non-portable to use spaces on a text-line to shape output: <a class="term"
href="glossary.xml#html">HTML</a>, for example, by default collapses whitespace. Secondly, consider whether
controlled spacing between text in an otherwise free-form text sequence is appropriate. In most space-retaining cases,
such as in source code examples, you're better off with a literal display mode such as covered at the end of this
section.
</p>
<p>
<b>Do not</b> use the space-retaining feature to create double-spaces following a sentential period! See <a
href="part2-1-5.xml#sentential_punctuation">Sentential Punctuation</a> for how to do this properly.
</p>
<p>
If the first letter of a text line is a space character, the output line shall be preceded by a newline. This creates
the effect of an implicit literal display.
</p>
<div class="mdocin">
Hello, World.
<br />
The newline, leading spaces, and in-line spacing are retained.
<br />
This is free-form text.
</div>
<p>
The portability of this behaviour is unknown. For greater portability (and semantic annotation), a literal display mode
should be opened instead with, for example, the <a class="macro" href="macros.xml#macro_bd">Bd</a> <span
class="macroflag">literal</span>:
</p>
<div class="mdocin">
Hello, World.
<br />
.Bd -literal -compact
<br />
The newline and leading spaces are retained.
<br />
.Ed
<br />
While this is not.
</div>
<p>
In this example, the <span class="macroflag">compact</span> flag prevents leading vertical space. To effect a vertical
space following the literal display, use a <a class="macro" href="macros.xml#macro_pp">Pp</a>.
</p>
<div class="mdocin">
Consider the following example:
<br />
.Bd -literal
<br />
int a_function(int *foo, int bar) {
<br />
*foo += bar;
<br />
}
<br />
.Ed
<br />
.Pp
<br />
This is subsequent text.
</div>
<table class="nav">
<tbody>
<tr>
<td class="nav-contents"><a href="toc.xml">Contents</a></td>
<td class="nav-next"><a href="part2-1-2.xml">Next</a></td>
<td class="nav-home"><a href="http://manpages.bsd.lv/index.html">Home</a></td>
<td class="nav-history"><a href="http://manpages.bsd.lv/cgi-bin/cvsweb/part2-1-1.xml?cvsroot=manpages">History</a></td>
</tr>
</tbody>
</table>
<p class="edits">
Last edited by $Author$ on $Date$. Copyright © 2011, Kristaps Dzonsons. CC BY-SA.
</p>
</body>
</html>