Next: 4. Library Interface Up: Aspell .28.3 alpha A Previous: 2. Getting Started Contents
Subsections

- 3.1 As a ``ispell -a'' replacement
  - 3.1.1 Format of the Data Stream
    - 3.1.1.1 Notes of Storing Replacement Pairs
- 3.2 As an independent spell checker
- 3.3 As an utility to manage word lists

# 3. The Aspell utility

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

> aspell [options] «command»

«command» is one of:

check «file»
  to check a file
pipe
  'ispell -a' compatible mode.
dump config
  dump the current configuration to stdout
dump|create|merge maser|personal|repl [word list]
  dumps, creates, or merges a master, personal, or replacement word list.

[options] is any or all of the following standard aspell library options:

-d, --master=«base»
  main word list base name
-p, --personal=«file»
  personal word list file name
--repl=«file»
  replacements list file name
--lang=«lang»
  default language to use
--dict-dir=«dir»
  location of the main word list
--data-dir=«dir»
  location of language data files
--[dont-]ignore-repl
  [don't] ignore commands to store replacement pairs
--conf=«file»
  main configuration file
--conf-dir=«dir»
  location of main configuration file

in addition to

--reverse
  reverse the order of the suggestions list.
-b --backup
  create a backup file by appending ``.bak'' to the file name. (Only applies when the command is check)
-x --dont-backup
  don't create a backup file

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 when used is ``-a'' mode.

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

Aspell can also make use of a global or user configuration file. Each line of the configuration file has the format:

  `«option» [args]`

where option is any one of the standard library options above without the leading dashes. For example the following line will set the default language to German:

  `lang german`

Anything from a ``#'' to a newline is ignored. The global configuration file is usually named ``aspell.conf'' and is found in the etc directory while the user configuration file is usually named ``.aspell.conf'' and is found in the users home directory. Use ``aspell dump config'' to found out what they are for your installation.

The environmental variable ASPELL_CONF may also be used and it overrides any options set in the configuration file. The format of the string is exactly the same as the configuration file except that semicolons ( ; ) are used instead of newlines.

# 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 or may not be required depending on the particular command. Aspell currently supports the following command.

m which
  Print out the current mode
m none
  Do not use any special mode.
m url
  Enter email, URL, and host name skipping mode.
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.1.1.1 Notes of Storing Replacement Pairs

As of version .27 of Aspell storing replacements pairs has a memory. Which means if you first store the replacement pair:

> sicolagest -> psycolagest

then store the replacement pair

> psycolagest -> psychologist

The replacement pair

> sicolagest -> psychologist

will also get stored so that you don't have to worry about it.

# 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 an utility to manage word lists

To create the main word list from a list of words use the command

> aspell --lang=«lang» create master ./«base» < «wordlist»

where «base» is the name of the word list and «word list» is the list of words seperated by white space. The ``./'' is important because without it aspell will create the word list in the normal word list directory.

This will create two files in the current directory. To use the new word list copy the files to the normal word list directory (use ``aspell dump config'' to find out what it is) and use the option --master=«base».

A personal and replacement word list can be created in a similar fashion.

Please note that Aspell currently does not support any sort of 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'' to expand the munched word lists.

The replacement word has each replacement pair on its own line in the following format

  `«misspelled word»: «correction»`

The dump command will simply dump the contents of a word list to stdout in a formate than can be read back in with aspell create.

If no word list is specified the command will act on the default one. For example the command

> aspell dump master

will simply dump the contents of the current master word list to stdout.

Next: 4. Library Interface Up: Aspell .28.3 alpha A Previous: 2. Getting Started Contents