Next: Dumping Configuration Values, Previous: Specifying Options, Up: Customizing Aspell [Contents]

### 4.2 The Options

The following is a list of available options broken down by category. Each entry has the following format:

> option[,single-letter-abbreviation]

>   (type) description

Where single letter options are specified as they would appear at the command line, ie with the preceding dash. Boolean single letter options are specified in the following format:

> -<abbreviation to enable>|-<abbreviation to disable>

option is one of the following: boolean, string, file, dir, integer, or list.

String, file, dir, and integer types are all value options which can only take a specific type of value.

#### 4.2.1 Dictionary Options

The following options may be used to control which dictionaries to use and how they behave (for more information see How Aspell Selects an Appropriate Dictionary):

master,-d

  (string) Base name of the dictionary to use. If this option is specified then Aspell will either use this dictionary or die.

dict-dir

  (dir) Location of the main word list.

lang

  (string) Language to use. It follows the same format of the `LANG` environment variable on most systems. It consists of the two letter ISO 639 language code and an optional two letter ISO 3166 country code after a dash or underscore. The default value is based on the value of the `LC_MESSAGES` locale.

size

  (string) The preferred size of the word list. This consists of a two char digit code describing the size of the list, with typical values of: 10=tiny, 20=really small, 30=small, 40=med-small, 50=med, 60=med-large, 70=large, 80=huge, 90=insane.

variety

  (list) Any extra information to distinguish two different words lists that have the same lang and size.

word-list-path

  (list) Search path for word list information files.

personal,-p

  (file) Personal word list file name.

wordlists

  (list)

  UTF-8 files of additional words to accept. Non-word characters will be removed from the start and end of each word and if the word is then considered valid for the current language it will be added. Otherwise it will be silently ignored.

  The `--dont-clean-words` option can be used to prevent the removal of non-word characters. The `--dont-skip-invalid-words` can be used to try harder to accept the word; if a word contains a character that the language can’t handle it will still be ignored (for example a Cyrillic letter in a Latin based language).

  If words are not being added that you expect to, use the `aspell clean` to find out why.

repl

  (file) Replacements list file name.

extra-dicts

  (list) Extra dictionaries to use.

dict-alias

  (list) create dictionary aliases. Each entry has the form ‘`from to`’. Will override any system dictionaries that are present.

dont-use-other-dicts

  (boolean)

  Disable use of personal, replacement & session dictionaries. Any dictionaries specified using ‘`extra-dicts`’ will still be used.

#### 4.2.2 Encoding Options

These options control the encoding the document is expected to be in and how it is displayed.

encoding

  (string) The encoding the input text is in. Valid values include, but not limited to, ‘`iso-8859-*`’, ‘`utf-8`’, ‘`ucs-2`’, ‘`ucs-4`’. When using the Aspell utility the default encoding is based on the current locale. Thus if your locale currently uses the ‘`utf-8`’ encoding than everything will be in UTF-8. The ‘`ucs-2`’ and ‘`ucs-4`’ encodings are intended to be used by other programs using the Aspell library and is not supported by the Aspell utility.

normalize

  (boolean) Perform Unicode normalization. Enabled by default.

norm-strict

  (boolean) Avoid lossy conversions when normalizing. Lossy conversions includes compatibility mappings such as splitting the letter ‘`OE`’ (U+152) into ‘`O`’ and ‘`E`’ (when the combined letter is not available), and mappings which will remove accents. Disabled by default except when creating dictionaries.

norm-form

  (string) The normalization form the output should be in. This option primarily effects the normalization form of the suggestions as when spell checkering as the actual text is unchanged unless there is an error. Valid values are ‘`none`’, ‘`nfd`’ for fully decomposition (Normalization Form D), ‘`nfc`’ for Normalization Form C, or ‘`comp`’ for fully composed. ‘`comp`’ is like ‘`nfc`’ except that full composition is used rather than canonical composition. The `normalize` option must be enabled for this option to be used.

norm-required

  (boolean) Set to true when the current language requires Unicode normalization. This is generally the case when private use characters are used internally by Aspell or when Normalization Form C is not the same as full composition.

