doc: Document placement of extracted comment blocks

* xgettext.texi: Mention that extracted comment blocks must be
adjacent to keyword lines.
Reported by Yves-Gwenael Bourhis at:
<https://savannah.gnu.org/bugs/index.php?42376>.

diff --git a/gettext-tools/doc/ChangeLog b/gettext-tools/doc/ChangeLog
index e96e8bf2a33c4d4402205080a6b02cc310724387..4bd99366c8cfaa8f62e96aff6684e5b40f1e66ac 100644 (file)
--- a/gettext-tools/doc/ChangeLog
+++ b/gettext-tools/doc/ChangeLog
@@ -1,3 +1,11 @@
+2014-12-01  Daiki Ueno  <ueno@gnu.org>
+
+       doc: Document placement of extracted comment blocks
+       * xgettext.texi: Mention that extracted comment blocks must be
+       adjacent to keyword lines.
+       Reported by Yves-Gwenael Bourhis at:
+       <https://savannah.gnu.org/bugs/index.php?42376>.
+
 2014-10-15  Daiki Ueno  <ueno@gnu.org>
 
        * gettext 0.19.3 released.

diff --git a/gettext-tools/doc/xgettext.texi b/gettext-tools/doc/xgettext.texi
index d187d6343b76de8c5dadc59d3f9b530e736cb28b..451e25fb6ec61278351d345127678c380352267c 100644 (file)
--- a/gettext-tools/doc/xgettext.texi
+++ b/gettext-tools/doc/xgettext.texi
@@ -125,6 +125,25 @@ Place comment blocks starting with @var{tag} and preceding keyword lines
 in the output file.  Without a @var{tag}, the option means to put @emph{all}
 comment blocks preceding keyword lines in the output file.
 
+Note that comment blocks supposed to be extracted must be adjacent to
+keyword lines.  For example, in the following C source code:
+
+@example
+/* This is the first comment.  */
+gettext ("foo");
+
+/* This is the second comment: not extracted  */
+gettext (
+  "bar");
+
+gettext (
+  /* This is the third comment.  */
+  "baz");
+@end example
+
+The second comment line will not be extracted, because there is one
+blank line between the comment line and the keyword.
+
 @end table
 
 @subsection Language specific options