Advantages For Debian Users

• Correct selection of available dictionaries by applications.

• Consistent, simpler, management of multiple dictionaries, for e.g. multiple languages and/or multiple specialties.

• Single question at ispell dictionary or wordlist installation time, via debconf.

• Consistent ways for administrators and users to select from among the available ispell-dictionaries and wordlists for system-wide default, user default and individual application session default.

Advantages For Debian Package Maintainers

• Easier package configuration.

• Fewer bug reports.

• Better integration of wordlists and spelling dictionaries.

Quick checklist for the impatient maintainer

• If you maintain an ispell dictionary or wordlist package you must install the package dictionaries-common. This package will conflict with all old style ispell dictionary or wordlist packages. Since from this policy on ispell hash files should be 128 character per string it will also conflict with older ispell packages. If you use debhelper and want to use the debhelper like scripts you must also install package dictionaries-common-dev.

• There is no need to change the name of your package for ispell dictionary or wordlist packages. You however have to take care with one thing; since all such packages conforming to this policy will replace the old packages and pre-depend on the package dictionaries-common, you need to notify the dictionaries-common maintainer which one will be the last version of your package(s) not using the new policy. That versioned conflict will be added to the dictionaries-common package and after that your new policy compliant package can be used.

  For myspell dictionary packages however you have to rename your existing package if it followed the old "OpenOffice.org Spellcheck Packages Packaging Guide". You have to rename openoffice.org-spellcheck-<langcode> to myspell-<langcode>

• Set the correct dependency relationships as in the Section called Relationships.

• Verify the architecture and priority level in debian/control (see the Section called Choice of Architecture and Priority Level).

• Be sure that you are installing the correct files and symlinks in /usr/lib/ispell/, /usr/share/myspell/ or /usr/share/dict/. (see the Section called Installation Directories and Symlinks).

• Update the maintainer maintainer scripts.

  • First of all you need to have an info-{ispell,wordlist} or for myspell just a file conforming to the specified in the Section called The info file.

    If you are a happy debhelper user, all you have to do is to call installdeb-{ispell,wordlist} (it internally calls dh_installdebconf, so do not call it again) in debian/rules You will need to install the dictionaries-common-dev package first in order to have the new debhelper scripts available. Unless you need extra features in your maintainer scripts or extra templates you are done. Otherwise, take a look at the Section called The config file or the Section called The templates file. There is no script like that necessary for myspell dictionary package although one exist which could be used.

  • If you are not building your package with debhelper, you should set up things by hand. We strongly suggest you to migrate your package to debhelper to take advantage of the helpers provided by the system, but you can do things without using debhelper:

    • Change the debian/{postinst,prerm} scripts according to the Section called Maintainer Scripts for ispell dictionaries and wordlists.

    • Add debconf support (files debian/{templates,config} as described in the Section called Ispell Dictionary and wordlist selection Support via Debconf).

    • Create and install the info file (See the Section called The info file).

• If you are packaging a ispell dictionary, you no longer need to add an emacsen startup file. It will be automatically generated from the info file once all the dictionaries are installed.

• Rebuild and test that everything is working O.K. When adding a new ispell dictionary or wordlist package debconf will query for the default selection. When removing or purging a package containing the default selection that query will be done again unless only one package of his class is left. Also check that the emacs menu(s) corresponding to your package displays properly. If not, look at the info file and at your package entries in the autogenerated file at /var/cache/dictionaries-common/emacsen-ispell-dicts.el

• Upload.

System wide configuration

Besides the debconf configuration at installation time, there will be a /usr/sbin/select-default-(ispell|wordlist) script available to the system administrator (in /usr/sbin/) that will call the debconf question at any time and will be responsible to set the appropriate links /usr/lib/(ispell|words)/default.*. This scripts are included in the dictionaries-common package.

Ispell wrapper

A ispell wrapper command will be made available by dictionaries common. This command will accept all the ispell options plus -L <language>, where language must correspond to one of the languages installed in the system (Perl regular expressions will be probably available here, such that calling ispell-wrapper -L ".*brasil.*" will select "Português Brasileiro").