#### 4.2.3 Checker Options

These options control the behavior of Aspell when checking documents.

ignore,-W

  (integer) Ignore words with N characters or less

ignore-repl

  (boolean) Ignore commands to store replacement pairs.

save-repl

  (boolean) Save the replacement word list on save all.

keyboard

  (file) The base name of the keyboard definition file to use (see Notes on Typo-Analysis)

sug-mode

  (mode) Suggestion mode = ‘`ultra`’ | ‘`fast`’ | ‘`normal`’ | ‘`slow`’ | ‘`bad-spellers`’ (see Notes on the Different Suggestion Modes)

sug-split-char

  (list) Characters to use when a word into two in the suggestion list. Setting this option to the empty list disables word splitting.

ignore-case

  (boolean) Ignore case when checking words.

ignore-accents

  (boolean) Ignore accents when checking words – currently ignored.

#### 4.2.4 Filter Options

These options control Aspell’s filters that filter out text that should not be spell checked.

mode

  (string) Sets the filter mode. A mode is a collection of individual filters that work well together. Possible values include, but not limited to, ‘`none`’, ‘`url`’ (the normal default), ‘`email`’, ‘`markdown`’, ‘`html`’, ‘`tex`’, `texinfo`, or ‘`nroff`’ (default for ‘`aspell pipe`’). For a complete list use ‘`aspell dump modes`’.

  The shortcut options `-e` may be used for email, `-H` for HTML, `-M` for Markdown, `-t` for TeX, or `-n` for Nroff.

filter

  (list) Individual filters to use, use ‘`aspell dump filters`’ for a complete list.

filter-path

  (list) Where to look when loading filter and filter modes.

#### 4.2.4.1 None filter mode

The `none` mode is exactly what it says. It turns off all filters.

#### 4.2.4.2 URL filter

The `url` filter/mode skips over URLs, host names, and email addresses. Because this filter is almost always useful and rarely does any harm it is enabled in all modes except `none`. To turn it off either select the `none` mode or use `rem-filter` option after the desired mode is selected.

#### 4.2.4.3 Email filter

The `email` mode skips over quoted text.

email-quote

  (list) Email quote characters. Defaults to ‘`>`’ and ‘`|`’.

email-margin

  (integer) The number of characters that can appear before the quote character. Defaults to 10.

#### 4.2.4.4 Markdown Filter

The `markdown` filter/mode skips over code and links in Markdown documents. The mode also handles HTML via the `html` filter which runs after the Markdown filer.

Properly parsing Markdown requires reading the entire document in at once, which doesn’t fit well into the existing filter framework so the filter parses the document a line at a time and makes a best guess when a line ends without enough information to correctly parse a a tag. For example in the following:

    `This looks like inline code

    But it's not, becuase the of the blank line.

the first line will be incorrectly skipped.

markdown-multiline-tags

  (boolean) Enables or disables support for HTML tags that might span multiple lines (outside of HTML blocks). Enabled by default (to disable from the command line use ‘`--dont-markdown-multiline-tags`’).

markdown-skip-ref-labels

  (boolean) Controls if ref lables are skipped. For example, when this option is enabled ‘`[ref]`’ will be skipped over in:

      [link][ref]

      [ref]: #c2 "Chapter 2"

  Enabled by default (to disable from the command line use ‘`--dont-markdown-skip-ref-labels`’).

The Markdown filter also supports the `markdown-raw-start-tags` and `markdown-block-start-tags` list options. These options are a list of HTML tags that start an HTML block. If the block starts with a tag listed in `markdown-raw-start-tags` then the block ends with the corresponding closing tag. If the block starts with a tag listed in `markdown-block-start-tags` then the block ends with a blank line. The defaults for these two options are taken from the CommonMark spec (version 0.29, 2019-04-06).

#### 4.2.4.5 SGML filter

The SGML filter allows you to spell check SGML, HTML, XHTML, and XML files. In most cases everything within a tag ‘`<tag attrib=value attrib2="a whole sentence">`’ will be skipped by the spell checker. The SGML/HTML/XML that Aspell supports is a slight superset of most DTDs (Document Type Definitions) and can spell check the often non-conforming HTML found on the web.

This filter will also translate SGML characters of the form ‘`&#num;`’. Other SGML characters such as ‘`&amp;`’ will simply be skipped over so that the word ‘`amp`’, for example, will not be spell checked. Eventually full support for properly translating SGML characters will be added.

