==========================
Yogosyu directive
==========================

To use your sort order in your glossary, you have to use ``yogosyu`` directive instead of ``glossary``\ .

When your language have CJK Ideographs, you want to add reading to sort.
In Japanese, this reading (or 'How to read the word') is called Yomi or Yomigana.

``yogosyu`` directive also have the feature to add Yomigana to sort.

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

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

.. note:

	For index page, see :doc:`UserOrderedIndexPatch`\ .

--------------------------------------------------
Define and assign the sort order for your language
--------------------------------------------------

Make your ``sort_order_xx.py`` and make sure ``language`` option etc.

This work completely same as described in :doc:`UserOrderedIndexPatch`\ .

---------------------------------------------
Use yogosyu directive instead of glossary
---------------------------------------------

The ``yogosyu`` extends the ``glossary`` directive. As told above, you should replace the name of the directive.

When your language doesn't have CJK Ideographs, you can skip the rest of this page ;)

------------------------------
Assign yomimark option 
------------------------------

To add Yomigana, use ``yomimark`` separator after each term, and place Yomigana just after ``yomimark``\ .

You can give any one character and can vary it for each ``yogosyu`` directive. Of course, ``yomimark``
should be the character neither in both terms nor Yomigana-s::

	.. yogosyu::
	    :sorted:
	    :yomimark: ×


You can omit ``sorted`` option. In this case, the terms don't sorted in ``yogosyu`` glossary and sorted in
index page only when :doc:`user_ordered_index_patch.py <UserOrderedIndexPatch>` used.

.. note::

	``yomimark`` can accept ``space``, ``tab`` or ``U+hhhh`` form. 
	see ``single_char_or_whitespace_or_unicode`` method in ``docutils.parsers.rst.directives.__init__.py``\ .

-------------------------------------
Add yomimark and Yomigana after terms
-------------------------------------

Write follwing order; each term, the character declared with ``yomimark`` option and the Yomigana.
You can omit ``yomimark`` and Yomigana for each term we don't have to give them::

	.. yogosyu::
	    :sorted:
	    :yomimark: ×

	    姫踊子草×Himeodorikoso
	    	Lamium purpureum. The Purple Deadnettle in English.
	    	
	    キーボード
	    	The keyboard in Katakana form.

You should not any (overadded) whitespaces before and after ``yomimark`` character. 

Currently, second appearance of it in a line, all characters after that are ignored.

.. note::

	This ignorance behavior is designed for future use. see :doc:`ToDos`\ .