Revision as of 13:57, 28 April 2008

Problem with current dictionary.lst file

In order to get rid of the problems involved with the dictionary.lst file at upgrade (see issue 72559) we have to forsake the use of it and provide the necessary information about dictionaries in the configuration.

Already provided configuration entries

Each implementation of spell checker, hyphenator or thesaurus needs to have an entry in the configuration (i.e. the file Linguistic.xcu) stating it's implementation name (for purposes of identification) and the file format names of the dictionaries it can handle. More than one file format can be listed if supported.

The dictionary file format names for the current OOo linguistic are

• DICT_SPELL
• DICT_HYPH and
• DICT_THES

Thus the respective entries do look like this:

• Spell checker entry

<node oor:name="ServiceManager">
    <node oor:name="SpellCheckers">
        <node oor:name="org.openoffice.lingu.MySpellSpellChecker" oor:op="fuse">
            <prop oor:name="SupportedDictionaryFormats" oor:type="oor:string-list">
                <value>DICT_SPELL</value>
            </prop>
        </node>

        ... entries for other spell checkers ...
    </node>
</node>

• Hyphenator entry

<node oor:name="ServiceManager">
    <node oor:name="Hyphenators">
        <node oor:name="org.openoffice.lingu.LibHnjHyphenator" oor:op="fuse">
            <prop oor:name="SupportedDictionaryFormats" oor:type="oor:string-list">
                <value>DICT_HYPH</value>
            </prop>
        </node>

        ... entries for other hyphenators ...
    </node>
</node>

• Thesaurus entry

<node oor:name="ServiceManager">
        <node oor:name="org.openoffice.lingu.new.Thesaurus" oor:op="fuse">
            <prop oor:name="SupportedDictionaryFormats" oor:type="oor:string-list">
                <value>DICT_THES</value>
            </prop>
        </node>

        ... entries for other thesauri ...
</node>

The only link between one of the above services and the dictionaries to be used by them is the name of the dictionary format. When invoked the services are required to check in the configuration which dictionaries they can make use of and thus establishing their set of dictionaries to use. This is done by looking at the format names of the configured dictionaries.

Dictionary entries (must be provided)

The entries that are still missing and need to be provided are those for the dictionaries. Each dictionary must have an entry of its own.

An entry consists of

• a unique name (the node name in the configuration)
• a list of file locations (only the ones actually needed by the service implementation)
• a single format name and
• a list of ISO-names for locales listing the languages the dictionary may be used for

Please note that there is no specified order to the list of files provided in the Locations property. Also it is the implementations task to distinguish between those files and their potentially different use by their name only.

Thus a set of dictionary entries in the Linguistic.xcu provided by a single extension may look like this:

 <node oor:name="ServiceManager">
    <node oor:name="Dictionaries">
        <node oor:name="HunSpellDic_de_CH" oor:op="fuse">
            <prop oor:name="Locations" oor:type="oor:string-list">
                <value>%origin%/de_CH.aff %origin%/de_CH.dic</value>
            </prop>
            <prop oor:name="Format" oor:type="xs:string">
                <value>DICT_SPELL</value>
            </prop>
            <prop oor:name="Locales" oor:type="oor:string-list">
                <value>de-CH</value>
            </prop>
        </node>
        <node oor:name="HunSpellDic_en_US" oor:op="fuse">
            <prop oor:name="Locations" oor:type="oor:string-list">
                <value>%origin%/en_US.aff %origin%/en_US.dic</value>
            </prop>
            <prop oor:name="Format" oor:type="xs:string">
                <value>DICT_SPELL</value>
            </prop>
            <prop oor:name="Locales" oor:type="oor:string-list">
                <value>en-US</value>
            </prop>
        </node>
        <node oor:name="HyphDic_en_US" oor:op="fuse">
            <prop oor:name="Locations" oor:type="oor:string-list">
                <value>%origin%/hyph_en_US.dic</value>
            </prop>
            <prop oor:name="Format" oor:type="xs:string">
                <value>DICT_HYPH</value>
            </prop>
            <prop oor:name="Locales" oor:type="oor:string-list">
                <value>en-US</value>
            </prop>
        </node>
        <node oor:name="HyphDic_de_CH" oor:op="fuse">
            <prop oor:name="Locations" oor:type="oor:string-list">
                <value>%origin%/hyph_de_CH.dic</value>
            </prop>
            <prop oor:name="Format" oor:type="xs:string">
                <value>DICT_HYPH</value>
            </prop>
            <prop oor:name="Locales" oor:type="oor:string-list">
                <value>de-CH</value>
            </prop>
        </node>
        <node oor:name="ThesDic_de_CH" oor:op="fuse">
            <prop oor:name="Locations" oor:type="oor:string-list">
                <value>%origin%/th_de_CH_v2.dat %origin%/th_de_CH_v2.idx</value>
            </prop>
            <prop oor:name="Format" oor:type="xs:string">
                <value>DICT_THES</value>
            </prop>
            <prop oor:name="Locales" oor:type="oor:string-list">
                <value>de-CH</value>
            </prop>
        </node>
        <node oor:name="ThesDic_en_US" oor:op="fuse">
            <prop oor:name="Locations" oor:type="oor:string-list">
                <value>%origin%/th_en_US_v2.dat %origin%/th_en_US_v2.idx</value>
            </prop>
            <prop oor:name="Format" oor:type="xs:string">
                <value>DICT_THES</value>
            </prop>
            <prop oor:name="Locales" oor:type="oor:string-list">
                <value>en-US</value>
            </prop>
        </node>
    </node>
 </node>  