An interactive selection script (select-default-iwrap) will also be available. This is an interactive selection script for selecting the user-specific default ispell dictionary for ispell-wrapper. The result will be placed in ~/.default-ispell.

The system wide default value for ispell-wrapper will be the globally selected one at installation time or through select-default-ispell.

These are included in the dictionaries-common package.

Add-on support

Emacsen, jed and mutt add-on support will be fully auto-generated by the update-default-(ispell|wordlist) script.

Do not add emacs or jed startup files to your package. That will surely interfere with the autogenerated system and be the major source for problems.

Naming of Language-specific ispell dictionary and wordlist Packages

Language-specific ispell dictionary packages and wordlists must be named the classical way, like "ifrench", "wfrench", "iswedish", etc. Use of non-English language names is discouraged; for example "ingerman" should not be named "indeutsch". (This is based on existing practice, and is for consistency and the convenience of Debian administrators in all languages.)

Dictionary sources may provide multiple dictionaries. Each of the binary packages can contain more than one dictionary. In this case, the maintainer must provide info entries for each dictionary in the package info file (see the Section called The info file).

Naming of Language-specific myspell dictionary Packages

myspell dictionary packages must be called myspell-<isocode> (<isocode> being the two-digit isocode of the language).

If there are more dictionaries for a language (e.g. de_DE, de_CH, ..) then the packages can be called myspell-<langcode>-<countrycode> too..

Relationships

The package relationships declared in the debian/control files should be as follows for ispell dictionary or wordlist packages:

• All ispell dictionary or wordlist packages have to depend on dictionaries-common in their debian/control files.

  Every ispell dictionary or wordlist package using the helpers from dictionaries-common-dev has also to declare

  Build-Depends: debhelper, dictionaries-common-dev

  to make autobuilders, lintian and debuild happy.

  They must also provide the appropriate virtual package ("ispell-dictionary" or "wordlist").

• Ispell dictionaries must depend on ispell. If your package uses ispell during the building process you must also set the appropiate build dependency.

• Each ispell dictionary package should suggest the corresponding wordlist package. (This is because ispell can use wordlists in addition to ispell dictionaries, but doesn't actually require them.)

• The dictionaries-common package suggests ispell. (A stronger relationship was considered and rejected, because users might want some wordlists and not want ispell.)

• The ispell package depends on ispell-dictionary and recommends wordlist.

• Packages containing tools that can use ispell (editors, MUA, etc.) may suggest or recommend ispell, but should not depend on ispell.

• Packages that use ispell and allow users to select or specify (from within the running application) which dictionary to use, should depend on dictionaries-common and should invoke an appropriate dictionaries-common dictionary-selection interface as documented in the Section called Ispell Dictionary and wordlist selection Support via Debconf).

For myspell dictionary packages the relationships in debian/control should be as follows:

• the myspell dictionary packages must depend on dictionaries-common (>= 0.10) because in that revision the myspell support was added.

• the myspell-<isocode> package must provide the virtual packages myspell-dictionary and myspell-dictionary-<isocode>

• the packages should declare a Suggests: on openoffice.org (>= 1.0.3-3) and the mozilla flavours in Debian supporting it (currently mozilla-browser[-snapshot] and mozilla-thunderbird) Moreover, it must Conflict: against openoffice.org (<= 1.0.3-2)

• The myspell packages having an "old" version named openoffice.org-spellcheck-* (rgardless of whether that was in Debian once or not) must declare the magic Conflicts: / Provides: / Replaces: combination "against" the old package.

The info file

All ispell dictionary or wordlist packages must install a file /var/lib/dictionaries-common/(ispell|wordlist)/<package-name>. General format of that file (reminiscent of the RFC 822 format) is, including all possible entries for ispell and wordlist packages:

