aboutsummaryrefslogtreecommitdiff
path: root/index.html
blob: 9fd23dc2e5999578f43e354df038c72431f602b6 (plain)
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
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
<table class="head" style="width: 100%;">
  <tr>
    <td class="head-ltitle">rf(1)</td>
    <td class="head-vol" style="text-align: center;">General Commands Manual</td>
    <td class="head-rtitle" style="text-align: right;">rf(1)</td>
  </tr>
</table>
<div class="manual-text">
<section class="Sh">
<h2 class="Sh" id="NAME"><a class="permalink" style="color: black; text-decoration: none;" href="#NAME">NAME</a></h2>
<code class="Nm">rf</code> &#x2014;
<div class="Nd">alternative reference system for (t)roff</div>
</section>
<section class="Sh">
<h2 class="Sh" id="SYNOPSIS"><a class="permalink" style="color: black; text-decoration: none;" href="#SYNOPSIS">SYNOPSIS</a></h2>
<table class="Nm">
  <tr>
    <td><code class="Nm">rf</code></td>
    <td><var class="Ar">file</var></td>
  </tr>
</table>
</section>
<section class="Sh">
<h2 class="Sh" id="DESCIPTION"><a class="permalink" style="color: black; text-decoration: none;" href="#DESCIPTION">DESCIPTION</a></h2>
<code class="Nm">rf</code> is a reference system for troff and other roff
  derivatives. It differs from <a class="Xr">refer(1)</a>, the traditional troff
  reference system, in a couple important ways:
<ol class="Bl-enum">
  <li>References are not stored in a separate file. They are defined via macros
      at the end of the troff document itself.
    <p class="Pp">This means that you can move, copy and share your troff
        document without needing to worry about an additional reference file.
        Furthermore, you never run the risk of accidentally losing the
        references attached to a document.</p>
  </li>
  <li><code class="Nm">rf</code> consists of circa 200 lines of Perl. If you
      find a bug or an (in your opinion) undesirable behavior in
      <code class="Nm">rf</code>, you can easily patch it.</li>
  <li>Finally, <code class="Nm">rf</code> is much simpler, much less opaque and
      offers much more basic functionality than <a class="Xr">refer(1)</a>. You
      can learn all of it in five minutes.</li>
</ol>
<p class="Pp">The performance of <code class="Nm">rf</code> primarily depends on
    the number of references (but not citations). On my HP Compaq dc5700 from
    2007, the relationship between number of references and total execution time
    is roughly the following:</p>
<table class="Bl-column Bd-indent">
  <tr>
    <td><i class="Em">Entries&#x00A0;&#x00A0;&#x00A0;&#x00A0;</i></td>
    <td><i class="Em">Time</i></td>
  </tr>
  <tr>
    <td>3</td>
    <td>0.01s</td>
  </tr>
  <tr>
    <td>50</td>
    <td>0.07s</td>
  </tr>
  <tr>
    <td>100</td>
    <td>0.14s</td>
  </tr>
  <tr>
    <td>200</td>
    <td>0.26s</td>
  </tr>
  <tr>
    <td>500</td>
    <td>0.65s</td>
  </tr>
  <tr>
    <td>2,000</td>
    <td>2.59s</td>
  </tr>
  <tr>
    <td>10,000</td>
    <td>12.94s</td>
  </tr>
</table>
<p class="Pp">Luckily, I would deem it extremely rare to have more than a couple
    of hundred unique references in a troff document.</p>
</section>
<section class="Sh">
<h2 class="Sh" id="USAGE"><a class="permalink" style="color: black; text-decoration: none;" href="#USAGE">USAGE</a></h2>
<code class="Nm">rf</code> provides two features, which it calls
  <i class="Em">references</i> and <i class="Em">citations</i>:
<dl class="Bl-tag">
  <dt><i class="Em">reference</i></dt>
  <dd>a bibliographic entry written at the end of the document</dd>
  <dt><i class="Em">citation</i></dt>
  <dd>an inline reference to a bibliographic entry</dd>
</dl>
<p class="Pp"><code class="Nm">rf</code> is controlled by several macros, all
    consisting of one uppercase and one lowercase letter, beginning with either
    an &#x2018;R&#x2019; &#x2013; macros controlling references and citations
    &#x2013; or an &#x2018;F&#x2019; &#x2013; macros controlling the appearance
    of references and citations.</p>
<section class="Ss">
<h3 class="Ss" id="Format_macros"><a class="permalink" style="color: black; text-decoration: none;" href="#Format_macros">Format
  macros</a></h3>
