forked from nspring/style-check
-
Notifications
You must be signed in to change notification settings - Fork 1
/
README.html
273 lines (221 loc) · 12.1 KB
/
README.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
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
<html>
<body>
<h1>style-check.rb</h1>
<p>The code described in this README parses
latex-formatted text in search of forbidden phrases and
prints error messages formatted as if from a compiler.
<h1>Why does this code exist?</h1>
<p>This code is a weapon against collaborators who would
dilute your writing with ambiguous or verbose prose. It
was designed to ensure that collaborative papers appear
in a consistent style: mine.
<p>I think of all activities as coding. My
presentations use python scripts, not powerpoint. My
writing and research posters use latex and emacs, not
word or publisher. When I write code, I try to be
creative and sloppy, relying on tools to identify most
of my mistakes. (For example, gcc issues warnings,
splint can verify some memory processes, and custom
scripts can identify simple portability problems.) When
writing text, I had no such tools.
<p>The style checker is one such tool. When I notice a
mistake that can be identified by a regular expression,
I add a forbidden expression to the style checker's
ruleset. Then, when I build my latex-formatted paper, I
run the style checker to seek out such phrases.
<p>It has saved me from submitting gramatically-sloppy
last-minute edits.
<p>Like the warnings printed by a compiler, errors from
the style checker should not be taken literally. Use
your own judgement to correct sentences: make them
shorter, more specific, and more varied. I cannot
advise you to rely on this tool in the way I do; my
approach to writing is not necessarily a good one for
anyone.
<h1>How does it work?</h1> The style checker is a ruby
script that seeks out files in directories
/etc/style-check.d or ~/.style-check.d, or files named
~/.style-censor or ./style-censor. Each file is a list
of expressions in one of four types, annotated with a
justification. See the existing files for examples.
<h2>Type 1: Syntax</h2> Syntax expressions are matched
exactly. They are case-sensitive. Any regular
expression will do. As a hint, "\b" will match some
non-word character, like a space or newline.
<pre class="example">
[ ], <span class="examplecomment">% syntax whitespace before comma seems wrong.</span>
''[\.,] <span class="examplecomment">% syntax end quotes go outside punctuation like . and , </span>
[ ]-[ ] <span class="examplecomment">% syntax a hyphen surrounded by space should probably be an emdash '---'</span>
</pre>
<h2>Type 2: Capitalize</h2> Capitalize expressions match
whole words, and are case-sensitive. Such expressions
are designed to help maintain uniformity of
capitalization of product and project names, like
PlanetLab, Scriptroute, CoDeeN, iPod, etc. They are
transparently wrapped with "\b"s to ensure that only
whole words are matched.
<pre class="example">
Planetlab <span class="examplecomment">% capitalize PlanetLab</span>
planetlab <span class="examplecomment">% capitalize PlanetLab</span>
ccdf <span class="examplecomment">% capitalize</span>
cisco <span class="examplecomment">% capitalize the company name</span>
internet <span class="examplecomment">% capitalize unless talking about an internet other than the Internet</span>
ttl <span class="examplecomment">% capitalize</span>
</pre>
<h2>Type 3: Phrase</h2> Phrases match longer phrases
such as "the foreseeable future" or <a
href="http://www.plainenglish.co.uk/pressrelease.html">"at
the end of the day"</a>. As with capitalize expressions,
they are transparently wrapped with "\b"s, but are not
case sensitive. Some phrases that should be forbidden
include double words.
<pre class="example">
[^r][^c][^h] impact <span class="examplecomment">% phrase "effect", "result", though nsf likes "research impact"</span>
absolutely essential <span class="examplecomment">% phrase essential</span>
few in number <span class="examplecomment">% phrase few</span>
the the <span class="examplecomment">% phrase apparent double word.</span>
(quite|more|very|most) unique <span class="examplecomment">% phrase unique is.</span>
a large number of <span class="examplecomment">% phrase you mean "many"</span>
the way in which <span class="examplecomment">% phrase should be "how" or "" </span>
live in a vacuum <span class="examplecomment">% phrase a tired metaphor that makes me want to vomit. </span>
</pre>
<h2>Type 4: Spelling</h2> Spelling expressions are
internally handled just like phrases. These are useful
for common misspellings or typo's. Perhaps you habitually
misspell lose as loose and would prefer to have a checker
complain. I habitually misspell measurment, secrurity,
and experiements.
<pre class="example">
experiements <span class="examplecomment">% spelling</span>
measurment <span class="examplecomment">% spelling</span>
secrurity <span class="examplecomment">% spelling</span>
taht <span class="examplecomment">% spelling</span>
teh <span class="examplecomment">% spelling</span>
privledge <span class="examplecomment">% spelling "privilege" I misspell it every way possible.</span>
privlege <span class="examplecomment">% spelling "privilege" I misspell it every way possible.</span>
priviledge <span class="examplecomment">% spelling "privilege" I misspell it every way possible.</span>
queueing <span class="examplecomment">% spelling I'd love to spell it this way, but spellchecker whines.</span>
</pre>
<h2>Type -1: Ignored Commands</h2> Ignore the parameter
to this command. If only spell checkers were this cool.
The standard ignored commands are \begin, \end, \url,
\cite, \ref, \label, and a few others. You can extend
this in ./censor-dict with a personal dictionary that
might include, for example \todo or \hostname. The
internal implementation of ignored commands is to
"replace" them with ~ (the non-breaking space character)
before the rest of the rules are checked, so it is
possible that other rules may need to take this into
account.
<pre class="example">
todo <span class="examplecomment">% ignoredcommand</span>
texttt <span class="examplecomment">% ignoredcommand</span>
</pre>
<h2>Built-in checking</h2>
<p>In addition to configurable rules, the style checker
also seeks out common errors within the LaTeX source
itself: <ul>
<li>an unescaped percent-sign directly following a
number is frequently an error.</li>
<li>a \cite{} tag should precede (not follow) a period.</li>
<li>a \cite{} tag should not be used obviously as a noun in
the middle of a sentence.</li>
<li>paragraphs should end with the end of a sentence.</li>
</ul>
<p>Comments using \begin{comment} and \end{comment} from
comment.sty are skipped.
<p>Math mode between unescaped $'s is skipped.
<p>For more detail, read the ruby code. It's shorter
than this file.
<h1>How do I use it?</h1>
From the style-check-(version) directory, run <br>
<tt>sudo make install</tt> <br>
to install as the superuser. As an alternative, <br>
<tt>make user-install</tt><br>
will put the
ruleset in your home-directory, but putting the
style-check.rb script in your path is up to you.
<p>To run the script,<br>
<tt>style-check.rb *.tex</tt>
<p>Or, if you'd like a little justification with your scolding, <br>
<tt>style-check.rb -v *.tex</tt>
<h1>Limitations</h1> This is not a proof-reader, editor,
spelling checker, or grammar checker. It can catch only
some simple, common, frustrating mistakes. It is not a
substitute for reading what I've listed below. It is intended
only for LaTeX files.
<p>This code will not teach you to use "that" and
"which" properly. It will not teach you to hyphenate.
It may be used for evil. You may think my rules are
stupid.
<p>There are many bugs in the code; it is not guaranteed
that the style checker will find all forbidden phrases. It
may become confused by nested environments.
<h1>Attitude</h1>
<p>Don't ask me to add a feature. Send me a patch.
<p>Don't complain that it's written in Ruby. My
language kicks your language's ass.
<p>Don't complain about the ruleset. Invent a mechanism
to override ones you don't care for.
<h1>Further Reading</h1> This section is split into two
categories -- entertainment for reading that is light
and fun and should help you think about writing better,
and reference that may help answer harder questions.
<h2>Entertainment</h2>
The Elements of Style, by Strunk and White<br>
<a href="http://www.bartleby.com/141/">http://www.bartleby.com/141/</a>
<p>Woe is I: The Grammarphobe's Guide to Better English in Plain English, by Patricia T. O'Conner.
<p>Lake Superior State University Banished Words List<br>
<a href="http://www.lssu.edu/banished/">http://www.lssu.edu/banished/</a>
<p>Usage in The American Heritage Dictionary<br>
<a href="http://www.bartleby.com/61/7.html">http://www.bartleby.com/61/7.html</a>
<p>alt.usage.english FAQ<br>
<a href="http://alt-usage-english.org/fast_faq.shtml">http://alt-usage-english.org/fast_faq.shtml</a>
<p>How To Write A Dissertation, by Doug Comer<br>
<a href="http://www.cs.purdue.edu/homes/dec/essay.dissertation.html">http://www.cs.purdue.edu/homes/dec/essay.dissertation.html</a>
<p>Plain English Campaign<br>
<a href="http://www.plainenglish.co.uk/">http://www.plainenglish.co.uk/</a>
<p>Thesis Errors<br>
<a href="http://core.ecu.edu/psyc/wuenschk/therr.htm">http://core.ecu.edu/psyc/wuenschk/therr.htm</a>
<p>How to Avoid Colloquial (Informal) Writing<br>
<a href="http://www.wikihow.com/Avoid-Colloquial-%28Informal%29-Writing">http://www.wikihow.com/Avoid-Colloquial-%28Informal%29-Writing</a>
<p>Henning Schulzrinne's Notes</p><br>
<a href="http://www.cs.columbia.edu/~hgs/etc/writing-style.html">http://www.cs.columbia.edu/~hgs/etc/writing-style.html</a>
<h2>Reading that takes work (and reference)</h2>
<p>Rules for Writers, by Diana Hacker.
<p>The New Oxford Guide to Writing, by Thomas S. Kane.
<p>Line by Line: How to Edit Your Own Writing, by Claire Cook.
<h2>Related Code</h2>
<p>Michael Haardt wrote GNU <a
href="http://www.gnu.org/software/diction/diction.html">diction</a>,
which is similar in that it finds and complains about
bad phrases, but different in that it also notes
questionable phrases (such as any use of "affect") and
does not expect to check LaTeX source. Style-check
focuses on forbidden phrases and common typographic
errors in LaTeX code.
<h2>To download</h2>
<a href="http://www.cs.umd.edu/~nspring/software/style-check-current.tar.gz">http://www.cs.umd.edu/~nspring/software/style-check-current.tar.gz</a>
<h1>Thanks</h1>
<p>Kurt Partridge for encouraging me to release this thing. </p>
<p>Vibha Sazawal for reminding me often that there is more to writing than style. </p>
<p>Rich Wolski for introducing me to Strunk and White, the gateway drug.</p>
<p>Jacob Martin reported the first bug, packaged style-check for <a href="http://www.gentoo-portage.com/dev-tex/style-check">gentoo</a>, and contributed a ruleset based
on <a href="www.amazon.com/ How-Write-Publish-Scientific-Paper/dp/0313330271">Day
and Gastel, "How to Write and Publish a Scientific Paper"</a>.</p>
<p>Indika Meedeniya noticed a few more bugs and suggested compatibility with gedit.</p>
<p>Rudolf Mühlbauer suggested: <blockquote>
I use it in conjunction with vim [:make | copen]:
<pre>
~/.vim/ftplugin/tex.vim:
set makeprg=~/opt/style-check-0.14/style-check.rb\ -v\ %
</pre>
</blockquote>
<hr>
<address><a href="mailto:[email protected]">Neil Spring</a></address>
<!-- Created: Wed May 12 13:50:54 PDT 2004 -->
<!-- hhmts start -->
Last modified: Wed Aug 17 09:06:10 EDT 2011
<!-- hhmts end -->
</body>
</html>