doc: Add Header Entry API

* gettext-tools/doc/gettext.texi (PO Header Entry API): New
subsection.  Add po_file_domain_header, po_header_field and
po_header_set_field documentation.
(libgettextpo): Add subsection to the menu.

diff --git a/gettext-tools/doc/gettext.texi b/gettext-tools/doc/gettext.texi
index 5de247b4f84059b51b568cbe9e79e5121a444803..83fe1030657d4d1f8d05fb85801405ba05eb7add 100644 (file)
--- a/gettext-tools/doc/gettext.texi
+++ b/gettext-tools/doc/gettext.texi
@@ -5336,6 +5336,7 @@ defined in a library called @samp{libgettextpo}.
 * po_file_t API::               File management
 * po_message_iterator_t API::   Message iteration
 * po_message_t API::            The basic units of the file
+* PO Header Entry API::         Meta information of the file
 @end menu
 
 The following example shows code how these functions can be used.  Error
@@ -5634,6 +5635,35 @@ comments of a message to the value @var{extracted_comments}, a multiline
 string, ending in a newline, or a non-@code{NULL} empty string.
 @end deftypefun
 
+@node PO Header Entry API
+@subsection PO Header Entry API
+
+The following functions provide an interface to extract and manipulate
+the header entry (@pxref{Header Entry}) from a file loaded in memory.
+The meta information must be written back into the domain message with
+the empty string as msgid.
+
+@deftypefun {const char *} po_file_domain_header (po_file_t @var{file},@
+                           const char *@var{domain})
+Return the header entry of a domain from @var{file}, a PO file loaded in
+memory.  The value @code{NULL} provided as @var{domain} denotes the
+default domain.  Return @code{NULL} if there is no header entry.
+@end deftypefun
+
+@deftypefun {char *} po_header_field (const char *@var{header},@
+                     const char *@var{field})
+Return the value of @var{field} in the @var{header} entry.  The return
+value is either a freshly allocated string, to be freed by the caller,
+or @code{NULL}.
+@end deftypefun
+
+@deftypefun {char *} po_header_set_field (const char *@var{header},@
+                     const char *@var{field}, const char *@var{value})
+Return a freshly allocated string which contains the entry from
+@var{header} with @var{field} set to @var{value}.  The field is added if
+necessary.
+@end deftypefun
+
 @node Binaries
 @chapter Producing Binary MO Files