These macros control control the appearance of references and citations.
<dl class="Bl-tag">
  <dt><b class="Sy">Fr</b></dt>
  <dd>Defines the format for references in the bibliography.
    <p class="Pp">Default: %a (%y). {\fI%t\fR}. {\*Q%q\*U}. %n, %d. %c: %p.
        {Available: %w.}</p>
  </dd>
  <dt><b class="Sy">Ff</b></dt>
  <dd>Defines the format for &#x201C;full&#x201D; citations, which by default
      contain both author and year.
    <p class="Pp">Default: (%A %y)</p>
  </dd>
  <dt><b class="Sy">Fx</b></dt>
  <dd>Defines the format for &#x201C;alternate&#x201D; citations, which by
      default contain only the year.
    <p class="Pp">Default: (%y)</p>
  </dd>
</dl>
<p class="Pp">For a description of the format syntax, see
    <a class="Sx" href="#FORMAT_SYNTAX">FORMAT SYNTAX</a>.</p>
</section>
<section class="Ss">
<h3 class="Ss" id="Reference_definition_macros"><a class="permalink" style="color: black; text-decoration: none;" href="#Reference_definition_macros">Reference
  definition macros</a></h3>
In the reference list or bibliography, a single reference is defined by a
  <b class="Sy">contiguous</b> block of lines containing any of the macros
  described below. The definition of one reference is separated from that of
  another by any other lines, <b class="Sy">including</b> text lines, empty
  lines and lines containing other macros than the ones listed below.
<dl class="Bl-tag">
  <dt><b class="Sy">Ra</b></dt>
  <dd>Defines the <i class="Em">author</i> of the publication. You can use
      <b class="Sy">Ra</b> more than once in order to define multiple authors.
    <p class="Pp">Format: Surname, Forename/Initial</p>
  </dd>
  <dt><b class="Sy">Rc</b></dt>
  <dd>Defines the <i class="Em">city</i> of publication.</dd>
  <dt><b class="Sy">Rd</b></dt>
  <dd>Defines the (detailed) <i class="Em">date</i> of publication, not as a
      substitute for <b class="Sy">Ry</b>, but as a further specification. For
      example, the day and month a newspaper article was published.</dd>
  <dt><b class="Sy">Rn</b></dt>
  <dd>Defines the <i class="Em">newspaper</i> in which an article was
    published.</dd>
  <dt><b class="Sy">Rp</b></dt>
  <dd>Defines the <i class="Em">publisher</i> of a book.</dd>
  <dt><b class="Sy">Rq</b></dt>
  <dd>Defines the (quoted) <i class="Em">title</i> of an article.</dd>
  <dt><b class="Sy">Rt</b></dt>
  <dd>Defines the <i class="Em">title</i> of a book.</dd>
  <dt><b class="Sy">Rw</b></dt>
  <dd>Defines the (web) <i class="Em">address</i> of an online resource.</dd>
  <dt><b class="Sy">Ry</b></dt>
  <dd>Defines the <i class="Em">year</i> of publication.</dd>
</dl>
<p class="Pp">In the final output, <code class="Nm">rf</code> prints a formatted
    version of each reference in place of its definition.
    <code class="Nm">rf</code> does not change the order of reference. This
    means that you can arrange your references freely.</p>
</section>
<section class="Ss">
<h3 class="Ss" id="Citation_macros"><a class="permalink" style="color: black; text-decoration: none;" href="#Citation_macros">Citation
  macros</a></h3>
To insert a citation, you can use one of two macros:
<dl class="Bl-tag">
  <dt><b class="Sy">Rf</b></dt>
  <dd>Inserts a &#x201C;full&#x201D; citation, which usually contains both
      author and year.</dd>
  <dt><b class="Sy">Rx</b></dt>
  <dd>Inserts an &#x201C;alternate&#x201D; citation, which usually contains only
      the year.</dd>
</dl>
<p class="Pp"><b class="Sy">Reference identification.</b> &#x00A0;After the
    macro name, you should provide one or more keywords to identify the
    reference to which the citation is to refer. Each word is matched
    case-insensitively against the author, year and title of all references. For
    example:</p>
<div class="Bd Pp Bd-indent">
<pre>
.Rf Trubetzkoy 1969
</pre>
</div>
<p class="Pp">If only a weak match is found, a helpful warning is printed on
    standard error.</p>
<p class="Pp"><b class="Sy">Adjacent punctuation.</b> &#x00A0;To include some
    punctuation character immediately after the inline reference, use the
    following syntax:</p>
<div class="Bd Pp Bd-indent">
<pre>
.Rf Grot 1873 .
</pre>
</div>
<p class="Pp">To wrap the inline reference in parentheses, use the following
    syntax:</p>
