Re: [bug-gettext] Libgettextpo documentation

[Bruno Haible]

Hi Miguel,

> In that process I've seen that libgettextpo documentation is quite
> outdated

Indeed. Currently the user has to look at both the manual
https://www.gnu.org/software/gettext/manual/html_node/libgettextpo.html
and the installed gettext-po.h file.

> and I'd like to take care of updating the manual.

This would be very welcome!

> These are the points I have in my TODO list:
> 
>     - [ ] Explain that libgettextpo now can be used for all kind of
>           operations.
>       - Some code paths can be a little bit inefficient, as removing
>       one message implies the creation of a new po_file_t and the
>       insertion of copies of each message except the removed one with
>       the exposed interface.  At least, this should be documented.
> 
>     - [ ] Add error handling API documentation.
> 
>     - [ ] Update po_file_t API documentation.
>       - [ ] Add po_file_create documentation.
>       - [ ] Add po_file_read_v3 documentation.
>       - [ ] Add a note about po_file_read kept for binary
>               compatibility.
>       - [ ] Add po_file_write_v2 documentation.
>       - [ ] Add a note about po_file_write kept for binary
>               compatibility.

There is no need to mention the functions that were kept for
binary compatibility more than 10 years ago. That is, when the .h file
does
  #define po_file_read po_file_read_v3
it is sufficient to document po_file_read_v3 and assume that programs
see this symbol under the name po_file_read.

>     - [ ] Add header API documentation.
>       - [ ] Add a usage description.  The header is the msgstr
>             associated with msgid "" and it contains metadata from the
>           translation unit.  Probably linking ``Header Entry'' would
>             be enough.
>       - [ ] Add po_file_domain_header documentation.
>       - [ ] Add field manipulators.
> 
>     - [ ] Add missing po_message_t accessor API documentation.
>       - [ ] Add msgctxt accessors.
>       - [ ] Add comments accessors.
>       - [ ] Add extracted comments accessors.
>       - [ ] Add stored previous message accessors.
>       - [ ] Add obsolete accessors.
>       - [ ] Add fuzzy accessors.
>       - [ ] Add format accessors.
> 
>     - [ ] Add check API documentation.
>       - [ ] Add po_file_check_all documentation.
>       - [ ] Add po_message_check_all documentation.
>       - [ ] Add po_message_check_format_v2 documentation.
>       - [ ] Add a note about po_message_check_format for binary
>               compatibility.
> 
> What do you think?

These will be valuable additions!

Thanks.

Bruno