@c $Id: grammar.texinfo,v 1.30 2002/01/09 16:59:07 m Exp m $
@node    Grammar, Analyzing Text, Text Editing, Text
@comment node-name,     next,	previous,	up
@chapter Grammar and Reference
@cindex grammar and reference
@cindex reference, tools for

@noindent
The tools and resources for writing and editing on Linux-based systems
include spell checkers, dictionaries, and reference files. This chapter
shows methods for using them.

@menu
* Spelling::                    Spell checking.
* Dictionaries::                Dictionaries.
* Checking Grammar::            Grammar tools.
* Reference Files::             Word lists and reference files.
@end menu


@node Spelling, Dictionaries, Grammar, Grammar
@comment  node-name,  next,  previous,  up
@section Spelling
@cindex spelling
@cindex system dictionary

@noindent
There are several ways to spell check text and files on Linux; the
following recipes show how to find the correct spellings of particular
words and how to perform batch, interactive, and Emacs-based spell
checks.

The system dictionary file, @file{/usr/dict/words},@footnote{On an
increasing number of systems, this file is being replaced with
@file{/usr/share/dict/words}; administrators should make a symbolic link
from this to the shorter, preferred form.} is nothing more than a word
list (albeit a very large one), sorted in alphabetical order and
containing one word per line. Words that are correct regardless of case
are listed in lowercase letters, and words that rely on some form of
capitalization in order to be correct (such as proper nouns) appear in
that form. All of the Linux spelling tools use this text file to check
spelling; if a word does not appear in the dictionary file, it is
considered to be misspelled.

@sp .25
@noindent
@strong{NOTE:} None of the computerized spell-check tools will correct
your writing if you are using the wrong word to begin with---for
example, if you have @samp{there} when you mean @samp{their}, the
computer will not catch it (yet!).

@menu
* Word Spell::                  Spell checking a word.
* File Spell::                  Spell checking a file.
* Personal Dictionary::         Keeping a personal dictionary.
* Ispell::                      Interactive spell checking.
* Emacs Spelling::              Spell checking in Emacs.
@end menu


@node Word Spell, File Spell, Spelling, Spelling 
@comment  node-name,  next,  previous,  up
@subsection Finding the Correct Spelling of a Word
@cindex finding the correct spelling of a word
@cindex word, finding the correct spelling of a 
@pindex spell

@noindent
If you're unsure whether or not you're using the correct spelling of a
word, use @code{spell} to find out. @code{spell} reads from the standard
input and outputs any words not found in the system dictionary---so if a
word is misspelled, it will be echoed back on the screen after you type
it.

@itemize @bullet
@item
For example, to check whether the word @samp{occurance} is misspelled, type:

@example
@cartouche
$ @kbd{spell @key{RET}
occurance @key{RET}}
occurance
@kbd{C-d}
$
@end cartouche
@end example
@end itemize

In the example, @code{spell} echoed the word @samp{occurance}, meaning
that this word was not in the system dictionary and therefore was quite
likely a misspelling. Then, @kbd{C-d} was typed to exit @code{spell}.


@node File Spell, Personal Dictionary, Word Spell, Spelling
@comment  node-name,  next,  previous,  up
@subsection Listing the Misspellings in a Text
@cindex listing the Misspellings in a text
@cindex text, listing the Misspellings in a
@cindex files, listing the misspellings in
@cindex spell checking files
@pindex uniq
@pindex sort

@noindent
To output a list of misspelled words in a file, give the name of the
file to check as an argument to @code{spell}. Any misspelled words in
the file are output, each on a line of its own and in the order that
they appear in the file.

@itemize @bullet
@item
To spell check the file @file{fall-lecture.draft}, type:

@example
@cartouche
$ @kbd{spell fall-lecture.draft @key{RET}
occurance
willl
occurance}
$
@end cartouche
@end example
@end itemize

In this example, three words are output: @samp{occurance}, @samp{willl}
and @samp{occurance} again, meaning that these three words were found in
@file{fall-lecture.draft}, in that order, and were not in the system
dictionary (and so were probably misspelled). Note that the misspelling
@samp{occurance} appears twice in the file.

To correct the misspellings, you could then open the file in your
preferred text editor and edit it. Later in this section I'll describe
an interactive spell checker that allows you to correct misspellings as
they are found. Still another option is to use a text editor with
spell-checking facilities built in, such as Emacs.

@itemize @bullet
@item
To spell check the file @file{fall-lecture.draft}, and output any
possibly misspelled words to a file @file{fall-lecture.spelling}, type:

@example
$ @kbd{spell fall-lecture.draft > fall-lecture.spelling @key{RET}}
@end example
@end itemize

