[I18n-sig] Re: pygettext.py extraction of docstrings

[Barry A. Warsaw]

Hi Francois!  I'm Cc'ing Bruno on this message because I think he's
the current gettext maintainer.  Sorry if I'm mistaken...

>>>>> "FP" =3D=3D Fran=E7ois Pinard <pinard@iro.umontreal.ca> writes:

    >> Then again, it doesn't say that #. comments are reserved.  It
    >> basically just says that #-whitespace comments are reserved for
    >> the translators.

    FP> You might consider that they are all reserved.

    >> I'm happy to switch it, but I'd really like to have a reference
    >> I can point to to short-circuit any further discussion.  Even a
    >> mailing list archive url would be fine.

    FP> If I remember well, `#.' are for textual comments written by
    FP> the program maintainer, meant to be read by translators, and
    FP> derived automatically at POT creation time.  They usually come
    FP> from specially formatted comments in the C sources.
    FP> `#-whitespace' are for textual comments also meant to be read
    FP> by various translators, but written by translators themselves.

This makes sense.  It would be good to make this a bit clearer in the
"Format of PO Files" section of the GNU gettext manual.

    FP> `#,' are for programmatic flags.  The idea was to use these
    FP> parsimoniously, keeping track of possible flag definitions and
    FP> consequences.  I do not know how far these are recognized and
    FP> validated by `msgfmt'.  Best would be to coordinate with the
    FP> current `gettext' maintainer before creating new ones.  Unless
    FP> he declares they are now for free use?

A while back I was convinced to switch the `docstring' flag to #, for
pygettext.  Perhaps Bruno can add some information on pygettext.py in
the GNU gettext manual?  I think the following would be of interest:

- Mention the existence of pygettext.py for extracting translatable
  strings in Python.

- Point to Python's gettext module documentation for more details on
  i18n'ing Python programs.  This should be a fairly stable url:

  http://www.python.org/doc/current/lib/module-gettext.html

- Document `docstring' as a legal #,-style flag.  It probably only has
  meaning in Python, but may be useful in other scripting languages.
  Think of it roughly equivalent to Emacs-Lisp docstrings (in fact,
  they were the inspiration for Python docstrings back in '94 at the
  1st Python workshop!)

- Make sure that the other GNU gettext tools recognize the docstring
  flag, in whatever way is meaningful (I'm not sure what would be
  useful or not... ;).

Thanks.  BTW, for my purposes, pygettext.py's -X/--no-docstrings
switch does the job perfectly, if a bit inelegantly.

-Barry