[gexiv2] doc: Separate sections by functionality

[Jens Georg <jensgeorg src gnome org>]

commit 5760f45573cbd59d3662dc788aa8b8ad35807bf5
Author: Jens Georg <mail jensge org>
Date:   Sat Feb 20 12:00:18 2021 +0100

    doc: Separate sections by functionality

 docs/reference/gexiv2-docs.xml     |  11 ++-
 docs/reference/gexiv2-sections.txt | 152 +++++++++++++++++++++----------------
 gexiv2/gexiv2-metadata.h           |  58 ++++++++++++++
 3 files changed, 154 insertions(+), 67 deletions(-)
---
diff --git a/docs/reference/gexiv2-docs.xml b/docs/reference/gexiv2-docs.xml
index 7facd8f..3acf400 100644
--- a/docs/reference/gexiv2-docs.xml
+++ b/docs/reference/gexiv2-docs.xml
@@ -17,13 +17,18 @@
   </bookinfo>
 
   <chapter>
-      <title>GExiv2</title>
-      <xi:include href="xml/gexiv2-log.xml"/>
+      <title>GExiv2 image metadata handling library</title>
+      <xi:include href="xml/gexiv2-startup.xml"/>
       <xi:include href="xml/gexiv2-metadata.xml"/>
+      <xi:include href="xml/gexiv2-io.xml"/>
+      <xi:include href="xml/gexiv2-convenience.xml"/>
+      <xi:include href="xml/gexiv2-metadata-exif.xml"/>
+      <xi:include href="xml/gexiv2-metadata-xmp.xml"/>
+      <xi:include href="xml/gexiv2-metadata-iptc.xml"/>
       <xi:include href="xml/gexiv2-preview-image.xml"/>
       <xi:include href="xml/gexiv2-preview-properties.xml"/>
-      <xi:include href="xml/gexiv2-startup.xml"/>
       <xi:include href="xml/gexiv2-version.xml"/>
+      <xi:include href="xml/gexiv2-log.xml"/>
 
   </chapter>
   <index id="api-index-full">
diff --git a/docs/reference/gexiv2-sections.txt b/docs/reference/gexiv2-sections.txt
index dd83768..f67162e 100644
--- a/docs/reference/gexiv2-sections.txt
+++ b/docs/reference/gexiv2-sections.txt
@@ -14,54 +14,32 @@ gexiv2_gexiv2_log_level_get_type
 </SECTION>
 
 <SECTION>
-<FILE>gexiv2-metadata</FILE>
-<TITLE>GExiv2Metadata</TITLE>
-GExiv2Orientation
-GExiv2StructureType
+<FILE>gexiv2-metadata-xmp</FILE>
 GExiv2XmpFormatFlags
-GExiv2Metadata
-GExiv2ByteOrder
-gexiv2_metadata_new
-gexiv2_metadata_free
-gexiv2_metadata_open_path
-gexiv2_metadata_open_buf
-gexiv2_metadata_open_stream
-gexiv2_metadata_from_stream
-gexiv2_metadata_from_app1_segment
-gexiv2_metadata_save_external
-gexiv2_metadata_save_file
-gexiv2_metadata_save_stream
-gexiv2_metadata_has_tag
-gexiv2_metadata_clear_tag
-gexiv2_metadata_clear
-gexiv2_metadata_is_exif_tag
-gexiv2_metadata_is_iptc_tag
 gexiv2_metadata_is_xmp_tag
-gexiv2_metadata_get_tag_label
-gexiv2_metadata_get_tag_description
-gexiv2_metadata_get_tag_type
-gexiv2_metadata_get_supports_exif
-gexiv2_metadata_get_supports_iptc
 gexiv2_metadata_get_supports_xmp
-gexiv2_metadata_get_mime_type
-gexiv2_metadata_get_pixel_width
-gexiv2_metadata_get_pixel_height
-gexiv2_metadata_get_tag_string
-gexiv2_metadata_try_get_tag_string
-gexiv2_metadata_set_tag_string
-gexiv2_metadata_try_set_tag_string
+gexiv2_metadata_has_xmp
 gexiv2_metadata_set_xmp_tag_struct
