Re: [bug-gnulib] Fixing argp doc strings

[Bruno Haible]

Sergey Poznyakoff wrote:
> 2006-09-09  Sergey Poznyakoff  <address@hidden>
> 
>         * argp-help.c (argp_doc): Split the untranslated doc string on
>           '\v', and translate the two parts separately, instead of
>           feeding the whole string to gettext.  This allows to exclude
>           '\v' from the msgids visible to the translator by writing doc
>           strings as N_("..") "\v" N_("..").

Thanks for doing that. Additionally, how about documenting this
(non-obvious) convention? Something like this:

*** argp.h      10 Jan 2006 21:49:07 -0000      1.11
--- argp.h      9 Sep 2006 14:53:48 -0000
***************
*** 243,249 ****
  
    /* If non-NULL, a string containing extra text to be printed before and
       after the options in a long help message (separated by a vertical tab
!      `\v' character).  */
    const char *doc;
  
    /* A vector of argp_children structures, terminated by a member with a 0
--- 243,251 ----
  
    /* If non-NULL, a string containing extra text to be printed before and
       after the options in a long help message (separated by a vertical tab
!      `\v' character).
!      Write the initial value as N_("BEFORE-TEXT") "\v" N_("AFTER-TEXT") if
!      you want xgettext to collect the two pieces of text into a POT file.  */
    const char *doc;
  
    /* A vector of argp_children structures, terminated by a member with a 0


Also, one could mention the need of N_(...) in the documentation of
the field 'doc' of struct argp_option as well:

*** argp.h      10 Jan 2006 21:49:07 -0000      1.11
--- argp.h      9 Sep 2006 14:59:55 -0000
***************
*** 94,100 ****
    /* The doc string for this option.  If both NAME and KEY are 0, This string
       will be printed outdented from the normal option column, making it
       useful as a group header (it will be the first thing printed in its
!      group); in this usage, it's conventional to end the string with a `:'.  
*/
    const char *doc;
  
    /* The group this option is in.  In a long help message, options are sorted
--- 94,102 ----
    /* The doc string for this option.  If both NAME and KEY are 0, This string
       will be printed outdented from the normal option column, making it
       useful as a group header (it will be the first thing printed in its
!      group); in this usage, it's conventional to end the string with a `:'.
!      Write the initial value as N_("TEXT") if  you want xgettext to collect
!      it into a POT file.  */
    const char *doc;
  
    /* The group this option is in.  In a long help message, options are sorted


Bruno