From: Miguel Ángel Arruga Vivas <rosen644835@gmail.com>
Date: Sun, 5 May 2019 18:51:49 +0000 (+0200)
Subject: doc: Split libgettextpo documentation into subsections
X-Git-Tag: v0.21~21
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=8b475393a15e70f35368ba5a1e6db676beb621ed;p=thirdparty%2Fgettext.git

doc: Split libgettextpo documentation into subsections

* gettext-tools/doc/gettext.texi (libgettextpo): Add a menu and split
the functions an types into separate subsections.
(Error Handling): New subsection.
(po_file_t API): New subsection
(po_message_iterator_t API). New subsection.
(po_message_t API): New subsection.
---

diff --git a/gettext-tools/doc/gettext.texi b/gettext-tools/doc/gettext.texi
index c7660b4e0..8a30a827b 100644
--- a/gettext-tools/doc/gettext.texi
+++ b/gettext-tools/doc/gettext.texi
@@ -5331,9 +5331,22 @@ provided too.
 The functions are declared in the header file @samp{<gettext-po.h>}, and are
 defined in a library called @samp{libgettextpo}.
 
+@menu
+* Error Handling::              Error handling functions
+* po_file_t API::               File management
+* po_message_iterator_t API::   Message iteration
+* po_message_t API::            The basic units of the file
+@end menu
+
+@node Error Handling
+@subsection Error Handling
+
+Error management is performed through callbacks provided by the user of
+the library.  They are provided through a parameter with the following
+type:
+
 @deftp {Data Type} struct po_xerror_handler
-This structure contains the functions that will be called in case of
-error.  Its pointer is defined as @code{po_xerror_handler_t}.  Contains
+Its pointer is defined as @code{po_xerror_handler_t}.  Contains
 two fields, xerror and xerror2, with the following function ignatures.
 @end deftp
 
@@ -5383,21 +5396,14 @@ It is similar to two calls to xerror.  If possible, an ellipsis can be
 appended to @var{message_text1} and prepended to @var{message_text2}.
 @end deftypefun
 
+@node po_file_t API
+@subsection po_file_t API
+
 @deftp {Data Type} po_file_t
 This is a pointer type that refers to the contents of a PO file, after it has
 been read into memory.
 @end deftp
 
-@deftp {Data Type} po_message_iterator_t
-This is a pointer type that refers to an iterator that produces a sequence of
-messages.
-@end deftp
-
-@deftp {Data Type} po_message_t
-This is a pointer type that refers to a message of a PO file, including its
-translation.
-@end deftp
-
 @deftypefun po_file_t po_file_create ()
 The @code{po_file_create} creates an empty PO file representation in
 memory.
@@ -5440,6 +5446,14 @@ contain no @samp{domain} directive, the return value contains only one domain,
 namely the default domain @code{"messages"}.
 @end deftypefun
 
+@node po_message_iterator_t API
+@subsection po_message_iterator_t API
+
+@deftp {Data Type} po_message_iterator_t
+This is a pointer type that refers to an iterator that produces a sequence of
+messages.
+@end deftp
+
 @deftypefun po_message_iterator_t po_message_iterator (po_file_t @var{file}, const char *@var{domain})
 The @code{po_message_iterator} returns an iterator that will produce the
 messages of @var{file} that belong to the given @var{domain}.  If @var{domain}
@@ -5458,6 +5472,14 @@ The @code{po_next_message} function returns the next message from
 iterator has reached the end of its message list.
 @end deftypefun
 
+@node po_message_t API
+@subsection po_message_t API
+
+@deftp {Data Type} po_message_t
+This is a pointer type that refers to a message of a PO file, including its
+translation.
+@end deftp
+
 The following functions returns details of a @code{po_message_t}.  Recall
 that the results are valid as long as the @var{file} handle is valid.