Tutorial: reading and writing IPTC tags.

1 files changed, 77 insertions, 10 deletions

diff --git a/doc/tutorial.rst b/doc/tutorial.rst
index 36d26a6..c1993c8 100644
--- a/doc/tutorial.rst
+++ b/doc/tutorial.rst
@@ -4,6 +4,8 @@ Tutorial
 This tutorial is meant to give you a quick overview of what pyexiv2 allows you
 to do. You can just read it through or follow it interactively, in which case
 you will need to have pyexiv2 installed.
+It doesn't cover all the possibilities offered by pyexiv2, only a basic subset
+of them. For complete reference, see the :doc:`api`.
 
 Let's get started!
 
@@ -11,7 +13,7 @@ First of all, we import the pyexiv2 module::
 
   >>> import pyexiv2
 
-We then load a JPEG image file and read its metadata::
+We then load an image file and read its metadata::
 
   >>> metadata = pyexiv2.ImageMetadata('test.jpg')
   >>> metadata.read()
@@ -22,9 +24,6 @@ Reading and writing EXIF tags
 Let's retrieve a list of all the available EXIF tags available in the image::
 
   >>> metadata.exif_keys
-
-This returns a list of EXIF keys, much like this:: 
-
   ['Exif.Image.ImageDescription',
    'Exif.Image.XResolution',
    'Exif.Image.YResolution',
@@ -59,8 +58,8 @@ manipulation.
 
 Note that querying the value of a tag may raise an :exc:`ExifValueError` if the
 format of the raw value is invalid according to the EXIF specification (may
-happen if it was written by other software that implement the specification in a
-broken manner), or if pyexiv2 doesn't know how to convert it to a convenient
+happen if it was written by other software that implements the specification in
+a broken manner), or if pyexiv2 doesn't know how to convert it to a convenient
 python object.
 
 Accessing the value of a tag as a python object allows easy manipulation and
@@ -71,8 +70,8 @@ formatting::
 
 Let's now modify the value of the tag and write it back to the file::
 
-  >>> from datetime import datetime
-  >>> tag.value = datetime.today()
+  >>> import datetime
+  >>> tag.value = datetime.datetime.today()
 
   >>> metadata.write()
 
@@ -81,10 +80,78 @@ Similarly to reading the value of a tag, one can set either the
 a correctly formatted byte string by pyexiv2).
 
 You can also add new tags to the metadata by providing a valid key and value
-pair (for a list of valid EXIF tags, see
-`exiv2's documentation <http://exiv2.org/tags.html>`_)::
+pair (see exiv2's documentation for a list of valid
+`EXIF tags <http://exiv2.org/tags.html>`_)::
 
   >>> key = 'Exif.Photo.UserComment'
   >>> value = 'This is a useful comment.'
   >>> metadata[key] = pyexiv2.ExifTag(key, value)
 
+
+Reading and writing IPTC tags
+#############################
+
+Reading and writing IPTC tags works pretty much the same way as with EXIF tags.
+Let's retrieve the list of all available IPTC tags in the image::
+
+  >>> metadata.iptc_keys
+  ['Iptc.Application2.Caption',
+   'Iptc.Application2.Writer',
+   'Iptc.Application2.Byline',
+   'Iptc.Application2.ObjectName',
+   'Iptc.Application2.DateCreated',
+   'Iptc.Application2.City',
+   'Iptc.Application2.ProvinceState',
+   'Iptc.Application2.CountryName',
+   'Iptc.Application2.Category',
+   'Iptc.Application2.Keywords',
+   'Iptc.Application2.Copyright']
+
+Each of those tags can be accessed with the ``[]`` operator on the metadata::
+
+  >>> tag = metadata['Iptc.Application2.DateCreated']
+
+An IPTC tag always has a list of values rather than a single value.
+This is because some tags have a repeatable character.
+Tags that are not repeatable only hold one value in their list of values.
+
+Check the :attr:`repeatable` attribute to know whether a tag can hold more than
+one value::
+
+  >>> tag.repeatable
+  False
+
+As with EXIF tags, the values of an :class:`IptcTag` object can be accessed in
+two different ways: with the :attr:`raw_values` and with the :attr:`values`
+attributes::
+
+  >>> tag.raw_values
+  ['2004-07-13']
+
+  >>> tag.values
+  [datetime.date(2004, 7, 13)]
+
+Note that querying the value of a tag may raise an :exc:`IptcValueError` if the
+format of the raw value is invalid according to the IPTC specification (may
+happen if it was written by other software that implements the specification in
+a broken manner), or if pyexiv2 doesn't know how to convert it to a convenient
+python object.
+
+Let's now modify the values of the tag and write it back to the file::
+
+  >>> tag.values = [datetime.date.today()]
+
+  >>> metadata.write()
+
+Similarly to reading the values of a tag, one can set either the
+:attr:`raw_values` or the :attr:`values` (which will be automatically converted
+to correctly formatted byte strings by pyexiv2).
+
+You can also add new tags to the metadata by providing a valid key and values
+pair (see exiv2's documentation for a list of valid
+`IPTC tags <http://exiv2.org/iptc.html>`_)::
+
+  >>> key = 'Iptc.Application2.Contact'
+  >>> values = ['John', 'Paul', 'Ringo', 'George']
+  >>> metadata[key] = pyexiv2.IptcTag(key, values)
+