-gexiv2_metadata_get_tag_interpreted_string
-gexiv2_metadata_get_tag_long
-gexiv2_metadata_set_tag_long
-gexiv2_metadata_get_tag_multiple
-gexiv2_metadata_try_get_tag_multiple
-gexiv2_metadata_set_tag_multiple
-gexiv2_metadata_try_set_tag_multiple
-gexiv2_metadata_get_tag_raw
+gexiv2_metadata_clear_xmp
+gexiv2_metadata_generate_xmp_packet
+gexiv2_metadata_get_xmp_packet
+gexiv2_metadata_get_xmp_tags
+gexiv2_metadata_register_xmp_namespace
+gexiv2_metadata_unregister_xmp_namespace
+gexiv2_metadata_unregister_all_xmp_namespaces
+gexiv2_metadata_get_xmp_namespace_for_tag
+<SUBSECTION Standard>
+GEXIV2_TYPE_GEXIV2_XMP_FORMAT_FLAGS
+gexiv2_gexiv2_xmp_format_flags_get_type
+</SECTION>
+
+<SECTION>
+<FILE>gexiv2-metadata-exif</FILE>
+gexiv2_metadata_is_exif_tag
+gexiv2_metadata_get_supports_exif
 gexiv2_metadata_has_exif
-gexiv2_metadata_clear_exif
 gexiv2_metadata_get_exif_tags
+gexiv2_metadata_clear_exif
 gexiv2_metadata_get_exif_tag_rational
 gexiv2_metadata_set_exif_tag_rational
 gexiv2_metadata_get_exif_thumbnail
@@ -69,18 +47,42 @@ gexiv2_metadata_get_exif_data
 gexiv2_metadata_set_exif_thumbnail_from_file
 gexiv2_metadata_set_exif_thumbnail_from_buffer
 gexiv2_metadata_erase_exif_thumbnail
-gexiv2_metadata_has_xmp
-gexiv2_metadata_clear_xmp
-gexiv2_metadata_generate_xmp_packet
-gexiv2_metadata_get_xmp_packet
-gexiv2_metadata_get_xmp_tags
-gexiv2_metadata_register_xmp_namespace
-gexiv2_metadata_unregister_xmp_namespace
-gexiv2_metadata_unregister_all_xmp_namespaces
-gexiv2_metadata_get_xmp_namespace_for_tag
+</SECTION>
+
+<SECTION>
+<FILE>gexiv2-metadata-iptc</FILE>
+gexiv2_metadata_is_iptc_tag
+gexiv2_metadata_get_supports_iptc
 gexiv2_metadata_has_iptc
 gexiv2_metadata_clear_iptc
 gexiv2_metadata_get_iptc_tags
+</SECTION>
+
+<SECTION>
+<FILE>gexiv2-io</FILE>
+gexiv2_metadata_open_path
+gexiv2_metadata_open_buf
+gexiv2_metadata_from_stream
+gexiv2_metadata_from_app1_segment
+gexiv2_metadata_save_external
+gexiv2_metadata_save_file
+gexiv2_metadata_open_stream
+gexiv2_metadata_save_stream
+Stream_CanSeek
+Stream_CanRead
+Stream_CanWrite
+Stream_Length
+Stream_Position
+Stream_Read
+Stream_Write
+Stream_Seek
+Stream_Flush
+ManagedStreamCallbacks
+WrapperSeekOrigin
+</SECTION>
+
+<SECTION>
+<FILE>gexiv2-convenience</FILE>
 gexiv2_metadata_get_orientation
 gexiv2_metadata_set_orientation
 gexiv2_metadata_get_metadata_pixel_width
@@ -103,17 +105,38 @@ gexiv2_metadata_update_gps_info
 gexiv2_metadata_delete_gps_info
 gexiv2_metadata_get_preview_properties
 gexiv2_metadata_get_preview_image
-WrapperSeekOrigin
-Stream_CanSeek
-Stream_CanRead
-Stream_CanWrite
-Stream_Length
-Stream_Position
-Stream_Read
-Stream_Write
-Stream_Seek
-Stream_Flush
-ManagedStreamCallbacks
+</SECTION>
+
+<SECTION>
+<FILE>gexiv2-metadata</FILE>
+<TITLE>GExiv2Metadata</TITLE>
+GExiv2Orientation
+GExiv2StructureType
+GExiv2Metadata
+GExiv2ByteOrder
+gexiv2_metadata_new
+gexiv2_metadata_free
+gexiv2_metadata_has_tag
+gexiv2_metadata_clear_tag
+gexiv2_metadata_clear
+gexiv2_metadata_get_tag_label
+gexiv2_metadata_get_tag_description
+gexiv2_metadata_get_tag_type
+gexiv2_metadata_get_mime_type
+gexiv2_metadata_get_pixel_width
+gexiv2_metadata_get_pixel_height
+gexiv2_metadata_get_tag_string
+gexiv2_metadata_try_get_tag_string
+gexiv2_metadata_set_tag_string
+gexiv2_metadata_try_set_tag_string
+gexiv2_metadata_get_tag_interpreted_string
+gexiv2_metadata_get_tag_long
+gexiv2_metadata_set_tag_long
+gexiv2_metadata_get_tag_multiple
+gexiv2_metadata_try_get_tag_multiple
+gexiv2_metadata_set_tag_multiple
+gexiv2_metadata_try_set_tag_multiple
+gexiv2_metadata_get_tag_raw
 <SUBSECTION Standard>
 GEXIV2_IS_METADATA
 GEXIV2_IS_METADATA_CLASS