In this example, the standard output redirection character, @samp{>}, is
used to redirect the output to a file (@pxref{Standard Output, ,
Redirecting Output to a File}).

To output an @emph{alphabetical} list of the misspelled words, pipe the
output to @code{sort}; then pipe the sorted output to the @code{uniq}
filter to remove duplicates from the list (@code{uniq} removes duplicate
adjacent lines from its input, outputting the ``unique'' lines).

@itemize @bullet
@item
To output a sorted list of the misspelled words that are in the file
@file{fall-lecture.draft}, type:

@example
$ @kbd{spell fall-lecture.draft | sort | uniq @key{RET}}
@end example
@end itemize


@node Personal Dictionary, Ispell, File Spell, Spelling
@comment  node-name,  next,  previous,  up
@subsection Keeping a Spelling Word List
@cindex keeping a spelling word list
@cindex spelling, keeping a word list for
@cindex word lists, for spelling
@cindex personal dictionary
@cindex dictionary, personal
@cindex Haun, Gregory Cosmo
@pindex ispell

@noindent
The stock American English dictionary installed with Linux-based systems
includes over 45,000 words. However large that number may seem, a lot of
words are invariably left out---including slang, jargon, and some proper
names.

You can view the system dictionary as you would any other text file, but
users never edit this file to add words to it.@footnote{If a word is
reasonably universal, you may, of course, contact the global maintainers
of @code{wenglish} or other appropriate packages and try to convince
them that said word ought to be included.} Instead, you add new words to
your own @dfn{personal dictionary}, a file in the same format as the
system dictionary, but kept in your home directory as the file
@file{~/.ispell_default}.

Users can have their own personal dictionary; the spelling commands
discussed in this chapter automatically use your personal dictionary, if
you have one, in addition to the system dictionary.

You build your personal dictionary using the @kbd{i}
and @kbd{u} options of @code{ispell}, which insert words into your
personal dictionary. Use these options either with the stand-alone tool
or with the various @code{ispell} Emacs functions (see @ref{Ispell, ,
Interactive Spell Checking} and @ref{Emacs Spelling, , Spell Checking in
Emacs}).

@sp .25
@strong{NOTE:} You can also add (or remove) words by manually editing
the file with a text editor, but take care so that the list is kept in
alphabetical order!

