[I18n-sig] pygettext.py extraction of docstrings

[Barry A. Warsaw]

A very long time ago I wrote:

    >> I have a tentative patch for Tools/i18n/pygettext.py which adds
    >> optional extraction of module, class, method, and function
    >> docstrings.

    >> One question: should docstring extraction be turned on my
    >> default?

>>>>> And "MvL" == Martin v Loewis <martin@loewis.home.cs.tu-berlin.de>
>>>>> responded:

    MvL> I'd say so, yes. People who are confronted with gettext for
    MvL> the first time will say "Wow, it even does that!". In the
    MvL> rare cases where doc strings would confuse the meat of the
    MvL> catalog, people will be able to turn that off.  Perhaps it
    MvL> may be good to indicate in the catalog that this is a doc
    MvL> string? I'm thinking of

    MvL> #, py-doc

    MvL> I don't know the exact specification of the #, comments, but
    MvL> it can look like

    MvL> #, c-format, fuzzy

    MvL> i.e. it appears to be a comma-separated list of informative
    MvL> flags. Translators could then decide to deal with doc strings
    MvL> in a different manner (e.g follow different grammatical
    MvL> conventions).

Nearest I can tell, according to

    http://www.gnu.org/manual/gettext/html_chapter/gettext_2.html#SEC9

I think the correct thing to do is to mark docstring extractions with

    #. docstring

comments.  I'm going to check in a patch to do this now, although for
backwards compatibility I think I will still leave docstring
extraction disabled by default (enabled it with -D / --docstrings).

-Barry