@@ -126,12 +149,13 @@ GExiv2MetadataPrivate
 gexiv2_metadata_get_type
 GEXIV2_TYPE_GEXIV2_BYTE_ORDER
 GEXIV2_TYPE_GEXIV2_ORIENTATION
-GEXIV2_TYPE_GEXIV2_XMP_FORMAT_FLAGS
 GEXIV2_TYPE_GEXIV2_STRUCTURE_TYPE
 gexiv2_gexiv2_byte_order_get_type
 gexiv2_gexiv2_orientation_get_type
 gexiv2_gexiv2_structure_type_get_type
-gexiv2_gexiv2_xmp_format_flags_get_type
+collate_key
+ptr_type
+size_type
 </SECTION>
 
 <SECTION>
diff --git a/gexiv2/gexiv2-metadata.h b/gexiv2/gexiv2-metadata.h
index f79b85d..581b84d 100644
--- a/gexiv2/gexiv2-metadata.h
+++ b/gexiv2/gexiv2-metadata.h
@@ -19,7 +19,9 @@
 
 /**
  * SECTION: gexiv2-metadata
+ * @title: Generic image metadata handling
  * @short_description: Class to handle the various image metadata standards
+ * @include: gexiv2/gexiv2.h
  *
  * #GExiv2Metadata is a generic object that provides everything from simple
  * aggregated accessors to common data such as image comments up to
@@ -27,11 +29,43 @@
  * or XMP
  */
 
+/**
+ * SECTION: gexiv2-metadata-xmp
+ * @short_description: Functionality specific to the XMP familiy of metadata information
+ * @title: Functions related to XMP metadata
+ * @include: gexiv2/gexiv2.h
+ *
+ * While being part of #GExiv2Metadata, these functions are dealing with specific
+ * aspects of XMP
+ */
+
+/**
+ * SECTION: gexiv2-metadata-exif
+ * @short_description: Functionality specific to the EXIF familiy of metadata information
+ * @title: Functions related to EXIF metadata
+ * @include: gexiv2/gexiv2.h
+ *
+ * While being part of #GExiv2Metadata, these functions are dealing with specific
+ * aspects of EXIF
+ */
+
+/**
+ * SECTION: gexiv2-metadata-iptc
+ * @short_description: Functionality specific to the IPTC familiy of metadata information
+ * @title: Functions related to IPTC metadata
+ * @include: gexiv2/gexiv2.h
+ *
+ * While being part of #GExiv2Metadata, these functions are dealing with specific
+ * aspects of IPTC
+ */
+
 /**
  * SECTION: gexiv2-preview-image
+ * @title: Preview images
  * @short_description: Class describing preview images (or thumbnails) that
  * are part of the metadata.
  * @see_also: #GExiv2Metadata #GExiv2PreviewProperties
+ * @include: gexiv2/gexiv2.h
  *
  * #GExiv2PreviewImage is an accessor to the preview images contained in
  * the image's metadata. This could be anything from a thumbnail to a
@@ -53,6 +87,7 @@
 
 /**
  * SECTION: gexiv2-preview-properties
+ * @title: Properties of preview images
  * @short_description: Class describing properties of a preview image
  * @see_also: #GExiv2Metadata #GExiv2PreviewProperties
  *
@@ -61,6 +96,29 @@
  * image from the metadata.
  */
 
+/**
+ * SECTION: gexiv2-version
+ * @title: Library version information
+ * @short_description: Utilities for querying the library version
+ *
+ * Provides macros and functions to query the version of the GExiv2 library during compile- and runtime.
+ */
+
+/**
+ * SECTION: gexiv2-io
+ * @title: Reading and writing metadata
+ * @short_description: How to read and write metadata from files and memory
+ */
+
+/**
+ * SECTION: gexiv2-convenience
+ * @title: High-level functions for specific information
+ * @short_description: A set of helper functions to simplify accessing specific information
+ *
+ * The functions in this section will use several individual tags to provide or set
+ * the required information while trying to follow the MWG recommendations
+ */
+
 G_BEGIN_DECLS
 
 #define GEXIV2_TYPE_METADATA \