-
Notifications
You must be signed in to change notification settings - Fork 4
/
part3-3-2.xml
132 lines (132 loc) · 5.38 KB
/
part3-3-2.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
<?xml version="1.0" encoding="UTF-8"?>
<html>
<head>
<meta http-equiv="Content-Type" content="text/xml; charset=utf-8"/>
<title>Spell-checking</title>
<link rel="stylesheet" href="css/book.css" type="text/css"/>
</head>
<body>
<h3>
Spell-checking
</h3>
<p>
The right or wrong spelling of terms in technical documents is very important. Thus, it's always important to carefully
spell-check your manuals, making sure that both technical and general terms are correctly spelt.
</p>
<p>
Unfortunately, spell-checking a <span class="lang">mdoc</span> document is fairly difficult, as the spell-checker must
have some knowledge of the language structure to discern text from macros. Consider spell-checking checking the
following snippet.
</p>
<div class="mdocin">
.Fl Alu Ar input
</div>
<p>
By now we understand that <a class="macro" href="macros.xml#macro_fl">Fl</a> and <a class="macro"
href="macros.xml#macro_ar">Ar</a> are macros. But it's unreasonable to expect a spell-checker to do so. Thus,
spell-checking manuals often raise many false-positives.
</p>
<h4>
spell
</h4>
<p>
The <a class="cmd" href="commands.xml#cmd_spell">spell</a> utility is distributed with many <a class="term"
href="glossary.xml#bsd_unix">BSD UNIX</a> operating systems as a simplistic spell-checker. In fact, it was
first distributed with Version 6 AT&T UNIX. <a href="commands.xml#cmd_spell" class="cmd">spell</a> preprocesses its
input with <a href="commands.xml#cmd_deroff" class="cmd">deroff</a>, another historic utility with some functionality of
stripping <span class="lang">roff</span> instructions from files.
</p>
<p>
To print a list of all unknown words, you can explicitly invoke <a href="commands.xml#cmd_deroff" class="cmd">deroff</a>
and <a href="commands.xml#cmd_spell" class="cmd">spell</a> as follows:
</p>
<div class="cmdline">
deroff -w file.1 | spell
</div>
<p>
A utility distributed with <a href="commands.xml#cmd_mandoc" class="cmd">mandoc</a>, <a href="commands.xml#cmd_demandoc"
class="cmd">demandoc</a>, is significantly stronger than <a href="commands.xml#cmd_deroff"
class="cmd">deroff</a>. If available, it should be used instead. It has the same calling syntax of <a
href="commands.xml#cmd_deroff" class="cmd">deroff</a>.
</p>
<div class="cmdline">
demandoc -w file.1 | spell
</div>
<p>
You can also maintain a per-manual list of technical terms by using additional word lists. In the case of <span
class="file">file.1</span>, consider a sorted list of words <span class="file">file.1.words</span> we're
maintaining with special words (such as names). We could then augment a <a href="commands.xml#cmd_make"
class="cmd">make</a> rule to automatically make sure additions are spell-checked.
</p>
<div class="screen">
file.1: file.1.words
<br />
<br />
.in.1.1:
<br />
mandoc -Tlint $<
<br />
test -z `demandoc -w $< | spell -b +$@.words`
<br />
cp -f $< $@
</div>
<p>
This snippet first makes the build of <span class="file">file.1</span> depend upon its local word file, <span
class="file">file.1.words</span>, a sorted list of words to ignore. When <span class="file">file.in.1</span> or
<span class="file">file.1.words</span> is updated, the rule is executed. It first makes sure that <span
class="file">file.in.1</span> is well-formed, then spell-checks it against the ignored-words file.
</p>
<p>
The same can be accomplished on systems without <a href="commands.xml#cmd_mandoc" class="cmd">mandoc</a>.
</p>
<div class="screen">
file.1: file.1.words
<br />
<br />
.in.1.1:
<br />
test -z `deroff -w $< | spell -b +$@.words`
<br />
cp -f $< $@
</div>
<h4>
ispell, aspell
</h4>
<p>
Another common spell-checker is <a class="cmd" href="commands.xml#cmd_ispell">ispell</a> and its <a class="term"
href="glossary.xml#gnu">GNU</a> replacement <a class="cmd" href="commands.xml#cmd_aspell">aspell</a>. I do not
suggest using these utilities because of their poor internal support for <span class="lang">mdoc</span>. It's possible,
however, to send stripped files for checking in a manner similar to <a class="cmd"
href="commands.xml#cmd_spell">spell</a>:
</p>
<div class="cmdline">
demandoc -w file.1 | ispell -l
</div>
<p>
Or with <a href="commands.xml#cmd_deroff" class="cmd">deroff</a>:
</p>
<div class="cmdline">
deroff -w file.1 | ispell -l
</div>
<p>
Both <a href="commands.xml#cmd_ispell" class="cmd">ispell</a> and <a href="commands.xml#cmd_aspell"
class="cmd">aspell</a> also have a pipe mode for more meaningful output:
</p>
<div class="cmdline">
demandoc -w file.1 | ispell -a
</div>
<table class="nav">
<tbody>
<tr>
<td class="nav-contents"><a href="toc.xml">Contents</a></td>
<td class="nav-next"><a href="part3-3-3.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/part3-3-2.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>