sgml-skip

  (list) tags whose contents will also be skipped by the spell checker. For example, if you wish to leave a misspelling in a document and not have them flagged as misspellings, you could surround them with a <nospellcheck> tag:

        <TD><FONT size=2><NOSPELLCHECK>leviosa</NOSPELLCHECK>
        is what Mr. Potter said</FONT></TD>

  And put that word in the skip config directive:

      add-sgml-skip nospellcheck

sgml-check

  (list) attributes whose values you do want spell checked. By default, ’alt’ (<img> alternate text) is a member of the check list since it is text that is seen by a web page viewer. You may also want ’value’ to be on the check list since that is the text put on buttons:

      add-sgml-check value

  In this case ‘`<input type=button value="Donr">`’ will be flagged as a misspelling.

#### 4.2.4.6 HTML filter

The `html` filter is like the SGML filter but specialized for HTML.

html-check

  (list) HTML attributes to always check, such as alt= (alternate text).

html-skip

  (list) HTML tags to always skip the contents of, such as <script>. Defaults to ’script’ and ’style’.

#### 4.2.4.7 TeX/LaTeX Filter

The `tex` (all lowercase) filter hides TeX/LaTeX commands and corresponding parameters that are not readable text in the output from Aspell. It also skips over TeX comments by default.

tex-command

  (list) Controls which TeX commands should have certain parameters and/or options also skipped over. Commands that are not specified will have all their parameters and/or options checked. The format for each item is

      <command> <a list of p,P,o and Os>

  The first item is simply the command name. The second item controls which parameters to skip over. A ’p’ skips over a parameter while a ’P’ doesn’t. Similarly an ’o’ will skip over an optional parameter while an ’O’ doesn’t. The first letter on the list will apply to the first parameter, the second letter will apply to the second parameter etc. If there are more parameters than letters Aspell will simply check them as normal. For example the option

      add-tex-command rule pp

  will skip over the first two parameters of the `rule` command while the option

      add-tex-command foo Pop

  will check the first parameter of the `foo` command, skip over the next optional parameter, if it is present, and will skip over the second parameter — even if the optional parameter is not present — and will check any additional parameters.

  A ‘`*`’ at the end of the command is simply ignored. For example the option

      add-tex-command enlargethispage p

  will ignore the first parameter in both `enlargethispage` and `enlargethispage*`.

  The defaults are designed to work well with typical LaTeX documents. Use ‘`aspell --reset-tex-command config tex-command`’ for the current defaults.

tex-check-comments

  (boolean) Check TeX comments. Defaults to false.

#### 4.2.4.8 Texinfo Filter

The `texinfo` filter allows you to spell check Texinfo files. It will skip over Texinfo commands and their parameters when appropriate. It will also skip over some Texinfo environments such as `example`.

The Texinfo filter has special code to deal with the `@table` and related commands. It will apply the formatting command to each of the `@item` or `@itemx` commands just like Texinfo will. This means that if the formatting command is `@code` and and the `@code` command is a member of the `texinfo-ignore` option than the Texinfo filter will ignore the parameter of the `@item` command as if the parameter was also the parameter of the `@code` command.

The Texinfo filter will also skip over the ‘`\input texinfo`’ line.

texinfo-ignore

  (list) Texinfo command to ignore the parameters of.

texinfo-ignore-env

  (list) Texinfo environments to ignore.

#### 4.2.4.9 Nroff Filter

The `nroff` filter mode allows you to check the spelling of Nroff documents. It is enabled by default when ‘`aspell pipe`’ is used. When checking documents with ‘`aspell check`’ it is automatically enabled if the first three characters of the file being checked are `.\"` (a `nroff` comment marker) or the file name ends in a one of the following suffixes:

