From: Bruno Haible Date: Sun, 26 Jul 2020 19:55:09 +0000 (+0200) Subject: doc: Tweak libgettextpo chapter. X-Git-Tag: v0.21~6 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d753131d459d4e29a46186a7075ae7c1834f8c94;p=thirdparty%2Fgettext.git doc: Tweak libgettextpo chapter. * gettext-tools/doc/gettext.texi (libgettextpo): Very small tweaks. --- diff --git a/gettext-tools/doc/gettext.texi b/gettext-tools/doc/gettext.texi index c50271c25..90eba7997 100644 --- a/gettext-tools/doc/gettext.texi +++ b/gettext-tools/doc/gettext.texi @@ -5403,14 +5403,15 @@ type: @deftp {Data Type} struct po_xerror_handler Its pointer is defined as @code{po_xerror_handler_t}. Contains -two fields, xerror and xerror2, with the following function ignatures. +two fields, @code{xerror} and @code{xerror2}, with the following function +signatures. @end deftp @deftypefun void xerror (int@tie{}@var{severity}, po_message_t@tie{}@var{message}, const@tie{}char@tie{}*@var{filename}, size_t@tie{}@var{lineno}, size_t@tie{}@var{column}, int@tie{}@var{multiline_p}, const@tie{}char@tie{}*@var{message_text}) This function is called to signal a problem of the given @var{severity}. It @emph{must not return} if @var{severity} is -@var{PO_SEVERITY_FATAL_ERROR}. +@code{PO_SEVERITY_FATAL_ERROR}. @var{message_text} is the problem description. When @var{multiline_p} is true, it can contain multiple lines of text, each terminated with a @@ -5437,7 +5438,7 @@ If @var{column} is @code{(size_t)(-1)}, it should be ignored. This function is called to signal a problem of the given @var{severity} that refers to two messages. It @emph{must not return} if -@var{severity} is @var{PO_SEVERITY_FATAL_ERROR}. +@var{severity} is @code{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}. @@ -5452,7 +5453,7 @@ been read into memory. @end deftp @deftypefun po_file_t po_file_create () -The @code{po_file_create} creates an empty PO file representation in +The @code{po_file_create} function creates an empty PO file representation in memory. @end deftypefun @@ -5462,7 +5463,7 @@ is given as argument. The return value is a handle to the PO file's contents, valid until @code{po_file_free} is called on it. In case of error, the functions from @var{handler} are called to signal it. -This function is exported as @samp{po_file_read_v3} at ABI level, but it +This function is exported as @samp{po_file_read_v3} at ABI level, but is defined as @code{po_file_read} in C code after the inclusion of @samp{}. @end deftypefun @@ -5474,7 +5475,7 @@ structure @var{file} the @var{filename} given. The return value is functions from @var{handler} are called to signal it. This function is exported as @samp{po_file_write_v2} at ABI level, but -it defined as @code{po_file_write} in C code after the inclusion of +is defined as @code{po_file_write} in C code after the inclusion of @samp{}. @end deftypefun @@ -5526,10 +5527,10 @@ translation. @end deftp @deftypefun {po_message_t} po_message_create (void) -Return a freshly constructed message. To finish initializing the -message, you must set the msgid and msgstr. It @emph{must} be inserted -into a file to manage its memory, as there is no @code{po_message_free} -available to the user of the library. +Returns a freshly constructed message. To finish initializing the +message, you must set the @code{msgid} and @code{msgstr}. It @emph{must} be +inserted into a file to manage its memory, as there is no +@code{po_message_free} available to the user of the library. @end deftypefun The following functions access details of a @code{po_message_t}. Recall @@ -5537,14 +5538,14 @@ that the results are valid as long as the @var{file} handle is valid. @deftypefun {const char *} po_message_msgctxt (po_message_t@tie{}@var{message}) The @code{po_message_msgctxt} function returns the @code{msgctxt}, the -context of @var{message}. Return @code{NULL} for a message not restricted +context of @var{message}. Returns @code{NULL} for a message not restricted to a context. @end deftypefun @deftypefun {void} po_message_set_msgctxt (po_message_t@tie{}@var{message}, const@tie{}char@tie{}*@var{msgctxt}) The @code{po_message_set_msgctxt} function changes the @code{msgctxt}, the context of the message, to the value provided through -@var{msgctxt}. The value @code{NULL} removes the restriction. +@var{msgctxt}. The value @code{NULL} removes the restriction. @end deftypefun @deftypefun {const char *} po_message_msgid (po_message_t@tie{}@var{message}) @@ -5697,14 +5698,14 @@ the message for the @var{format_type} provided. @deftypefun {int} po_message_is_range (po_message_t@tie{}@var{message}, int@tie{}*@var{minp}, int@tie{}*@var{maxp}) The @code{po_message_is_range} function returns true when the message has a numeric range set, and stores the minimum and maximum value in the -direction pointed by @var{minp} and @var{maxp} respectively. +locations pointed by @var{minp} and @var{maxp} respectively. @end deftypefun @deftypefun {void} po_message_set_range (po_message_t@tie{}@var{message}, int@tie{}@var{min}, int@tie{}@var{max}) The @code{po_message_set_range} function changes the numeric range of the message. @var{min} and @var{max} must be non-negative, with @var{min} < @var{max}. Use @var{min} and @var{max} with value @code{-1} -to remove the numeric range of @var{message} +to remove the numeric range of @var{message}. @end deftypefun @node PO Header Entry API @@ -5713,22 +5714,22 @@ to remove the numeric range of @var{message} 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. +the empty string as @code{msgid}. @deftypefun {const char *} po_file_domain_header (po_file_t@tie{}@var{file}, const@tie{}char@tie{}*@var{domain}) -Return the header entry of a domain from @var{file}, a PO file loaded in +Returns 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. +default domain. Returns @code{NULL} if there is no header entry. @end deftypefun @deftypefun {char *} po_header_field (const@tie{}char@tie{}*@var{header}, const@tie{}char@tie{}*@var{field}) -Return the value of @var{field} in the @var{header} entry. The return +Returns 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@tie{}char@tie{}*@var{header}, const@tie{}char@tie{}*@var{field}, const@tie{}char@tie{}*@var{value}) -Return a freshly allocated string which contains the entry from +Returns 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 @@ -5745,17 +5746,17 @@ The following functions provide an interface to extract and manipulate these references. @deftypefun {po_filepos_t} po_message_filepos (po_message_t@tie{}@var{message}, int@tie{}@var{index}) -Return the file reference in position @var{index} from the message. If -@var{index} is out of range, return @code{NULL}. +Returns the file reference in position @var{index} from the message. If +@var{index} is out of range, returns @code{NULL}. @end deftypefun @deftypefun {void} po_message_remove_filepos (po_message_t@tie{}@var{message}, int@tie{}@var{index}) -Remove the file reference in position @var{index} from the message. It +Removes the file reference in position @var{index} from the message. It moves all references following @var{index} one position backwards. @end deftypefun @deftypefun {void} po_message_add_filepos (po_message_t@tie{}@var{message}, const@tie{}char@tie{}*@var{file}, size_t@tie{}@var{start_line}) -Add a reference to the string from @var{file} starting at +Adds a reference to the string from @var{file} starting at @var{start_line}, if it is not already present for the message. The value @code{(size_t)(-1)} for @var{start_line} denotes that the line number is not available. @@ -5765,11 +5766,11 @@ number is not available. @subsection Format Type API @deftypefun {const char * const *} po_format_list (void) -Return a @code{NULL} terminated array of the supported format types. +Returns a @code{NULL} terminated array of the supported format types. @end deftypefun @deftypefun {const char *} po_format_pretty_name (const@tie{}char@tie{}*@var{format_type}) -Return the pretty name associated with @var{format_type}. For example, +Returns the pretty name associated with @var{format_type}. For example, it returns ``C#'' when @var{format_type} is ``csharp_format''. Return @code{NULL} if @var{format_type} is not a supported format type. @end deftypefun @@ -5778,24 +5779,24 @@ Return @code{NULL} if @var{format_type} is not a supported format type. @subsection Checking API @deftypefun {void} po_file_check_all (po_file_t@tie{}@var{file}, po_xerror_handler_t@tie{}@var{handler}) -Test whether the entire @var{file} is valid, like msgfmt does it. If it -is invalid, pass the reasons to @var{handler}. +Tests whether the entire @var{file} is valid, like @code{msgfmt} does it. If it +is invalid, passes the reasons to @var{handler}. @end deftypefun @deftypefun {void} po_message_check_all (po_message_t@tie{}@var{message}, po_message_iterator_t@tie{}@var{iterator}, po_xerror_handler_t@tie{}@var{handler}) -Test @var{message}, to be inserted at @var{iterator} in a PO file in memory, -like msgfmt does it. If it is invalid, pass the reasons to +Tests @var{message}, to be inserted at @var{iterator} in a PO file in memory, +like @code{msgfmt} does it. If it is invalid, passes the reasons to @var{handler}. @var{iterator} is not modified by this call; it only specifies the file and the domain. @end deftypefun @deftypefun {void} po_message_check_format (po_message_t@tie{}@var{message}, po_xerror_handler_t@tie{}@var{handler}) -Test whether the message translation from @var{message} is a valid +Tests whether the message translation from @var{message} is a valid format string if the message is marked as being a format string. If it -is invalid, pass the reasons to @var{handler}. +is invalid, passes the reasons to @var{handler}. This function is exported as @samp{po_message_check_format_v2} at ABI -level, but it defined as @code{po_message_check_format} in C code after +level, but is defined as @code{po_message_check_format} in C code after the inclusion of @samp{}. @end deftypefun