[#2750] Rewrite tag vocabularies docs

Change the tag vocabularies docs to refer to the working example in
ckanext/example_idatasetform instead of providing their own detailed
instructions.

Also add some more general explanation at the start about what tag
vocabularies are for/why you might want to use them/what you can do with
them, it was all a bit mysterious.

Remove some false claims from the Properties section, I don't think that
the restricted/free vocabulary types are implemented (they are either
always restricted or always free, can't remember), vocabularies do not
have descriptions.

doc/tag-vocabularies.rst

@@ -4,68 +4,67 @@ Tag vocabularies
 
 .. versionadded:: 1.7
 
-CKAN tags can belong to a vocabulary, which is a way of grouping related tags together.
+CKAN sites can have *tag vocabularies*, which are a way of grouping related
+tags together into custom fields.
 
-Properties
-----------
+For example, if you were making a site for music datasets. you might use a tag
+vocabulary to add two fields *Genre* and *Composer* to your site's datasets,
+where each dataset can have one of the values *Avant-Garde*, *Country* or
+*Jazz* in its genre field, and one of the values *Beethoven*, *Wagner*, or
+*Tchaikovsky* in its composer field. In this example, genre and composer would
+be vocabularies and the values would be tags:
 
-* A CKAN instance can have any number of vocabularies.
-* Each vocabulary consists of an ID, name and description.
-* Each tag can be assigned to a single vocabulary (or have no vocabulary).
-* A dataset can have more than one tag from the same vocabulary, and can have tags from more than one vocabulary.
-* Vocabularies can be of two types:
-    * Controlled: the list of possible tags is pre-defined
-    * Free: users enter their own terms
+- Vocabulary: Genre
 
-Using Vocabularies
-------------------
+  - Tag: Avant-Garde
 
-A CKAN developer/sysadmin user will have to do a number of things to add some custom vocabs to their CKAN instance:
+  - Tag: Country
 
-1. Call CKAN API functions to add the vocabularies and terms to the db.
-2. Implement a CKAN extension (with a custom form), including the tag vocabularies in the schema.
-3. Provide dataset view, edit and create templates with the new schemas in them.
+  - Tag: Jazz
 
-1. Adding Vocabularies
-~~~~~~~~~~~~~~~~~~~~~~
+- Vocabulary: Composer
 
-This needs to be done via the action API (:doc:`apiv3`). Please check the examples section to see which calls are needed.
+  - Tag: Beethoven
 
-2. Custom Form Schema
-~~~~~~~~~~~~~~~~~~~~~
+  - Tag: Wagner
 
-* Make a plugin that implements ``IDatasetForm`` (for example, see ``ExampleDatasetForm`` in https://github.com/okfn/ckanext-example/blob/master/ckanext/example/forms.py).
-* Override  ``form_to_db_schema``. Add a new field for your vocabulary tags, making sure that it uses the ``convert_to_tags`` converter with the name of the vocabulary. For example, the following will add a new field called ``vocab_tags``, with each tag assigned to the vocabulary ``EXAMPLE_VOCAB``::
+  - Tag: Tchaikovsky
 
-    def form_to_db_schema(self):
-        schema = package_form_schema()
-        schema.update({'vocab_tags': [ignore_missing, convert_to_tags('EXAMPLE_VOCAB')]})
-        return schema
+Ofcourse, you could just add Avant-Garde, Beethoven, etc. to datasets as normal
+CKAN tags, but using tag vocabularies lets you define Avant-Garde, Country and
+Jazz as genres and Beethoven, Wagner and Tchaikovsky as composers, and lets you
+enforce restrictions such as that each dataset must have a genre and a
+composer, and that no dataset can have two genres or two composers, etc.
 
-* Override ``db_to_form_schema``. Add your new field to the schema, making sure that it uses the ``convert_from_tags`` validator. If you don't want the tags with vocabularies to be listed along with normal tags (on the web page or via API calls), then make sure that the normal tags field has the ``free_tags_only`` converter applied. For example::
+Another example use-case for tag vocabularies would be to add a *Country Code*
+field to datasets defining the geographical coverage of the dataset, where each
+dataset is assigned a country code such as *en*, *fr*, *de*, etc. See
+``ckanext/example_idatasetform`` for a working example implementation of
+country codes as a tag vocabulary.
 
-    def db_to_form_schema(self):
-        schema = package_form_schema()
-        schema.update({
-            'tags': {'__extras': [keep_extras, free_tags_only]},
-            'vocab_tags': [convert_from_tags('EXAMPLE_VOCAB'), ignore_missing]
-        })
-        return schema
 
-3. Adding To Templates
-~~~~~~~~~~~~~~~~~~~~~~
+Properties of Tag Vocabularies
+------------------------------
 
-* If the vocabulary is restricted, you may want to pass a list of all tags in the vocabulary to the template so that they can be displayed as options in a select (or multi-select) box. This should be done by overriding the ``setup_template_variables`` method in your class that implements ``IDatasetForm``. For example::
+* A CKAN website can have any number of vocabularies.
+* Each vocabulary has an ID and name.
+* Each tag either belongs to a vocabulary, or can be a *free tag* that doesn't
+  belong to any vocabulary (i.e. a normal CKAN tag).
+* A dataset can have more than one tag from the same vocabulary, and can have tags from more than one vocabulary.
 
-    def setup_template_variables(self, context, data_dict=None):
-        c.vocab_tags = get_action('tag_list')(context, {'vocabulary_id': 'EXAMPLE_VOCAB'})
+Using Vocabularies
+------------------
 
-* The custom tags must be added to the template in order to be displayed or edited. For fixed vocabularies, we recommend adding them as a multi-select tag and using the JQuery ``Chosen`` plugin (included in CKAN core).
+To add a tag vocabulary to a site, a CKAN sysadmin must:
 
+1. Call the ``vocabulary_create()`` action of the CKAN API to create the
+   vocabulary and tags. See :doc:`api`.
 
-Examples
---------
+2. Implement an ``IDatasetForm`` plugin to add a new field for the tag
+   vocabulary to the dataset schema. See :doc:`writing-extensions`.
 
-* An example of how to implement it can be found in the section `Customizing Forms` :ref:`example-geospatial-tags`.
+3. Provide custom dataset templates to display the new field to users when
+   adding, updating or viewing datasets in the CKAN web interface.
+   See :doc:`theming`.
 
-* A complete, working example of a custom form that uses tag vocabularies can be found in the CKAN Example extension (http://github.com/okfn/ckanext-example).
+See ``ckanext/example_idatasetform`` for a working example of these steps.