- single decimal digit from ‘`0`’ to ‘`9`’
- letter ‘`n`’
- ‘`tmac`’

This filter mode skips following `nroff` language elements:

- Comments
- Requests
- Names of `nroff` registers (both traditional two-letter names and GNU nroff long names)
- Arguments to the following requests: `ds`, `de`, `nr`, `do`, `so`.
- Arguments to font switch (`\f`) and size switch (`\s`) escapes
- Arguments to extended charset escape in both traditional (`\(`) and extended (`\[comp1 comp2 …]`) form.

#### 4.2.4.10 Context Filter

The `context` filter can be used to spell check source codes, HTML sources and other texts which consist of different contexts. Because this filter is meant to build other filter modes, there is no `context` mode.

The filter distinguishes between visible and invisible contexts. The visible ones will be spell checked and the invisible ones will be ignored.

context-visible-first

  (boolean) Switches the context which should be visible to Aspell. When false (the default) the initial context is hidden and only delimited ones are visible. When true the initial context is visible while the delimited ones are hidden.

context-delimiters

  (list) The context delimiters specified as a space separated pairs. To indicate that a context is always closed by end of line use ‘`\0`’ sequence as closing delimiter. For example the defaults (for historical reasons) are:

        add-context-delimiters /* */
        add-context-delimiters // \0
        add-context-delimiters " "

  which (when `context-visible-first` is false) spell check C/C++ comments and string literals.

#### 4.2.4.11 Ccpp Filter Mode

The `ccpp` filter mode is a context filter that will limit spell checking to C/C++ comments and string literals. Any code in between will be left alone.

#### 4.2.5 Compound Word Options

These may be used to control the behavior of compound words (for more information see Controlling the Behavior of Compound Words):

run-together,-C|-B

  (boolean) consider run-together words valid

run-together-limit

  (integer) maximum number of words that can be strung together

run-together-min

  (integer) minimal length of interior words

camel-case

  (boolean) consider camelCase words valid

#### 4.2.6 Miscellaneous Options

Miscellaneous other options that don’t fall under any other category

conf

  (file) Main configuration file. This file overrides Aspell’s global defaults.

conf-dir

  (dir) location of main configuration file

data-dir

  (dir) location of language data files

local-data-dir

  (dir) alternative location of language data files. This directory is searched before `data-dir`. It defaults to the same directory the actual main word list is in (which is not necessarily `dict-dir`)

home-dir

  (dir) location for personal files

per-conf

  (file) personal configuration file. This file overrides options found in the global `conf` file

keyboard

  (file) use this keyboard layout for suggesting possible words. These spelling errors happen if a user accidently presses a key next to the intended correct key. The default is keyboard standard. If you are creating documents, you may want to set it according to your particular type of keyboard. If spellchecking documents created elsewhere, you might want to set this to the keyboard type for that locale. If you are not sure, just leave this as standard

prefix

  (dir) prefix directory

set-prefix

  (boolean) set the prefix based on executable location (only works on WIN32 and when compiled with `--enable-win32-relocatable`)

#### 4.2.7 Aspell Utility Options

backup,-b|-x

  (boolean) Create a backup file by appending `.bak` to the file name. This applies when the command is `check` and the backup file is only created if any spelling modifications take place.

time

  (boolean) Time load time and suggest time in `pipe` mode.

byte-offsets

  (boolean) Use byte offsets instead of character offsets in `pipe` mode.

reverse

  (boolean) Reverse the order of the suggestions list in `pipe` mode.

keymapping

  (string) the keymapping to use. Either `aspell` for the default mapping or `ispell` to use the same mapping that the Ispell utility uses.

guess

  (boolean) make possible root/affix combinations not in the dictionary in `pipe` mode.

suggest

  (boolean) Suggest possible replacements in `pipe` mode. If false Aspell will simply report the misspelling and make no attempt at suggestions or possible corrections.

Next: Dumping Configuration Values, Previous: Specifying Options, Up: Customizing Aspell [Contents]