[Next] [Up] [Previous] [Contents]
Next: 4. Library Interface Up: Aspell .26.2 alpha A Previous: 2. Getting Started   Contents

Subsections

3. The Aspell utility

The Aspell utility is a multipurpose utility that can function as a ``ispell -a'' replacement, as an independent spell checker, as a test utility to test out Aspell features, and as a utility for managing dictionaries. Here is a brief summary of Aspell's command line options.

aspell <command> [file] [options]

<command> is one of:

check
to check a file
pipe
'ispell -a' compatible mode.
master
to create a master word list from stdin. The file is the base name of the word list to create
personal
to create a personal word list from stdin. The file is the base name of the word list to create
lang
to create language support code from the language data file
test
to go into a special test mode.
[options] is any or all of the following:

-master <base>
the base name of the master word list to use
-personal <base>
the base name of the personal word list to use
-lang <lang>
the language to use when creating word lists
-replacement <base>
the base name of the replacement dictionary to use
-ignore-repl
-do not store replacements in the replacement dictionary
-reverse
reverse the order of the suggestions list.
In addition Aspell with try to make seance out of Ispell's command line options so that it can function as a drop in replacement for Ispell.

If Aspell is specified with out any command line options it will display a brief help screen and quit.

Aspell will also make use of the the following environmental variables.

HOME
for the location of the personal dictionaries
ASPELL_DATA_DIR
for the location of the master word list. If this variable is not present it will look in <prefix>/lib/aspell/ where <prefix> is determined at compile time. (Usually /usr/local/).

3.1 As a ``ispell -a'' replacement

To actually use Aspell as an Ispell replacement simply follow the directions in section 2.6.

When given the pipe or -a command aspell goes into a pipe mode the is compatible with ispell with a few extra additions.

  
3.1.1 Format of the Data Stream

In this mode, Aspell prints a one-line version identification message, and then begins reading lines of input. For each input line, a single line is written to the standard output for each word checked for spelling on the line. If the word was found in the main dictionary, or your personal dictionary, then the line contains only a '*'.

If the word is not in the dictionary, but there are suggestions, then the line contains an '&', a space, the misspelled word, a space, the number of near misses, the number of characters between the beginning of the line and the beginning of the misspelled word, a colon, another space, and a list of the suggestions separated by commas and spaces.

Finally, if the word does not appear in the dictionary, and there are no suggestions, then the line contains a '#', a space, the misspelled word, a space, and the character offset from the beginning of the line. Each sentence of text input is terminated with an additional blank line, indicating that ispell has completed processing the input line.

These output lines can be summarized as follows:

OK:
*
Suggestions:
& <original> <count> <offset>: <miss>, <miss>, ...
None:
# <original> <offset>
When in the -a mode, Aspell will also accept lines of single words prefixed with any of '*', '&', '@', '+', '-', '~', '#', '!', '%', or '^'. A line starting with '*' tells ispell to insert the word into the user's dictionary. A line starting with '&' tells ispell to insert an all-lowercase version of the word into the user's dictionary. A line starting with '@' causes ispell to accept this word in the future. A line starting with '+', '-', or '~', is ignored for ispell compatibility. A line prefixed with '#' will cause the personal dictionary to be saved. A line prefixed with '!' will turn on terse mode (see below), and a line prefixed with '%' will return ispell to normal (non-terse) mode. Any input following the prefix characters '+', '-', '#', '!', '~', or '%' is ignored, as is any input following. To allow spell-checking of lines beginning with these characters, a line starting with '^' has that character removed before it is passed to the spell-checking code. It is recommended that programmatic interfaces prefix every data line with an uparrow to protect themselves against future changes in Aspell.

To summarize these:

* <word>
Add a word to the personal dictionary
& <word>
Insert the all-lowercase version of the word in the personal dictionary
@ <word>
Accept the word, but leave it out of the dictionary
#
Save the current personal dictionary
~
Ignored
+
Ignored
-
Ignored
!
Enter terse mode
%
Exit terse mode
^
Spell-check the rest of the line
In terse mode, Aspell will not print lines beginning with '*', which indicate correct words. This significantly improves running speed when the driving program is going to ignore correct words anyway.

In addition to the above commands which are designed for Ispell compatibility Aspell also supports its own extension. All Aspell extensions follow the following format.

$$<command> [data]
Where data may are may not be required depending on the particular command. Aspell currently supports the following command.

s <word1>,<word2>
Returns the score of the two words based roughly on how aspell would score them.
Sw <word>
Returns the soundlike equivalent of the word.
Sl <word>
Returns a list of words that have the same soundlike equivalent.
Pw <word>
Returns the phoneme equivalent of the word.
pp
Returns a list of all words in the current personal wordlist.
ps
Returns a list of all words in the current session dictionary.
l
Returns the current language name.
ra <mis>,<cor>
Add the word pair to the replacement dictionary for latter use. Returns nothing.
ric
Returns the status of the ignore_replacements flag which will either be a 1 or a 0.
ri0
Sets the ignore_replacement flag to false (the default). Returns nothing.
ri1
Sets the ignore_replacement flag to true. Returns nothing.
Anything returned is returned on its own line line. All lists returned have the following format

<num of items>: <item1>, <item2>, <etc>
(Note: part of this section was directly copied out of the Ispell manual)

3.2 As an independent spell checker

To use Aspell as an independent spell checker type

aspell check <filename>
Where <filename> is the file you want to check. Aspell will create a new file named <filename>.checked with the corrections and the original file is untouched.

3.3 As a test utility to test out Aspell features

In Aspell's test mode you can test out Aspell's individual features as well and get some idea if the speed at which aspell runs. To go into test mode simply type

aspell test

3.4 As a utility for managing word lists

Normally the word list is automatically created for you when you type make however if you wish to use your own you will need to use aspell to probably prepare it. The format for the command is:

aspell master <base> or

aspell personal <base>
where <base> is the root name of the word list to be created. Unless you have a special reason it should be ``english''. Aspell gets it word list from stdin. For example the make creates the default word list with the command:

aspell master english < english.wl
Once the word list is created you need to move the files <base>.wrd and <base>.mta to a place where Aspell can find it. This is normally /usr/local/share/aspell.

The personal dictionary can be created in almost the same way except that the file is named <base>.per and it should be either in the current directory or the users home directory in order for Aspell to find it. Unless you have a good reason <base> should normally be ``.aspell''.

Please note that Aspell currently does not currently support any affix compression like Ispell does. Thus Ispell's word list will not work as is. In order to use Ispell's word lists simply pipe the word list through ``ispell -e'' (or ispell.real -e if you renamed it) to expand the munched word lists.

3.5 As a utility for creating language support code

See section 5.2.1.


[Next] [Up] [Previous] [Contents]
Next: 4. Library Interface Up: Aspell .26.2 alpha A Previous: 2. Getting Started   Contents

1999-01-04