>From fd8d4a8aa28f57b8f98ba1cd2df5afd6c38c4218 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel=20Arruga=20Vivas?=
 <address@hidden>
Date: Sun, 5 May 2019 19:38:57 +0200
Subject: [PATCH 02/15] doc: Add po_xerror_handler_t documentation

* gettext-tools/doc/gettext.texi (libgettextpo): Add struct
po_xerror_handler and its callbacks to the manual.
---
 gettext-tools/doc/gettext.texi | 52 ++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/gettext-tools/doc/gettext.texi b/gettext-tools/doc/gettext.texi
index 2dc34ec47..6442375a3 100644
--- a/gettext-tools/doc/gettext.texi
+++ b/gettext-tools/doc/gettext.texi
@@ -5272,6 +5272,58 @@ for writing PO files are not provided at this time.
 The functions are declared in the header file @samp{<gettext-po.h>}, and are
 defined in a library called @samp{libgettextpo}.
 
address@hidden {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
+two fields, xerror and xerror2, with the following function ignatures.
address@hidden deftp
+
address@hidden void xerror (int @var{severity}, po_message_t @var{message},@
+            const char address@hidden, size_t @var{lineno},@
+            size_t @var{column}, int @var{multiline_p},@
+            const char address@hidden)
+
+This function is called to signal a problem of the given @var{severity}.
+It @emph{must not return} if @var{severity} is
address@hidden
+
address@hidden is the problem description.  When @var{multiline_p}
+is true, it can contain multiple lines of text, each terminated with a
+newline, otherwise a single line.
+
address@hidden and/or @var{filename} and @var{lineno} indicate where the
+problem occurred:
+
address@hidden @bullet
address@hidden
+If @var{filename} is @code{NULL}, @var{filename} and @var{lineno} and
address@hidden should be ignored.
+
address@hidden
+If @var{lineno} is @code{(size_t)(-1)}, @var{lineno} and @var{column}
+should be ignored.
+
address@hidden
+If @var{column} is @code{(size_t)(-1)}, it should be ignored.
address@hidden itemize
address@hidden deftypefun
+
address@hidden void xerror2 (int @var{severity}, po_message_t @var{message1},@
+            const char address@hidden, size_t @var{lineno1},@
+            size_t @var{column1}, int @var{multiline_p1},@
+            const char address@hidden, po_message_t @var{message2},@
+            const char address@hidden, size_t @var{lineno2},@
+            size_t @var{column2}, int @var{multiline_p2},@
+            const char address@hidden)
+
+This function is called to signal a problem of the given @var{severity}
+that refers to two messages.  It @emph{must not return} if
address@hidden is @var{PO_SEVERITY_FATAL_ERROR}.
+
+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}.
address@hidden deftypefun
+
 @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.
-- 
2.21.0