>From e0709494468b519655cdab66a7eaa632ca9a0ea9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel=20Arruga=20Vivas?=
 <address@hidden>
Date: Mon, 6 May 2019 14:37:32 +0200
Subject: [PATCH 07/15] doc: Update libgettextpo example

* gettext-tools/doc/gettext.texi (libgettextpo): Update example to the
latest API.
---
 gettext-tools/doc/gettext.texi | 42 +++++++++++++++++++++++-----------
 1 file changed, 29 insertions(+), 13 deletions(-)

diff --git a/gettext-tools/doc/gettext.texi b/gettext-tools/doc/gettext.texi
index 8bc315ebc..fd99356b5 100644
--- a/gettext-tools/doc/gettext.texi
+++ b/gettext-tools/doc/gettext.texi
@@ -5280,39 +5280,55 @@ defined in a library called @samp{libgettextpo}.
 * po_message_t API::            The basic units of the file
 @end menu
 
-Here is an example code how these functions can be used.
+The following example shows code how these functions can be used.  Error
+handling code is omitted, as its implementation is delegated to the user
+provided functions.
 
 @example
+struct po_xerror_handler handler =
+  @{
+    .xerror = @dots{},
+    .xerror2 = @dots{}
+  @};
 const char *filename = @dots{};
-po_file_t file = po_file_read (filename);
+/* Read the file into memory.  */
+po_file_t file = po_file_read (filename, &handler);
 
-if (file == NULL)
-  error (EXIT_FAILURE, errno, "couldn't open the PO file %s", filename);
 @{
   const char * const *domains = po_file_domains (file);
   const char * const *domainp;
 
+  /* Iterate the domains contained in the file.  */
   for (domainp = domains; *domainp; domainp++)
     @{
+      po_message_t *message;
       const char *domain = *domainp;
       po_message_iterator_t iterator = po_message_iterator (file, domain);
 
-      for (;;)
+      /* Iterate each message inside the domain.  */
+      while ((message = po_next_message (iterator)) != NULL)
         @{
-          po_message_t *message = po_next_message (iterator);
+          /* Read data from the message @dots{}  */
+          const char *msgid = po_message_msgid (message);
+          const char *msgstr = po_message_msgstr (message);
+
+          @dots{}
 
-          if (message == NULL)
-            break;
-          @{
-            const char *msgid = po_message_msgid (message);
-            const char *msgstr = po_message_msgstr (message);
+          /* Modify its contents @dots{}  */
+          if (perform_some_tests (msgid, msgstr))
+            po_message_set_fuzzy (message, 1);
 
-            @dots{}
-          @}
+          @dots{}
         @}
+      /* Always release returned po_message_iterator_t.  */
       po_message_iterator_free (iterator);
     @}
+
+  /* Write back the result.  */
+  po_file_t result = po_file_write (file, filename, &handler);
 @}
+
+/* Always release the returned po_file_t.  */
 po_file_free (file);
 @end example
 
-- 
2.21.0