===========================
user_ordered_index_patch.py
===========================

``user_ordered_index_patch.py`` can be used as the extension of Sphinx.

But this extension includes the hack codes against Sphinx. Because of that,
The extension may or may not work with further version of Sphinx.
You can check by comparing newer with hacked one.

-------------------------------
Declare to use as the extension
-------------------------------

Put in ``exts`` folder and add ``user_ordered_index_patch`` into ``extension`` valuable in ``conf.py``.


.. note:

	For ``yogosyu``, extended glossary directive, see :doc:`YogosyuDirective`\ .

---------------------------------------
Make sure the language of your document
---------------------------------------

You can declare with ``language='xx'`` in ``conf.py`` where ``xx`` is your locale language code.
``xx`` is not limited 2 characters. e.g. 5 characters are acceptable.

---------------------------------------------------
Make sure sort_order.py and sort_order_xx.py exists
---------------------------------------------------

You should make sure ``sort_order.py`` and ``sort_order_xx.py`` are importable as python module.
Simply, just place them under ``exts`` folder like other extensions.

if ``sort_order_xx.py`` is not found, ``SortOrderLegacy`` defined in ``sort_order.py`` is used.

.............................................
Make sort_order_xx.py where xx is your locale
.............................................

Of course, currently only ``sort_order_ja.py`` and ``sort_order_eo.py`` are given with this
distribution, any ``xx`` except ``ja`` nor ``eo`` doesn't work.
You have to make your ``sort_order_xx.py``\ .

``sort_order_ja.py`` looks complex one, but the requirement is more simple.

- Make subclass of ``sort_order.SortOrderBase`` defined ``sort_order.py``
- Make ``get_default_sort_order`` function to return the instance of the class.
- Make ``setup`` function used only when directly assigned (optional).

.. note::

	``sort_order_eo.py`` is included in ``esperant_ordo/exts`` folder.

.............................................
Directly assigning sort order
.............................................

If your sort order is very special and not generally used in your locale, please implement
``setup`` function described in the section above. And declare in ``extension`` valuable in
your ``conf.py`` *BEFORE* ``user_ordered_index.py`` and ``yogosyu.py``\ .

In this way, you can give any name to the file, not ``sort_order_xx.py``\ .