Language: português brasileiro (Brazilian Portuguese) 
Hash-Name: brazilian
Emacsen-Name: brasileiro
Casechars: [a-záéíóúàèìòùãõçüâêôA-ZÁÉÍÓÚÀÈÌÒÙÃÕÇÜÂÊÔ]
Not-Casechars: [^a-záéíóúàèìòùãõçüâêôA-ZÁÉÍÓÚÀÈÌÒÙÃÕÇÜÂÊÔ]
Otherchars: [---']
Many-Otherchars: yes
Additionalchars: áéíóúàèìòùãõçüâêôÁÉÍÓÚÀÈÌÒÙÃÕÇÜÂÊÔ
Ispell-Args: 
Extended-Character-Mode: 
Coding-System: iso-8859-1
      

adapted to the corresponding language and ispell dictionary or wordlist package.

Each field in this file must be contained in a single line. They may also have the right side (i.e., after the character ":") empty, which is equivalent to suppressing the field (the default value will be used in this case, see below).

Several records as the above may be present in each file and must be separated by a blank line. They can correspond to different dictionaries or to different ways of accessing the same dictionary from ispell wrapper or emacs (this will have no effect for use of plain ispell). They must have unique values for the Language field.

The records supplied by each dictionary package will be used by the core of dictionaries-common to provide site-wide configuration, including Debconf list of choices, ispell/wordlist default symlinks, automatic generation of add-on support (emacsen, jed and mutt). This file is therefore essential for the correct integration of the dictionary packages into the dictionaries-common scheme.

Here is an explanation of the fields shown above:

• Language: (this field is mandatory)

  Comprehensive description of the language. It is advised to include both the description in the original language (in UTF-8 coding system) and a description in English between parentheses. This will help the system administrators around the world, who does not now how the dictionaries are spelled in their original language. You need to use UTF-8 for this string, because otherwise it will not be displayed (will display an empty value) in UTF-8 systems. The drawback is that 8bit characters will display strangely in a non UTF-8 terminal, but it will still be readable.

  This field will be used in the Debconf list of choices as well as a key for determining the language default for the ispell-wrapper utility. Hence, it has to be unique among all the installed dictionaries in the system.

• Hash-Name: (this field is mandatory)

  Base name of the files that will appear as symlinks in both /usr/lib/ispell or /usr/share/dict. Has to be unique among the installed dictionaries in the system.

• Emacsen-Name: (optional, defaults to Hash-Name)

  Entry name of the dictionary that appears in the list of choices of the emacsen ispell package. Maintainers should try to respect the tradition of that package, by keeping the name that they used to have in the past.

• Casechars: (optional, defaults to [a-zA-Z])

  Emacs-Lisp regular expression of valid characters that comprise a word. It is typically enclosed between square brackets.

• Not-Casechars: (optional, defaults to [^a-zA-Z])

  Opposite regexp of Casechars.

• Otherchars: (optional, defaults to ['])

  Regexp of characters in the Not-Casechars set but which can be used to construct words in some special way. (See the ispell.el documentation for details.)

• Many-Otherchars: (optional, default value no)

  Boolean variable (assuming either the values yes or no). If it is non-nil when multiple Otherchars are allowed in a word. Otherwise only a single Otherchars character is allowed to be part of any single word.

• Additionalchars: (optional, defaults to an empty string)

  Characters other than ASCII that may be part of a word. This is somehow redundant with the Casechars field, but is necessary for the proper working of the -w option to ispell.

• Ispell-Args: (optional, defaults to -d <Hash-Name>)

  List of additional arguments passed to the ispell.

• Extended-Character-Mode: (optional, defaults to the empty string)

  Set when dictionaries are used which have been configured in an ispell affix file. (For example, umlauts can be encoded as \"a, a", "a, ...)

• Coding-System : (optional, defaults to the empty string)

  Used for languages with multibyte characters. Any coding system will be accepted if the {x}emacs version being run accepts it. Maintainers, please check that the provided coding system works with the different emacsen flavours. If the coding system is not one of iso-8859-1, iso-8859-2, iso-8859-3 or koi8-r make your package depend on at least dictionaries-common (>=0.24), where the other encodings were allowed.

  Warning

  At the time of this writing there are some encoding unification problems in emacs between iso-8859-1 and iso-8859-15 charsets, being the same character represented differently in the emacs internal mule encoding. For this reason please do not blindly replace the old iso-8859-1 entry by iso-8859-15. If you require the iso-8859-15 encoding, better add a new emacs only iso-8859-15 entry (see debconf-display: no) as a temporary workaround. This way the iso-8859-1 entry will work with iso-8859-1 and UTF-8 texts and fail with iso-8859-15, while the new iso-8859-15 entry will work with iso-8859-15, but will fail with iso-8859-1 and UTF-8. The same might also apply to other charsets, please doublecheck.

• {debconf,emacs,jed}-display : (optional, defaults to yes)

  If "emacs-display" or "jed-display" are set to "no", the corresponding entry will not be displayed by emacs or jed when building the cache files. Needs a versioned dependency on dictionaries-common.

  If "debconf-display" is set to "no", this entry will not be added by installdeb-ispell to the debconf template with the possible values of choice. It will remain available to ispell-wrapper and emacs/jed unless "{emacs,jed}-display" are set to no. Needs a versioned build dependency on dictionaries-common-dev

• aspell-locales : (aspell only, optional, no default)

  Comma separated list that represents the set of locales associated to the aspell dictionary to try guessing the emacs ispell.el default aspell dictionary after the contents of the LANG environment variable. When there is no possible confusion the two digits language iso code is enough, but you can add other locales to make it more complete (e.g. Aspell-Locales: es, es_ES, es_ES@variant). The long form will be selected first if matches the value of the LANG environment variable. This last will be stripped of @.. and compared and stripped of _... and compared for a match.

  When there are two variants of a language (e.g., for new and old German) use the prefix 1: for the non preferred variant, e.g. Aspell-Locales: de, de_DE for new German and Aspell-Locales: 1:de, 1:de_DE for old German.

Wordlist packages only need to set the "Language" and "Hash-Name" fields. Other fields will silently be ignored.

myspell dictionary packages must provide a info file too -- this very different though. myspell dictionary package must provide a file -- which best is named as the package -- which contain the lines which should be added to OpenOffice.org's dictionary.lst; it should be installed into /usr/share/myspell/infos/ooo. For example

# German (Germany)
DICT de DE de_DE
      

which is the entry for German in Germany... For the exact meaning of the fields see dictionary.lst(5).

Choice of Architecture and Priority Level

Because the hash files generated by the buildhash program are binary files subject to big/little-endian differences, all ispell dictionary dictionary packages directly installing the hash file should have "Architecture: any" in their debian/control files. All wordlist packages should have "Architecture: all" (unless other files in the package prevent that).

If your ispell hash file is built at package postinst it should have "Architecture: all" in the debian/control file.

The priority level for all ispell dictionary dictionary and wordlist packages should be set to "optional", as we believe that any production system should provide spelling support for at least one language.

Dictionaries-common and wenglish have priority "standard", because (thanks to Charles Briscoe-Smith, previous wenglish maintainer): " The idea of "standard" is to define a minimal, standard Unix-like setup. A wordlist is certainly part of that, so to have [wenglish] and dictionaries-common as standard is probably right. "

myspell dictionary packages are "Architecture: all" and have priority "optional".

Installation Directories and Symlinks

* ispell dictionaries and wordlists

Ispell dictionary hashed files (.hash) and affix table iles (.aff) must be placed in the directory /usr/lib/ispell/. Wordlist dictionary files must be placed in the directory /usr/share/dict/.

When, as in the polish ispell dictionary, hash table is build at install time and can be later rebuilt with different options, things need to be done in a different way. In that case, the hashed table must be installed in /var/lib/ispell and a link from /usr/lib/ispell must be installed pointing to the hash file. The aff file will be installed as for any other dictionary.

If desired, symlinks can be created in this same directory with other language names, like italiano.hash -> italian.hash. This may be of some help to local users who do not know the language names in English.

enchant is a spellchecking portable library similar to what pspell was, but with more possible backends, developed by the abiword people. Currently Debian ispell dictionaries are compatible with enchant and can be made available to it under the names and encodings expected by enchant (See Appendix B). If your ispell dictionary is one of those listed there and the default encoding is the right one you only need to set a symlink, e.g.

/usr/share/enchant/ispell/espanol.hash -> /usr/lib/ispell/espa~nol.hash 
	

* myspell dictionary files

myspell dictionary files (*.dic and *.aff) must be installed in /usr/share/myspell/dicts.

If the files are called e.g. de_DE.{dic,aff} then there should be a symlink de-DE.{dic,aff} -> de_DE.{dic,aff} and the other way round... Another way is just to call them de-DE.{dic,aff} and add that to the last part of dictionary.lst(5) but that may be confusing to the users.

There could be exceptions of this rule (e.g. for swedish, where mozilla just supports "sv"...)

When used, the script installdeb-myspell, from the dictionaries-common-dev package, will take care of setting the appropriate symlinks if required, after the names found in the info file. With the --srcdir option can in some systems try to install the {.dic,.aff} files, see its documentation. Needs a versioned build dependency on dictionaries-common-dev

Maintainer Scripts for ispell dictionaries and wordlists

Notice that the debhelper scripts installdeb-ispell and installdeb-wordlist, provided by dictionaries-common-dev will handle most of the following automatically after the info file (See the Section called The info file). These are "debhelper-like" commands but are not officially part of the debhelper package. Debhelper may one day contain something with a completely different design and usage, that accomplishes about the same thing.

• postinst: should source the script update-default-ispell or update-default-wordlist (provided by the dictionaries-common package) when called with argument "configure". Here is a template for inclusion in the postinst script of ispell dictionary packages,

  . /usr/share/debconf/confmodule if [ "$1" = "configure" ] ; then /usr/sbin/update-default-ispell --rebuild fi

  And here is a similar template for the wordlist packages,

  . /usr/share/debconf/confmodule if [ "$1" = "configure" ] ; then /usr/sbin/update-default-wordlist --rebuild fi

  installdeb-ispell and installdeb-words will automatically include above code into the final postinst scripts.

• postrm: should source the script remove-default-ispell or remove-default-wordlist. when invoked with argument "remove" or "abort-install". The goal here is to prompt the administrator for a new selection if the package being removed is the current default. Here is a template for the code to be inserted into the postrm script of ispell dictionary packages (do not forget to edit #PACKAGE#),

  case "$1" in abort-install|remove) /usr/sbin/remove-default-ispell #PACKAGE# if [ -e /usr/share/debconf/confmodule ] ; then . /usr/share/debconf/confmodule db_purge fi esac

  The template for the wordlist packages is pretty similar:

  case "$1" in abort-install|remove) /usr/sbin/remove-default-wordlist #PACKAGE# if [ -e /usr/share/debconf/confmodule ] ; then . /usr/share/debconf/confmodule db_purge fi esac

where #PACKAGE# will be substituted by the package name. installdeb-ispell and installdeb-wordlist will automatically included above codes into the final postrm scripts with the right substitution for #PACKAGE#.

The scripts update-default-ispell and update-default-wordlist are responsible for the the manipulation of the appropriate symlinks in /usr/lib/ispell/ and in /usr/share/dict/, respectively, taking into account the selections made via debconf (see the Section called Ispell Dictionary and wordlist selection Support via Debconf).

Maintainer Scripts for myspell dictionaries

myspell dictionary packages must have (at least) the following maintainer scripts:

• postinst

  #!/bin/sh set -e if [ "$1" = "configure" ]; then update-openoffice-dicts fi #DEBHELPER# exit 0

• postrm

  #!/bin/sh set -e if [ "$1" = "remove" ]; then update-openoffice-dicts fi #DEBHELPER# exit 0

When used, the script installdeb-myspell, from the dictionaries-common-dev package, will take care of adding the appropriate debhelper snippets. Needs a versioned build dependency on dictionaries-common-dev

The templates file

Every ispell dictionary or wordlist package must have a templates file defining a shared debconf multiple-choice question as well as another template defining the languages the package provides. This is an example for an ispell dictionary:

Template: shared/packages-ispell
Type: text
Description:

Template: #PACKAGE#/languages
Type: text
Default: #LANGUAGES#
Description:
	

The example for the wordlist is this one:

Template: shared/packages-wordlist
Type: text
Description:

Template: #PACKAGE#/languages
Type: text
Default: #LANGUAGES#
Description:

The token #PACKAGE# must be replaced by *exactly* the name of the package and #LANGUAGES# must be replaced by a comma separated list of languages provided by the package. The entries in the #LANGUAGES# substitution must be *exactly* the same that appear in the Languages field in file /var/lib/dictionaries-common/(idict|wordlist)/<package-name> unless you really know what you are doing. Any missing entry will not be displayed by debconf. While sometimes this might be what you want you are suggested to use for that the "debconf-display" entry in your info-file and the debhelper-like command installdeb-ispell.

Additional templates may be added, if needed.

The config file

There must also exist a config file, which will be responsible for getting the user selection during the configuration run of dpkg. The debian/config script for a ispell dictionary must contain (after the #!/usr/bin/perl line) exactly the Perl code below,

use Debconf::Client::ConfModule q(:all);

version ('2.0');

my $class  = "ispell";
my $script = "/usr/share/dictionaries-common/dc-debconf-select.pl";

if ( -e $script ){
    require $script;
    dc_debconf_select($class);
}

For wordlist packages, must contain (after the #!/usr/bin/perl line) exactly the following perl code

use Debconf::Client::ConfModule q(:all);

version ('2.0');

my $class  = "wordlist";
my $script = "/usr/share/dictionaries-common/dc-debconf-select.pl";

if ( -e $script ){
    require $script;
    dc_debconf_select($class);
}

If some other debconf actions need to be added and they are in Perl, just add them to the script above. If you prefer to write in shell, wrap the script above in the following shell code:

tmp=`tempfile`
cat > $tmp <<EOF
** (the script above) **
EOF
perl $tmp
rm -f $tmp
	

Both the templates and the config files are package-independent, so that the maintainer should just copy the files above to his control area at build time, typically debian/tmp/DEBIAN directory.

Add an info file

An info file similar to that described in the Section called The info file must be installed as /var/lib/dictionaries-common/aspell/<package-name>, containing one entry for each aspell dictionary it provides.

Emacsen-Name must be the same of the equivalent ispell dictionary. Otherwise things like ;; ispell-local-dictionary: "brasileiro" in the spell checked file will not work similarly under ispell and aspell. As told before you must make sure that it will work with an info file entry similar to the ispell one.

Modify the maintainer scripts

Add a call to update-dictcommon-aspell to your postinst

if [ "$1" = "configure" ] ; then 
  [ -x /usr/sbin/update-dictcommon-aspell ] && /usr/sbin/update-dictcommon-aspell
  
fi

case "$1" in abort-install|remove)
  [ -x /usr/sbin/update-dictcommon-aspell ] && /usr/sbin/update-dictcommon-aspell

esac

Set the right relationships

If you want to use this system you must make your aspell dictionary depend on dictionaries-common (>= 0.9.1).

Make sure your dict will work with the ispell name

When aspell is selected for use from emacs, ispell.el will call something like aspell -d your_hashname through a pipe, where your_hashname is the value of the Hash-Name field in the info file entry for your dictionary. Since this must work with the corresponding ispell name, make sure that something like your_hashname.alias or a symlink to the .multi file as your_hashname.multi is present in the aspell lib dir, so a command like aspell check -d your_hashname your_file checks your_file with aspell and the selected language.

installdeb-aspell: a debhelper like helper for aspell dictionaries

A debhelper like script is provided to make even easier the steps above. This helper is named installdeb-aspell and relies in the existence of an info-aspell file conforming to the specified in the Section called The info file, and named as for other debhelper files (.docs, .manpages, ...). Calling it in debian/rules will install the aspell info file and create postinst and postrm debhelper snippets to be installed by debhelper. Note, that, unlike installdeb-{ispell,wordlist} this script does not know about debconf so you should install your debconf stuff, if any, in the usual way.

If you use this script you must make your package build depend on dictionaries-common-dev (>= 0.9.1).