Rafael Laboissière The Debian Project

rafael@debian.org

David Coe The Debian Project

davidc@debian.org

Agustín Martín Domingo The Debian Project

agmartin@debian.org

René Engelhard The Debian Project

rene@debian.org

Release 0.98.10 (2008-7-03) Status: draft 1999-2008 Rafael Laboissière, David Coe, Agustín Martín Domingo & René Engelhard This text is distributed according to the GNU General Public License . This document is intended for Debian maintainers whose packages relate in some manner to the ispell program, ispell/aspell/myspell dictionaries and/or wordlists (application-independent dictionaries). It concerns therefore the ispell package itself, the language-specific ispell/aspell/myspell dictionaries, the language-specific wordlists, some editors like (X)Emacs and jed, some of the mail and news user agents (MUAs, NUAs), and other tools that give the user a choice of dictionaries for spell checking. The main goal of this Policy is to establish the basic requirements for the said packages in a Debian system, allowing a high degree of integration among them. This should yield a coherent behavior of all ispell/aspell/myspell dictionary and wordlist-related packages, both at installation and usage time. This document no longer affects aspell packages for anything else that its use under emacs (see ). For information on aspell dictionary policy please look at the aspell package documentation and at the aspell manuals http://aspell.net/dist.txt http://savannah.gnu.org/download/aspell/manual/user/manual.html emacs-snapshot package should not be affected by this document. It will contain the bleeding edge code from emacs cvs and we have decided to keep it as standalone as possible to minimize interferences from external code. 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. Easier package configuration. Fewer bug reports. Better integration of wordlists and spelling dictionaries. If you maintain an &IDWP; you must install the package dictionaries-common. This package will conflict with all old style &IDWP;s. 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 &IDWP;s. 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 &MDP;s 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 . Verify the architecture and priority level in debian/control (see ). Be sure that you are installing the correct files and symlinks in /usr/lib/ispell/, /usr/share/myspell/ or /usr/share/dict/. (see ). 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 . 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 or . There is no script like that necessary for &MDP; 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 . Add debconf support (files debian/{templates,config} as described in ). Create and install the info file (See ). 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 &IDWP; 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. Wordlists and Ispell dictionaries are interrelated but separate packages. This system provides a common background for them and intends to be able to handle a number of different possibilities. The simplest one is a package providing just one dictionary. There are also some packages that do provide more that one dictionary. For instance, ifrench-gut provides both french-gut and french-gut-tex8b, or the norwegian dictionary provides both nynorsk and bokmål. That will be handled properly by the system. The miscfiles package also provides an english wordlist (web2, all the words from the 1934 Webster's Second International Dictionary), as well as many other different things. This can also be handled properly by the system. A package called dictionaries-common is created. It allows (ispell/aspell/myspell)-dictionary and wordlist packages to be coherently integrated by providing necessary infrastructure, including configuration scripts, commands for selecting default dictionaries, and initialization routines for the different emacsen flavors and jed. It also provides support for registering aspell dictionaries for use under emacs. This is the basic package for the system to work. A package dictionaries-common-dev, to which this Policy belongs, is also provided. This is a package for maintainers of &IDWP;s. It contains the Policy document itself, as well as debhelper-like scripts to simplify the debianization of &IDWP;s for maintainers using debhelper. It also (via this policy document) may provide suggestions or patches for other related packages. 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. 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. 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. 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 ). It is not possible for a system to have a mixture of new-style and old-style &IDWP; concurrently. The package dictionaries-common conflicts with all the old &old-dic-name; and &old-wlist-name; packages prior to the first version using the new policy, because there is now a new way to manage their alternative symlinks. For that reason you have to check the entry corresponding to your &IDWP; in the versioned conflicts line of dictionaries-common package and notify maintainer of that package which was the last version of your package using the old system, to include the right versioned conflict in the dictionaries-common package. &MDP;s 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.. Please check for information about versions where some features were introduced. This is needed to set correct versioned dependencies and build-dependencies. The package relationships declared in the debian/control files should be as follows for &IDWP;s: Because wamerican will provide a /usr/share/dict/words->/usr/share/dict/american-english symlink, needs to conflict with dictionaries-common (<< 0.98) where /usr/share/dict/words diversion was first introduced. No dependency on dictionaries-common is needed as long as wamerican maintainer scripts do not fail without it (see ). All &IDWP;s but wamerican have to depend on dictionaries-common in their debian/control files. Every &IDWP; using the helpers from dictionaries-common-dev has also to declare Build-Depends: debhelper, dictionaries-common-dev if your package contains architecture dependent ispell or aspell dicts (See ispell-autobuildhash or aspell-autobuildhash manual pages for info about how to make our ispell or aspell dict package 'arch: all' by building hashes from package postinst), or Build-Depends: debhelper Build-Depends-Indep: dictionaries-common-dev if all ispell, aspell, myspell dicts and wordlist packages using dictionaries-common-dev are architecture independent. This will 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 appropriate build dependency. Each &new-dic-name; package should suggest the corresponding &new-wlist-name; 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 ). For &MDP;s the relationships in debian/control should be as follows: the &MDP;s 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 flavors in Debian supporting it (currently iceape-browser, iceweasel and icedove) Moreover, it must Conflict: against openoffice.org (<= 1.0.3-2) The myspell packages having an "old" version named openoffice.org-spellcheck-* (regardless of whether that was in Debian once or not) must declare the magic Conflicts: / Provides: / Replaces: combination "against" the old package. All &IDWP;s must install a file /var/lib/dictionaries-common/(ispell|wordlist)/<package-name>. (Aspell dictionaries can install it at /var/lib/dictionaries-common/aspell/<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 Elanguage: portugues brasileiro (Brazilian Portuguese) 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 &IDWP;. 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). 8-bit chars in Casechars, Not-Casechars and Additionalchars must be represented in the same encoding declared for the dict in the info file, either as the char itself or as its octal \xxx representation. This later is highly preferable if another string like Language contains utf-8 chars. 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. It is very important that the Language name be unambiguous and informative to the system administrator, because at debconf dictionary-selection time only the list of package names, and not their descriptions, will be visible. 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. Once set, do not change it for entries triggering a debconf question unless there is a good reason for that. Note that changes may trigger an extra debconf prompt. 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. You should consider using only 7 bit chars if possible when you create this field for the first time. 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. English description should preferably be unique too. 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 value) 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. Elanguage: (optional, defaults to Language value) Alternative language name to be displayed by debconf. Not needed at all unless you use the debhelper like scripts and are changing the language name to be displayed, avoiding extra debconf prompts. Its format is the same as Language. See for more info about this. Casechars: (optional, defaults to [a-zA-Z]) Emacs-Lisp regexp of valid characters that comprise a word. It is typically enclosed between square brackets. Do not use ranges here for non 7bit chars. 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. For emacsen this is somehow redundant with the Casechars field, but is necessary for the proper working of jed and 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 flavors. 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. At the time of this writing there are some encoding unification problems in at least xemacs 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. The values of the fields Otherchars, Many-Otherchars, and Additionalchars must have the same encoding as the dictionary encoding. Each character can be written in the \xxx format, where xxx is its octal value. For instance, é can be written as \351. Wordlist packages only need to set the Language and Hash-Name fields. Other fields will silently be ignored. &MDP;s must provide a info file too -- this very different though. &MDP; 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). If you use debhelper and the helpers installdeb-{ispell,wordlist} provided by the package dictionaries-common-dev most of the required work will be automatically done after this info file. In this case you have to name this file with extension .info-ispell or .info-wordlist depending of the package class. When used, the script installdeb-myspell, from the dictionaries-common-dev package, will take care of installing the myspell info-myspell file in its place. Needs a versioned build dependency on dictionaries-common-dev The full name rules are similar than for other debhelper files like dirs or docs. If you use cdbs for building your package, just use: include /usr/share/cdbs/1/rules/debhelper.mk include /usr/share/doc/dictionaries-common/cdbs/dict-common.mk in your debian/rules. This will take care of the inclusion of all the installdeb-* commands at the appropriate places. Notice that this is only guaranteed to work when used in conjunction with debhelper. For this to work the package should build-depend on cdbs and debhelper, and also contain a versioned build-dependency on dictionaries-common-dev >= 0.70. For an example of use of the cdbs support see the myspell.pt source package (version 20060602-2 or later). Because the hash files generated by the buildhash program are binary files subject to big/little-endian differences, all &new-dic-name; dictionary packages directly installing the hash file should have Architecture: any in their debian/control files. All &new-wlist-name; 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. See ispell-autobuildhash or aspell-autobuildhash manual pages for info about how to make your ispell or aspell dict package Architecture: all by building hashes from package postinst. The priority level for all &new-dic-name; dictionary and &new-wlist-name; 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 wamerican 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 [wamerican] and dictionaries-common as standard is probably right. &MDP;s are Architecture: all and have priority optional. * ispell dictionaries and wordlists Ispell dictionary hashed files (.hash) and affix table files (.aff) must be placed in the directory /usr/lib/ispell/. Wordlist dictionary files must be placed in the directory /usr/share/dict/. wamerican will also set a /usr/share/dict/words->/usr/share/dict/american-english symlink. 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 spell-checking 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 ). 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. For better mozilla integration, if the files are called e.g. de_DE.{dic,aff} then, for most languages, there should be a de-DE.{dic,aff}->de_DE.{dic,aff} symlink, and mozilla will display German instead of de-DE. 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. Note that there are exceptions for this rule (e.g. for Swedish, where mozilla expects just "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. When your myspell dict corresponds to one of the exceptions, set links using debian/$myspell_dict_package.links. installdeb-myspell will not try to set symlinks if this file is found (see checklist in for build-dependency information). With the --srcdir option can in some systems try to install the {.dic,.aff} files, see its documentation. Use of installdeb-myspell needs a versioned build dependency on dictionaries-common-dev (See ) 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 ). 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. wamerican: For the special case of wamerican scripts should be similar as below, but modified so they do not fail in case dictionaries-common is not installed. Note that this needs to be done manually, installdeb-wordlist will only create the standard maintainer scripts. 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, And here is a similar template for the wordlist packages, 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#), The template for the wordlist packages is pretty similar: 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 manipulation of the appropriate symlinks in /usr/lib/ispell/ and in /usr/share/dict/, respectively, taking into account the selections made via debconf (see ). &MDP;s must have (at least) the following maintainer scripts: postinst postrm 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 debconf makes it possible to have the selection of a default dictionary happen only once, just before dpkg install phase, even if several dictionary packages are being installed at the same time. This is in contrast with the old system, where the user was prompted for each new package being installed/upgraded, or was just advised to manually update the wordlist dictionary symlink in /etc/alternatives. Individual users may, of course, override the administrator's chosen default ispell dictionary, by using either DICTIONARY environment variable, or by explicitly giving the dictionary name in the command line (e.g. with the -d option of ispell). Some applications also allow the user to select a dictionary from within that application -- such changes affect only that application and (usually) only the current application session. (See ). In order to accomplish these things, some discipline is required. 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: The example for the wordlist is this one: 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* (including that this entry is not to be localized) the same that appear in the Languages field in file /var/lib/dictionaries-common/(ispell|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. A #PACKAGE#/elanguages template entry similar to #PACKAGE#/languages can be used to override the debconf prompt text in the later. Its format is the same as for language. If containing more that one language, both languages and elanguages must have entries for the same languages and in the exact same ordering. Please try making elanguages base text as portable as possible (that is, try hard to make it 7 bit clean, using appropriate transliteration if possible). #PACKAGE#/elanguages has another difference, it can be localized. While this field is localizable, for most cases the former poor man Language internationalization is enough and translators should have another priorities. When localizing, please change only the non-parenthesized part for consistency with other entries. A #PACKAGE#/elanguages will be created by the installdeb-* scripts after either Elanguage value, if given in the info file, or Language value otherwise. This can be disabled when calling the script. Additional templates may be added, if needed. If you are using debhelper and the debhelper like scripts provided by the dictionaries common system, the above templates file will be automatically generated from information gathered from the info file. If you do not need additional templates you do not have to worry about this. Otherwise, if you need additional templates, do not put them in a file named debian/<package-name>.templates, since it will be overwritten by the installdeb-* scripts. The exact way for doing that depends on whether you use po-debconf or not to maintain localized versions of the templates. If you use po-debconf, your master templates file is expected to be named debian/<package-name>.po-master.templates. You do not need to merge the translations by yourself, since installdeb-* will do that for you. See the po-debconf manual page for details about how to create master templates file and po files. Remember that the templates file is now named debian/<package-name>.po-master.templates to avoid conflicts with the autogenerated one. Remember also putting the appropriate po-debconf dependencies as described in the po-debconf manual since dictionaries-common sets no dependency on it. If you do not use po-debconf, put them in a file named debian/<package-name>.templates.in. installdeb-* will merge the templates and will install the merged templates file the right way. This system can coexist with localized templates like debian/<package-name>.templates.ru corresponding to localizations of your extra templates. dh_installdebconf, called internally from the installdeb-* scripts will merge them with the templates file that is auto generated at debian/<package-name>.templates. Note that this is being deprecated by debconf. 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, wordlist packages other than wamerican must contain (after the #!/usr/bin/perl line) exactly the following perl code config file for wamerican is similar to the above, but checking also for existence of /usr/share/dictionaries-common/elanguages before loading the common stuff. This is intended to avoid problems if dictionaries-common is made an optional package in the future, as intended. (See http://lists.alioth.debian.org/pipermail/dict-common-dev/2008-June/000739.html for more details). 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. If the maintainer is using debhelper and package dictionaries-common-dev is installed, the installdeb-ispell and installdeb-wordlist, when called in debian/rules, will create the above files automatically when no other actions are required in the config file. Do not call dh_instaldebconf in your rules file, since the scripts above already call it internally. If other actions are to be added in the debian/config file and you are using debhelper and the helper scripts from dictionaries-common-dev proceed as follows. Add your actions to a debian/config.in (or debian/<package-name>.config.in) file. If your actions are written in perl the config.in should look something like #!/usr/bin/perl #DEBHELPER# # Now the package local stuff with your code and if they are written in a sh script, they should look like #!/bin/sh #DEBHELPER# # Now the package local stuff with your code installdeb-ispell or installdeb-wordlist will take care of including the code required by this policy document into the config scripts. Startup files for emacs and jed are automatically generated after installation of the ispell dictionaries (see ). Mutt support is also provided. As regards the user interface, a new jed command is now available: Mx ispell_change_dictionary , which prompts the user for the ispell dictionary which will be used in the current editing session for spell checking. Many debian packages (and non-debian-packaged applications) don't provide a way for the user to select from multiple spelling dictionaries -- they just use ispell, which uses its currently-selected default dictionary. This is fine, and the user doesn't have to learn anything new to switch from one dictionary to another (see ). The dictionaries-common system will only use the contents of the emacs ispell-dictionary-alist variable in ispell.el if the corresponding entry is not redefined after the really installed dictionaries. A registration system similar to that provided for ispell dictionaries is available for aspell dictionaries. To use this system, please see the following guidelines An info file similar to that described in must be installed as /var/lib/dictionaries-common/aspell/<package-name>, containing one entry for each aspell dictionary it provides. If there is an equivalent ispell dictionary, Emacsen-Name must be the same of it. Otherwise things like ;; ispell-local-dictionary: "brasileiro" in the spell checked file will not work similarly under ispell and aspell. Add a call to update-dictcommon-aspell to your postinst and to your postrm If you want to use this system you must make your aspell dictionary depend on dictionaries-common (>= 0.9.1). 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 , 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). This is a summary of the dictionaries-common(-dev) versions that may imply a dependency or build-dependency in your package. This is a summary of the system scripts provided by the system and their purpose: select-default-(ispell|wordlist): Make debconf always ask the shared question. Calls internally update-default-(ispell|wordlist). update-default-(ispell|wordlist): Read the system default from the debconf database and set links in default links in /etc/dictionaries-common pointing to the appropriate files in /usr/lib/ispell/ or /usr/share/dict/. Also updates the system-wide setting /etc/dictionaries-common/(ispell|wordlist)-default. If option --rebuild is given, rebuilds the /var/cache/dictionaries-common/(ispell|wordlist).db and the emacsen and jed support (to be put in /var/cache/dictionaries-common/(emacsen|jed)) from the files in /var/lib/dictionaries-common/(ispell|wordlist) update-dictcommon-aspell: Rebuilds the /var/cache/dictionaries-common/aspell.db and the emacsen support (to be put in /var/cache/dictionaries-common/) from the files in /var/lib/dictionaries-common/aspell (merged for the emacsen support with stuff from /var/lib/dictionaries-common/ispell). update-openoffice-dicts: Update OpenOffice.org myspell dictionary list at /etc/openoffice/dictionary.lst remove-default-(ispell|wordlist): Call update-default-(ispell|wordlist) --rebuild. The emacsen implementation that follows is essentially an implementation of the proposal made by Rob Browning some time ago (see file emacsen.historic in the source package). Emacsen support for the ispell dictionaries is built upon the requirements of the emacsen-common packages. Package maintainers are encouraged to read the Debian Emacsen Policy, included in the emacsen-common package (/usr/share/doc/emacsen-common/debian-emacs-policy.gz), although they do not need to know it for maintaining ispell dictionaries or wordlist packages. The goal here is to allow a coherent behavior of the ispell.el ELisp package, available in all emacsen flavors. Information from each ispell and aspell dictionary info file is gathered and used to create an emacs elisp initialization file (/var/cache/dictionaries-common/emacsen-ispell-dicts.el) in which certain language-specific parameters are set after the contents of the info files, resulting in correct entries in the ispell-dictionary-alist variable. Remember that this file is automatically generated, so do no not edit it for any other purpose than debugging problems with the emacs menus, since it will be overwritten at some time. In case of problems, with the information in this appendix, check entries in that file to verify that they have the expected values and double check the syntax of the info file (see ) in case of problems. Also look at the entries corresponding to other dictionaries, a wrong entry from other dictionary can cause problems with menus for all dictionaries. This mapping shows locale name, expected hash name and expected encoding for enchant ispell interface. Extracted from file src/ispell/ispell_checker.cpp at the enchant sources. This appendix might be out of date, please refer to that file for the most recent values.