<div class="Bd Pp Bd-indent">
<pre>
.Rf Courtenay 1972 ) (
</pre>
</div>
<p class="Pp"><b class="Sy">Shortcuts.</b> &#x00A0;Any instance of
    <code class="Li">''</code> is replaced with the last word on the preceding
    line. This allows the following shortcut:</p>
<div class="Bd Pp Bd-indent">
<pre>
According to Brandt
.Rx '' 1892 ,
Russian differs from other European languages in its [...]
</pre>
</div>
</section>
</section>
<section class="Sh">
<h2 class="Sh" id="FORMAT_SYNTAX"><a class="permalink" style="color: black; text-decoration: none;" href="#FORMAT_SYNTAX">FORMAT
  SYNTAX</a></h2>
<section class="Ss">
<h3 class="Ss" id="Interpolation"><a class="permalink" style="color: black; text-decoration: none;" href="#Interpolation">Interpolation</a></h3>
In a format specification, use a percent (%) sigil followed by a single letter
  to interpolate any given field of the reference. The letter following the
  percent sign corresponds to the second letter of the reference list macros
  described above. For example:
<div class="Bd Pp Bd-indent">
<pre>
.Ff (%A, %y)      \&quot; (Author, Year)
</pre>
</div>
<p class="Pp">By wrapping an interpolation in braces, you can specify a prefix
    and/or suffix that should be included only if the interpolation is
    successful. For example:</p>
<div class="Bd Pp Bd-indent">
<pre>
.Ff (%A{, %y}).   \&quot; Here, ', ' is removed if there is no year.
</pre>
</div>
<p class="Pp">To interpolate only the <b class="Sy">surnames</b> of the authors,
    you can use the special <i class="Em">%A</i> syntax, with an uppercase
    instead of lowercase &#x2018;a&#x2019;.</p>
</section>
<section class="Ss">
<h3 class="Ss" id="Special_backslash_behavior"><a class="permalink" style="color: black; text-decoration: none;" href="#Special_backslash_behavior">Special
  backslash behavior</a></h3>
<ol class="Bl-enum">
  <li>A backslash at the end of a format line acts as a line continuation
      marker. The newline after the backslash is preserved.</li>
  <li>For format macros describing citations, a backslash immediately following
      the macro name will cause the reference be joined to the preceding
    line.</li>
</ol>
<p class="Pp">Anywhere else in the line, backslashes are preserved
  literally.</p>
<p class="Pp">By using backslashes, you can implement footnote-based citations.
    For example, using the ms macro package:</p>
<div class="Bd Pp Bd-indent">
<pre>
.Fx\ \**\
.FS\
%a, {\fI%t\fR}, {\*Q%q\*U}, %y.\
.FE
</pre>
</div>
</section>
<section class="Ss">
<h3 class="Ss" id="Automatic_cleanup"><a class="permalink" style="color: black; text-decoration: none;" href="#Automatic_cleanup">Automatic
  cleanup</a></h3>
You usually don't need to worry about excessive spaces and stray punctuation
  marks. <code class="Nm">rf</code> removes common punctuation immediately
  preceding and following an unsuccessful interpolation. Excessive spaces are
  also removed, unless they follow a period, marking the end of a sentence.
</section>
</section>
<section class="Sh">
<h2 class="Sh" id="EXAMPLE"><a class="permalink" style="color: black; text-decoration: none;" href="#EXAMPLE">EXAMPLE</a></h2>
Below is an example of an ms-based troff document using
  <code class="Nm">rf</code> references.
<div class="Bd Pp Bd-indent">
<pre>
.de noop
..
.blm noop

.SH
Previous work

.LP
Davidson
.Rx '' 1991
has performed a study [...]

.PP
[...] which leads to a higher total cholesterol level
.Rf Smith 2007 .

.SH
Literature

.XP
.Ra Davidson, H.
.Ry 1991
.Rt Seminal Work
.Rc Athens
.Rp Logos

.XP
.Ra Smith, P.
.Ry 2007
.Rt Modern Society
.Rc Athens
.Rp Logos
</pre>
</div>
<p class="Pp">When given the above file, <code class="Nm">rf</code> will output
    the following source code:</p>
<div class="Bd Pp Bd-indent">
<pre>
.de noop
..
.blm noop

.SH
Previous work


.LP
Davidson
(1991)
has performed a study [...]

.PP
[...] which leads to a higher total cholesterol level
(Smith 2007).

.SH
Literature

.XP
Davidson, H. (1991).  \fISeminal Work\fR.  Athens: Logos.

.XP
Smith, P. (2007).  \fIModern Society\fR.  Athens: Logos.
</pre>
</div>
</section>
<section class="Sh">
<h2 class="Sh" id="AUTHORS"><a class="permalink" style="color: black; text-decoration: none;" href="#AUTHORS">AUTHORS</a></h2>
<code class="Nm">rf</code> was written by John Ankarstr&#x00F6;m
  &lt;<a class="Mt" href="mailto:john">john</a>
  <a class="Mt" href="mailto:(at)">(at)</a>
  <a class="Mt" href="mailto:ankarstrom.se">ankarstrom.se</a>&gt;.
</section>
</div>
<table class="foot" style="width: 100%;">
  <tr>
    <td class="foot-date">November 12, 2020</td>
    <td class="foot-os" style="text-align: right;">Linux 5.4.72-0-lts</td>
  </tr>
</table>