Over time, personal dictionaries begin to look very personal, as a
reflection of their owners; Gregory Cosmo Haun made a work of art by
photographing the portraits of a dozen users superimposed with listings
of their personal dictionaries (accessible online at
@url{http://www.reed.edu/~cosmo/art/DictPort.html}).


@node Ispell, Emacs Spelling, Personal Dictionary, Spelling
@comment  node-name,  next,  previous,  up
@subsection Interactive Spell Checking
@cindex interactive spell checking
@cindex spell checking, interactive
@pindex ispell

@noindent
Use @code{ispell} to spell check a file @emph{interactively}, so that
every time a misspelling is found, you're given a chance to replace it
then and there.

@itemize @bullet
@item
To interactively spell check @file{fall-lecture.notes}, type:

@example
$ @kbd{ispell fall-lecture.notes @key{RET}}
@end example
@end itemize

When you type this, @code{ispell} begins checking the file. It stops at
the first misspelling it finds:

@cartouche
@image{grammar-ispell-01, 4in}
@end cartouche

On the top line of the screen, @code{ispell} displays the misspelled
word, followed by the name of the file. Underneath this is the sentence
in which the misspelling appears, with the word in question
highlighted. Following this is a list of suggested words, each offset by
a number---in this example, @code{ispell} has only one suggestion:
@samp{lectures}.

To replace a misspelling with a suggested word, type the number that
corresponds to the suggested word (in this example, you would type
@kbd{0} to replace the misspelling with @samp{lectures}). You only need
to type the number of your selection---a @key{RET} is not required.

You can also type a correction yourself; this is useful when
@code{ispell} either offers no suggestions, or when it does and the word
you want is not one of them. To do this, type @kbd{r} (for ``replace'')
and then type the replacement word, followed by @key{RET}.

Sometimes, @code{ispell} will question a word that you may not want to
count as a misspelling, such as proper names and the like---words that
don't appear in the system dictionary. There are a few things you can do
in such cases, as follows.

To accept a misspelled word as correct for the current @code{ispell}
session only, type @kbd{a}; from then on during the current session,
this word will be considered correct.

If, however, you want @code{ispell} (and @code{spell}, and all other
tools that access the system dictionary) to remember this word as being
correct for this and all future sessions, insert the word in your own
personal dictionary. Type @kbd{u} to insert a copy of the word
@emph{uncapitalized}, in all lowercase letters---this way, even if the
word is capitalized at the beginning of a sentence, the lowercase
version of the word is saved. From then on, in the current @code{ispell}
session and in future sessions, this word, regardless of case, will be
considered correct.

When case is important to the spelling---for example, in a word that is
a proper name such as @samp{Seattle}, or a word with mixed case, such as
@samp{LaTeX}---type @kbd{i} to insert a copy of the word in your
personal dictionary with its case @emph{just as it appears}; this way,
words spelled with the same letters but with different case will be
considered misspellings.

When @code{ispell} finishes spell checking a file, it saves its changes
to the file and then exits. It also makes a copy of the original file,
without the changes applied; this file has the same name as the original
but with @file{.bak} added to the end---so in our example, the backup
file is called @file{fall-lecture.notes.bak}. This is useful if you
regret the changes you've made and want to restore the file to how it
was before you mucked it up---just remove the spell-checked file and
then rename the @file{.bak} file to its original name.

The following table is a reference to the @code{ispell} key commands.

@multitable @columnfractions .30 .70
@item @sc{Key}
@tab @sc{Command}
@item @key{SPC}
@tab Accept misspelled word as correct, but only for this particular
instance.

@item @var{number}
@tab Replace the misspelled word with the suggestion that corresponds to
the given number.

@item @code{?}
@tab Display a help screen.

@item @code{a}
@tab Accept misspelled word as correct for the remainder of this
@code{ispell} session.

@item @code{i}
@tab Accept misspelled word as correct and add it to your private
dictionary with the capitalization as it appears.

@item @code{l}
@tab Look up words in the system dictionary according to a pattern you
then give.

@item @code{q}
@tab Quit checking and restore the file to how it was before this
session.

@item @code{r}
@tab Replace misspelled word with a word you type.

@item @code{u}
@tab Accept misspelled word as correct and add it to your private
dictionary in all lowercase letters.

@item @code{x}
@tab Save the changes thus made, and then stop checking this file.
@end multitable


@node Emacs Spelling, , Ispell, Spelling
@comment  node-name,  next,  previous,  up
@subsection Spell Checking in Emacs
@cindex spell checking in Emacs
@cindex Emacs, spell checking in 
@pindex emacs
@pindex ispell
@pindex spell
@pindex flyspell-mode

@noindent
Emacs has several useful commands for spell checking. The
@code{ispell-word}, @code{ispell-region}, and @code{ispell-buffer}
functions, as you might guess from their names, use the @code{ispell}
command inside Emacs to check portions of the current buffer.

The first command, @code{ispell-word}, checks the spelling of the word
at point; if there is no word at point, it checks the first word to the
left of point. This command has a keyboard shortcut, @kbd{M-$}. The
second command, @code{ispell-region}, checks the spelling of all words
in the currently selected region of text. The third command,
@code{ispell-buffer}, checks the spelling of the entire buffer.

@itemize @bullet
@item
To check the spelling of the word at point, type:

@example
@kbd{M-x ispell-word @key{RET}}
@end example

@item
To check the spelling of all words in the currently selected region of
text, type:

@example
@kbd{M-x ispell-region @key{RET}}
@end example

@item
To check the spelling of all words in the current buffer, type:

@example
@kbd{M-x ispell-buffer @key{RET}}
@end example
@end itemize

@code{Flyspell} mode is another useful Emacs spelling command that, when
set in a buffer, highlights misspelled words. This function is useful
when you are writing a first draft in a buffer, because it lets you
catch misspellings as you type them.

@itemize @bullet
@item
To turn on @code{Flyspell} mode in a buffer, type:

@example
@kbd{M-x flyspell-mode @key{RET}}
@end example
@end itemize

@sp .25
@noindent
@strong{NOTE:} This command is a toggle; run it again to turn it off.

To correct a word in @code{Flyspell} mode, click and release the middle
mouse button on the word to pull up a menu of suggestions; you then use
the mouse to select the replacement word or add it to your personal
dictionary.

If there are words you frequently misspell, you can define abbrevs for
them (@pxref{Emacs Abbreviations, , Making Abbreviations in
Emacs}). Then, when you type the misspelled word, Emacs will
automatically replace it with the correct spelling.

Finally, if you prefer the sparse, non-interactive interface of
@code{spell}, you can use the Emacs interfaces to that command instead:
@code{Spell word}, @code{Spell region}, and @code{Spell buffer}. When
any of these commands find a misspelling, they prompt for a replacement
in the minibuffer but do not offer suggestions or provide any of
@code{ispell}'s other features.


@node Dictionaries, Checking Grammar, Spelling, Grammar
@comment  node-name,  next,  previous,  up
@section Dictionaries
@cindex dictionaries
@cindex WordNet lexical database
@pindex wn
@pindex wnb

@flushleft
@sf{Debian}: @file{wordnet-dev}
@sf{WWW}: @url{http://www.cogsci.princeton.edu/~wn/}
@end flushleft
@*
@noindent
The term @dfn{dictionary} on Linux systems generally refers to one of
two things: the traditional Unix-style dictionary, which is an
alphabetically sorted word list containing no actual definitions, and
the newer database-style dictionary that contains the headwords as well
as their definitions. The latter is the kind of thing most people mean
when they talk about dictionaries. (When most Unix folk talk about
dictionaries, however, they almost always mean the former.)

WordNet is a lexical reference system in the form of a database
containing thousands of words arranged in synonym sets. You can search
the database and output the results in text with the @code{wn} tool or
the @code{wnb} X client (the ``WordNet browser'').

Use of the X client is fairly straightforward---type a word in the
dialog box near the top of the screen, followed by @key{RET}, to get its
definition(s), which are displayed in the large output window underneath
the dialog box.

For example, this is what appears when you do a search for the
definition of the word @samp{browse}:

@image{grammar-wnb-01, 3 in}

Between the dialog box and the output window, there are menus for
searching for synonyms and other word senses. A separate menu is given
for each part of speech a word may have; in the preceding example, the
word @samp{browse} can be either a noun or a verb, so two menus are
shown.

To get a list of all word sense information available for a given word,
run @code{wn} with the name of the word as an argument. This outputs a
list of all word sense information available for the word, with each
possible sense preceded with the name of the option to use to output it.

@itemize @bullet
@item
To output a list of word senses available for the word @samp{browse},
type:

@example
$ @kbd{wn browse @key{RET}}
@end example
@end itemize

The following sections show how to use @code{wn} on the command line.

@sp .25
@noindent
@strong{NOTE:} For more information on WordNet, consult the
@code{wnintro} @code{man} page (@pxref{Man, , Reading a Page from the
System Manual}).

@menu
* Word Lookup::                 Listing words that match a pattern.
* Definition Lookup::           Looking up a word's definition.
* Synonym Lookup::              Finding Synonyms.
* Antonym Lookup::              Finding Antonyms.
* Hypernym Lookup::             Finding Hypernyms.
* Online Dictionaries::         Free dictionaries on the WWW.
@end menu


@node Word Lookup, Definition Lookup, Dictionaries, Dictionaries
@comment  node-name,  next,  previous,  up
@subsection Listing Words that Match a Pattern
@cindex listing words that match a pattern
@cindex words, listing that match a pattern
@cindex dictionary, searching for words in the
@cindex rhyme, listing words that
@pindex look
@pindex grep
@pindex wn

@noindent
There are several ways to search for and output words from the system
dictionary.

Use @code{look} to output a list of words in the system dictionary that
begin with a given string---this is useful for finding words that begin
with a particular phrase or prefix. Give the string as an argument; it
is not case sensitive.

@itemize @bullet
@item
To output a list of words from the dictionary that begin with the string
@samp{homew}, type:

@example
$ @kbd{look homew @key{RET}}
@end example
@end itemize

This command outputs words like @samp{homeward} and @samp{homework}.

Since the system dictionary is an ordinary text file, you can also use
@code{grep} to search it for words that match a given pattern or regular
expression (@pxref{Regexps, , Regular Expressions---Matching Text
Patterns}).

@itemize @bullet
@item
To list all words in the dictionary that contain the string @samp{dont},
regardless of @w{case, type:}

@example
$ @kbd{grep -i dont /usr/dict/words @key{RET}}
@end example

@item
To list all words in the dictionary that end with @samp{ing}, type:

@example
$ @kbd{grep ing^ /usr/dict/words @key{RET}}
@end example

@item
To list all of the words that are composed only of vowels, type:

@example
$ @kbd{grep -i '^[aeiou]*$' /usr/dict/words @key{RET}}
@end example
@end itemize

To find some words that rhyme with a given word, use @code{grep} to
search @file{/usr/dict/words} for words ending in the same last few
characters as the word they should rhyme with (@pxref{End Match, ,
Matching Lines Ending with Certain Text}).

@itemize @bullet
@item
To output a list of words that rhyme with @samp{friend}, search
@file{/usr/dict/words} for lines ending with @samp{end}:

@example
$ @kbd{grep 'end$' /usr/dict/words @key{RET}}
@end example
@end itemize

Finally, to do a search on the WordNet dictionary, use @code{wn} with
one of the @samp{-grep} options. When you give some text to search for
as an argument, this command does the equivalent search as @code{look},
except only the particular kind of word sense you specify is searched:
@samp{-grepn} searches nouns, @samp{-grepv} searches verbs,
@samp{-grepa} searches adjectives, and @samp{-grepr} searches
adverbs. You can combine options to search multiple word senses.

@itemize @bullet
@item
To search the WordNet dictionary for nouns that begin with @samp{homew},
type:

@example
$ @kbd{wn homew -grepn @key{RET}}
@end example

@item
To search the WordNet dictionary for both nouns and adjectives that
begin with @samp{homew}, type:

@example
$ @kbd{wn homew -grepn -grepa @key{RET}}
@end example
@end itemize


@node Definition Lookup, Synonym Lookup, Word Lookup, Dictionaries
@comment  node-name,  next,  previous,  up
@subsection Listing the Definitions of a Word
@cindex listing the definitions of a word
@cindex word, listing the definitions of a
@cindex definitions, of words
@pindex wn

@noindent
To list the definitions of a word, give the word as an argument to
@code{wn}, followed by the @samp{-over} option.

@itemize @bullet
@item
To list the definitions of the word @samp{slope}, type:

@example
$ @kbd{wn slope -over @key{RET}}
@end example
@end itemize


@node Synonym Lookup, Antonym Lookup, Definition Lookup, Dictionaries
@comment  node-name,  next,  previous,  up
@subsection Listing the Synonyms of a Word
@cindex listing the synonyms of a word
@cindex word, listing the synonyms of a
@cindex synonyms, of words

@noindent
A @dfn{synonym} of a word is a different word with a similar meaning
that can be used in place of the first word in some context. To output
synonyms for a word with @code{wn}, give the word as an argument,
followed by one of the following options: @samp{-synsn} for nouns,
@samp{-synsv} for verbs, @samp{-synsa} for adjectives, and @samp{-sysnr}
for adverbs.

@itemize @bullet
@item
To output all of the synonyms for the noun @samp{break}, type:

@example
$ @kbd{wn break -synsn @key{RET}}
@end example

@item
To output all of the synonyms for the verb @samp{break}, type:

@example
$ @kbd{wn break -synsv @key{RET}}
@end example
@end itemize


@node Antonym Lookup, Hypernym Lookup, Synonym Lookup, Dictionaries
@comment  node-name,  next,  previous,  up
@subsection Listing the Antonyms of a Word
@cindex listing the antonyms of a word
@cindex word, listing the antonyms of a
@cindex antonyms, of words

@noindent
An @dfn{antonym} of a word is a different word that has the opposite
meaning of the first in some context. To output antonyms for a word with
@code{wn}, give the word as an argument, followed by one the following
options: @samp{-antsv} for verbs, @samp{-antsa} for adjectives, and
@samp{-antsr} for adverbs.

@itemize @bullet
@item
To output all of the antonyms for the adjective @samp{sad}, type:

@example
$ @kbd{wn sad -antsa @key{RET}}
@end example
@end itemize


@node Hypernym Lookup, Online Dictionaries, Antonym Lookup, Dictionaries
@comment  node-name,  next,  previous,  up
@subsection Listing the Hypernyms of a Word
@cindex listing the hypernyms of a word
@cindex word, listing the hypernyms of a
@cindex hypernyms, of words

@noindent
A @dfn{hypernym} of a word is a related term whose meaning is more
general than the given word. (For example, the words @samp{mammal} and
@samp{animal} are hypernyms of the word @samp{cat}.)

To output hypernyms for a word with @code{wn}, use one of the following
options: @samp{-hypen} for nouns and @samp{-hypev} for verbs.

@itemize @bullet
@item
To output all of the hypernyms for the noun @samp{cat}, type:

@example
$ @kbd{wn cat -hypen @key{RET}}
@end example
@end itemize


@node Online Dictionaries, , Hypernym Lookup, Dictionaries
@comment  node-name,  next,  previous,  up
@subsection Online Dictionaries
@cindex online dictionaries
@cindex dictionaries, online
@cindex DICT Development Group
@cindex FILE
@cindex Free Journalism Dictionary
@cindex lexicons

@flushleft
@sf{Debian} @file{dict}
@sf{WWW}: @url{http://www.dict.org/}
@end flushleft
@*
@noindent
The DICT Development Group has a number of free dictionaries on their
Web site at @url{http://www.dict.org/}. On that page, you can look up
the definitions of words (including thesaurus and other searches) from a
dictionary that contains over 300,000 headwords, or make a copy of their
dictionary for use on your own system. A @code{dict} client exists for
accessing DICT servers and outputting definitions locally; this tool is
available in the @file{dict} package.

DICT also has a number of specialized dictionaries that are plain text
files (including the author's @cite{Free Journalism Dictionary},
containing jargon and terms used in the journalism and publishing
professions). Their @cite{FILE} project, @cite{The Free Internet Lexicon
and Encyclopedia}, is an effort to build a free, open source collection
of modern-word, idiom, and jargon dictionaries. FILE is a volunteer
effort and depends on the support of scholars and lexicographers; the
DICT pages contain information on how to help contribute to this worthy
project.


@node Checking Grammar, Reference Files, Dictionaries, Grammar
@comment  node-name,  next,  previous,  up
@section Checking Grammar
@cindex checking grammar
@cindex grammar, checking 
@cindex Writer's WorkBench (WBB)
@cindex AT&T UNIX
@cindex Haardt, Michael
@cindex GNU Project
@pindex style
@pindex diction
@pindex look
@pindex spell

@flushleft
@sf{WWW}: @url{http://www.gnu.org/software/diction/diction.html}
@end flushleft
@*
@noindent
Two venerable Unix tools for checking writing have recently been made
available for Linux-based systems: @code{style} and @code{diction}.

Old-timers probably remember these names---the originals came with AT&T
UNIX as part of the much-loved ``Writer's Workbench'' (WWB) suite of
tools back in the late 1970s and early 1980s.@footnote{There was also a
set of tools for formatting text called the ``Documenter's Workbench''
(DWB), and there was a planned ``Reader's Workbench''; we can only guess
at what that might have been, but today we do have
@uref{http://www.gutenbook.org/, Project Gutenbook}, a new etext
reader.}

AT&T ``unbundled'' the Writer's Workbench from their UNIX version 7
product, and as the many flavors of Unix blossomed over the years, these
tools were lost by the wayside---eventually becoming the stuff of Unix
lore.

In 1997, Michael Haardt wrote new Linux versions of these tools from
scratch. They support both the English and German languages, and
they're now part of the GNU Project.

Two additional commands that were part of the Writer's Workbench have
long been standard on Linux: @code{look} and @code{spell}, described
previously in this chapter.

@menu
* Diction::                     Checking for misused phrases.
* Doubled Words::               Checking for doubled words.
* Writing Style::               Checking writing style.
* Difficult Sentences::         Checking for difficult sentences.
* Long Sentences::              Checking for long sentences.
@end menu


@node Diction, Doubled Words, Checking Grammar, Checking Grammar
@comment  node-name,  next,  previous,  up
@subsection Checking Text for Misused Phrases
@cindex checking text for misused phrases
@cindex phrases, checking text for misused 
@cindex text, checking for misused phrases
@cindex diction, checking
@cindex @cite{UNIX Environment, The}
@cindex @cite{Elements of Style}
@cindex Strunk, William
@cindex Walker, Andrew
@pindex diction
@pindex suggest
@pindex less
@pindex lynx

@noindent
Use @code{diction} to check for wordy, trite, clich@'ed, or misused
phrases in a text. It checks for all the kind of expressions William
Strunk warned us about in his @uref{http://coba.shsu.edu/help/strunk/,
@cite{Elements of Style}}.

According to @cite{The UNIX Environment}, by Andrew Walker, the
@code{diction} tool that came with the old Writer's Workbench just
@emph{found} the phrases, and a separate command called @code{suggest}
would output suggestions. In the GNU version that works for Linux
systems, both functions have been combined in the single @code{diction}
command.

In GNU @code{diction}, the words or phrases are enclosed in brackets
@samp{[like this]}. If @code{diction} has any suggested replacements,
it gives them preceded by a right arrow, @samp{-> like this}.

When checking more than just a screenful of text, you'll want to pipe
the output to @code{less} so that you can peruse it on the screen
(@pxref{Perusing Text, , Perusing Text}), or pipe the output to a file
for later examination.

@itemize @bullet
@item
To check file @file{dissertation} for clich@'es or other misused
phrases, type: 

@example
$ @kbd{diction dissertation | less @key{RET}}
@end example

@item
To check file @file{dissertation} for clich@'es or other misused
phrases, and write the output to a file called
@file{dissertation.diction}, type: 

@example
$ @kbd{diction dissertation > dissertation.diction @key{RET}}
@end example
@end itemize

If you don't specify a file name, @code{diction} reads text from the
standard input until you type @kbd{C-d} on a line by itself. This is
especially useful when you want to check a single sentence:

@example
@cartouche
$ @kbd{diction @key{RET}}
@kbd{Let us ask the question we wish to state. @key{RET}}
(stdin):1: Let us [ask the question -> ask]
[we wish to state -> (cliche, avoid)]. 
@kbd{C-d}
$
@end cartouche
@end example

To check the text of a Web page, use the text-only Web browser
@code{lynx} with the @samp{-dump} and @samp{-nolist} options to output
the plain text of a given URL, and pipe this output to @code{diction}.
(If you expect there to be a lot of output, add another pipe at the end
to @code{less} so you can peruse it.)

@itemize @bullet
To peruse a copy of the text of @url{http://example.org/1.html} with
markings for possible wordy and misused phrases, type:
@end itemize

@example
$ @kbd{lynx -dump -nolist http://example.org/1.html | diction | less @key{RET}}
@end example


@node Doubled Words, Writing Style, Diction, Checking Grammar
@comment  node-name,  next,  previous,  up
@subsection Checking Text for Doubled Words
@cindex checking text for doubled words
@cindex doubled words, checking text for
@cindex repeated words, checking text for
@cindex text, checking for doubled words
@pindex diction
@pindex grep

@noindent
One of the things that @code{diction} looks for is doubled words---words
repeated twice in a row. If it finds such a sequence, it encloses the
second member of the doubled pair in brackets, followed by a right arrow
and the text @samp{Double word}, like @samp{this [<i>this -> Double
word.]}.

To check a text file for doubled words @emph{only}, and not for any of
the other things @code{diction} checks, use @code{grep} to find only
those lines in @code{diction}'s output that contain the text
@samp{Double word}, if any.

@itemize @bullet
@item
To output all lines containing double words in the file
@file{dissertation}, type:

@example
$ @kbd{diction dissertation | grep 'Double word' @key{RET}}
@end example
@end itemize


@node Writing Style, Difficult Sentences, Doubled Words, Checking Grammar
@comment  node-name,  next,  previous,  up
@subsection Checking Text for Readability
@cindex checking text for readability
@cindex readability, checking text for
@cindex text, checking for readability
@cindex style, checking
@pindex style

@noindent
The @code{style} command analyzes the writing style of a given text. It
performs a number of readability tests on the text and outputs their
results, and it gives some statistical information about the sentences
of the text. Give as an argument the name of the text file to check.

@itemize @bullet
@item
To check the readability of the file @file{dissertation}, type:

@example
$ @kbd{style dissertation @key{RET}}
@end example
@end itemize

Like @code{diction}, @code{style} reads text from the standard input if
no text is given---this is useful for the end of a pipeline, or for
checking the writing style of a particular sentence or other text you
type.

The sentence characteristics of the text that @code{style} outputs are
as follows:

@itemize @bullet
@item
Number of characters

@item
Number of words, their average length, and their average number of
syllables

@item
Number of sentences and average length in words

@item
Number of short and long sentences

@item
Number of paragraphs and average length in sentences

@item
Number of questions and imperatives
@end itemize

The various readability formulas that @code{style} uses and outputs are
as follows:

@itemize @bullet
@item
Kincaid formula, originally developed for Navy training manuals; a
good readability for technical documentation

@item
Automated Readability Index (ARI)

@item
Coleman-Liau formula

@item
Flesch Reading Ease Score, which gives an approximation of readability
from 0 (difficult) to 100 (easy)

@item
Fog Index, which gives a school-grade reading level

@item
WSTF Index, a readability indicator for German documents

@item
Wheeler-Smith Index, Lix formula, and SMOG-Grading tests, all
readability indicators that give a school-grade reading level
@end itemize


@node Difficult Sentences, Long Sentences, Writing Style, Checking Grammar
@comment  node-name,  next,  previous,  up
@subsection Checking Text for Difficult Sentences
@cindex checking text for difficult sentences
@cindex sentences, checking text for difficult 
@cindex text, checking for difficult sentences
@pindex style

@noindent
To output just the ``difficult'' sentences of a text, use @code{style}
with the @samp{-r} option followed by a number; @code{style} will output
only those sentences whose Automated Readability Index (ARI) is greater
than the number you give.

@itemize @bullet
@item
To output all sentences in the file @file{dissertation} whose
ARI is greater than a value of 20, type: 

@example
$ @kbd{style -r 20 dissertation @key{RET}}
@end example
@end itemize

@node Long Sentences, , Difficult Sentences, Checking Grammar
@comment  node-name,  next,  previous,  up
@subsection Checking Text for Long Sentences
@cindex checking text for long sentences
@cindex text, checking for long sentences
@cindex sentences, checking text for long 
@pindex style

@noindent
Use @code{style} to output sentences longer than a certain length by
giving the minimum number of words as an argument to the @samp{-l}
option.

@itemize @bullet
@item
To output all sentences longer than 14 words in the
file @file{dissertation}, type:

@example
$ @kbd{style -l 14 dissertation @key{RET}}
@end example
@end itemize


@node Reference Files, , Checking Grammar, Grammar
@comment  node-name,  next,  previous,  up
@section Word Lists and Reference Files
@cindex word lists and reference files
@cindex reference files
@cindex GNU Manifesto
@cindex abbreviations, a list of common
@cindex airport city codes
@cindex National Weather Service, city codes for
@cindex ASCII character set
@cindex atlases, online
@cindex telephone codes
@pindex miscfiles

@flushleft
@sf{Debian}: @file{miscfiles}
@sf{WWW}: @url{ftp://ftp.gnu.org/pub/gnu/miscfiles/miscfiles-1.1.tar.gz}
@end flushleft
@*
@noindent
The GNU Miscfiles are a collection of text files containing various
facts and reference material, such as common abbreviations, telephone
area codes, and English connective phrases. 

The files are stored in the @file{/usr/share/misc} directory, and they
are all compressed; use @code{zless} to peruse them (@pxref{Perusing
Text, , Perusing Text}).

The following table lists the files in @file{/usr/share/misc} and
describes their contents.

@multitable @columnfractions .30 .70
@item @sc{File}
@tab @sc{Description}
@item @code{GNU-manifesto.gz}
@tab The GNU Manifesto.

@item @code{abbrevs.talk.gz} @code{abbrevs.gen.gz}
@tab Collections of common abbreviations used in electronic
communication. (This is the place to look to find the secrets of
@samp{TTYL} and @samp{LOL}.)

@item @code{airport.gz}
@tab List of three-letter city codes for some of the major airports. The
city code is useful for querying the National Weather Service computers
to get the latest weather report for your region.

@item @code{ascii.gz}
@tab A chart of the ASCII character set.

@item @code{birthtoken.gz}
@tab The traditional stone and flower tokens for each month.

@item @code{cities.dat.gz}
@tab The population, political coordinates (nation, region), and
geographic coordinates (latitude, longitude) of many major cities.

@item @code{inter.phone.gz}
@tab International country and city telephone codes.

@item @code{languages.gz}
@tab Two-letter codes for languages, from ISO 639.

@item @code{latin1.gz}
@tab A chart of the extended ASCII character set, also known as the ISO
8859 (``Latin-1'') character set.

@item @code{mailinglists.gz}
@tab Description of all the public Project GNU-related mailing lists.

@item @code{na.phone.gz}
@tab North American (+1) telephone area codes.

@item @code{operator.gz}
@tab Precedence table for operators in the C language.

@item @code{postal.codes.gz}
@tab Postal codes for U.S.@: and Mexican states and Canadian provinces.

@item @code{us-constitution.gz}
@tab @cite{The Constitution of the United States of America} (no
@cite{Bill of Rights}, though). (On Debian systems, this file is placed
in @file{/usr/share/state}.)

@item @code{us-declaration.gz}
@tab @cite{The Declaration of Independence of the Thirteen
Colonies}. (On Debian systems, this file is placed in
@file{/usr/share/state}.)

@item @code{rfc-index.txt}
@tab Indexes of Internet standardization Request For Comments (RFC)
documents. (On Debian systems, this file is placed in
@file{/usr/share/rfc}).

@item @code{zipcodes.gz}
@tab U.S.@: five-digit Zip codes.
@end multitable

@file{miscfiles} is not the only reference package available for Debian
systems, though; other related packages include the following:

@multitable @columnfractions .30 .70
@item @sc{Package}
@tab @sc{Description}
@item @code{doc-iana}
@tab Internet protocol parameter registry documents, as published by the
Internet Assigned Numbers Authority.

@item @code{doc-rfc}
@tab A collection of important RFCs, stored in @file{/usr/share/rfc}.

@item @code{jargon}
@tab The ``Jargon file,'' which is the definitive dictionary of hacker
slang.

@item @code{vera}
@tab List of computer acronyms.
@end multitable

@iftex
@page
@end iftex

@sp .25
@noindent
@strong{NOTE:} The official GNU @code{miscfiles} distribution also
includes the Jargon file and the @file{/usr/dict/words} dictionary file,
which are available in separate packages for Debian, and are removed
from the Debian @file{miscfiles} distribution. @file{/usr/dict/words} is
part of the standard spelling packages, and the Jargon file comes in the
optional @file{jargon} package, and installs in
@file{/usr/share/jargon}.