__addentry(): add optional keyword arg `isdocstring' which is a flag

indicating whether the entry was extracted from a docstring or not.

write(): If any of the locations of a string appearance came from a
docstring, add a comment such as

#. docstring

before the references (after a suggestion by Martin von Loewis).

Tools/i18n/pygettext.py

@@ -137,6 +137,7 @@ import sys
 import time
 import getopt
 import tokenize
+import operator
 
 # for selftesting
 try:
@@ -260,7 +261,7 @@ class TokenEater:
             # module docstring?
             if self.__freshmodule:
                 if ttype == tokenize.STRING:
-                    self.__addentry(safe_eval(tstring), lineno)
+                    self.__addentry(safe_eval(tstring), lineno, isdocstring=1)
                     self.__freshmodule = 0
                 elif ttype not in (tokenize.COMMENT, tokenize.NL):
                     self.__freshmodule = 0
@@ -280,7 +281,7 @@ class TokenEater:
     def __suitedocstring(self, ttype, tstring, lineno):
         # ignore any intervening noise
         if ttype == tokenize.STRING:
-            self.__addentry(safe_eval(tstring), lineno)
+            self.__addentry(safe_eval(tstring), lineno, isdocstring=1)
             self.__state = self.__waiting
         elif ttype not in (tokenize.NEWLINE, tokenize.INDENT,
                            tokenize.COMMENT):
@@ -308,12 +309,12 @@ class TokenEater:
             self.__data.append(safe_eval(tstring))
         # TBD: should we warn if we seen anything else?
 
-    def __addentry(self, msg, lineno=None):
+    def __addentry(self, msg, lineno=None, isdocstring=0):
         if lineno is None:
             lineno = self.__lineno
         if not msg in self.__options.toexclude:
             entry = (self.__curfile, lineno)
-            self.__messages.setdefault(msg, {})[entry] = 1
+            self.__messages.setdefault(msg, {})[entry] = isdocstring
 
     def set_filename(self, filename):
         self.__curfile = filename
@@ -325,6 +326,11 @@ class TokenEater:
         # generated by xgettext...
         print >> fp, pot_header % {'time': timestamp, 'version': __version__}
         for k, v in self.__messages.items():
+            # If the entry was gleaned out of a docstring, then add a comment
+            # stating so.  This is to aid translators who may wish to skip
+            # translating some unimportant docstrings.
+            if reduce(operator.__add__, v.values()):
+                print >> fp, '#. docstring'
             # k is the message string, v is a dictionary-set of (filename,
             # lineno) tuples.  We want to sort the entries in v first by file
             # name and then by line number.