A most simple dictionary extension providing several dictionaries at once is attached to issue 81365.

A more complete extension probably likes to provide the description.xml for the extension as well in order to give a short description and a version number for the extension.

However for a sample description.xml to use look below.

Dictionary extensions vs pre-installed flat-file dictionaries

There are only two choices for installing dictionaries to make use of. Those are

• pre-installing dictionaries with the office installation or
• download one or more dictionaries as extension

Downloadable dictionaries must always be provided as extension only! Either way in both variants configuration entries for each dictionary have to be provided.

The configuration entries for above two flavors differ only in the way the required files are denoted in the Locations property of the entry.

For extension dictionaries the property must look like

    <prop oor:name="Locations" oor:type="oor:string-list">
        <value>%origin%/en_US.aff %origin%/en_US.dic</value>
    </prop>

While for pre-installed dictionaries (using plain files as done so far) it needs to look like

    <prop oor:name="Locations" oor:type="oor:string-list">
        <value>$(insturl)/share/dict/ooo/en_US.aff $(insturl)/share/dict/ooo/en_US.dic</value>
    </prop>

Note: Even though it is possible to use flat-file installation for dictionaries the way to go is by providing them as extension!

A sample description.xml for a dictionary extension

<?xml version="1.0" encoding="UTF-8"?>
<description xmlns="http://openoffice.org/extensions/description/2006" xmlns:d="http://openoffice.org/extensions/description/2006"  xmlns:xlink="http://www.w3.org/1999/xlink">


    <!-- SHOULD OR MUST BE PROVIDED ENTRIES FOLLOWING... -->


    <!--Here you can state the license text to be displayed during installation.
        You can provide more than one localized version if you like.
        If no matching locale was found the first one will be displayed.
        !!! Don't change the values for 'accept-by' or 'suppress-on-update' it  !!!
        !!! might be troublesome in multi-user installations if no shared-layer !!!
        !!! installation can be done.                                           !!!
    -->
    <registration>
        <simple-license accept-by="admin" suppress-on-update="false" >
            <license-text xlink:href="LISEZMOI.txt" lang="fr-FR" license-id="fr-FR" />
        </simple-license>
    </registration>

    <!--The version of your extension. NOT the one of OpenOffice.org...
        It will also be used to automatically check if there are updates for this
        extension available. Newer versions should have higher values.
    -->
    <version value="1.2.1" />

    <!--A unique identifier for your extension.
        In order to avoid name clashes with other extensions it should probably hold
        your company name or your full name along with the name of the extension in a form like
            MyFirstName.MyLastName.DictionayName
        or  www.MyWebpage.net.DictionayName
        Or  you may use the project name of your submitted extension to start with...
        For the very same reason they should NOT start with 'org.openoffice'.
        When choosing the identifier keep in mind that others may provide a dictionary for that
        very same language as well and even then your identifier still needs to be unique!
    -->
    <identifier value="MyFirstName.MyLastName.fr-FR.dictionaries" />

    <!--A name for the extension to be used in the UI.
        For dictionaries it should show the locales supported
        and the purpose spell checking and/or hyphenation and/or thesaurus.
        The display name can be localized and there should be at least one
        entry for each language it implements and one default English entry.
        The default entry is the one listed first.
    -->
    <display-name>
        <name lang="en">French (France) spell check dictionary</name>
        <name lang="fr">... to be done ...</name>
    </display-name>

    <!--Dictionaries should work with all platforms...-->
    <platform value="all" />
    
    <!--A minimal OpenOffice.org version the extension requires to be used with.
        For dictionary extensions that will be 'OpenOffice.org 3.0'
    -->
    <dependencies>
        <OpenOffice.org-minimal-version value="3.0" d:name="OpenOffice.org 3.0" />
    </dependencies>


    <!-- MORE OPTIONAL LIKE ENTRIES FOLLOWING (may easily be omitted, uncommented by default)... -->


    <!--If you uploadet your extension to the repository (which should be the default!) 
        you do not need to have this one.
    <update-information>
        <src xlink:href="http://extensions.openoffice.org/testarea/desktop/license/update/lic3.update.xml" />
    </update-information>
    -->
    
    <!--Check if this is already generated by repository.
        Otherwise you may like to provide it manually.
    <publisher>
        <name xlink:href="http://extensions.openoffice.org/testarea/desktop/publisher/publisher_en.html" lang="en">My dictionary extension (en)</name>
        <name xlink:href="http://extensions.openoffice.org/testarea/desktop/publisher/publisher_fr.html" lang="fr">My dictionary extension (fr)</name>
    </publisher>
    -->

    <!--This link will be generated by repository. Check if this already works for multiple languages. 
        If not you may provide it manually if you like.         
    <release-notes>
        <src xlink:href="http://extensions.openoffice.org/testarea/desktop/publisher/release-notes_en.txt" lang="en" />
        <src xlink:href="http://extensions.openoffice.org/testarea/desktop/publisher/release-notes_fr.txt" lang="fr" />
    </release-notes>
    -->
      
</description>

Further readings and notes

• Start page for extensions
• Checklist for writing extensions
• About the description.xml
• Online update of extensions

Uploading and installing extensions

You can browse all available extensions here.

Extensions should be created as oxt files and uploaded to the repository. Only that way checking for available updates will happen automatically. You can upload your extension here

For installation instructions look here