[PATCH] better docs in gettext.texi and xgettext.texi

[Andrea G. Monaco]

Here is my proposal for some improvements to the docs.
I added a usage example for xgettext and made other little
stylistic changes.


Cheers,
Andrea

---
 gettext-tools/doc/gettext.texi  | 16 ++++++++++++++--
 gettext-tools/doc/xgettext.texi | 10 +++++-----
 2 files changed, 19 insertions(+), 7 deletions(-)

diff --git a/gettext-tools/doc/gettext.texi b/gettext-tools/doc/gettext.texi
index 90eba7997..c0f4f5e59 100644
--- a/gettext-tools/doc/gettext.texi
+++ b/gettext-tools/doc/gettext.texi
@@ -3008,9 +3008,21 @@ This section explains how to use @code{xgettext} for 
this purpose.
 @code{xgettext} creates a file named @file{@var{domainname}.po}.  You
 should then rename it to @file{@var{domainname}.pot}.  (Why doesn't
 @code{xgettext} create it under the name @file{@var{domainname}.pot}
-right away?  The answer is: for historical reasons.  When @code{xgettext}
+right away?  For historical reasons.  When @code{xgettext}
 was specified, the distinction between a PO file and PO file template
-was fuzzy, and the suffix @samp{.pot} wasn't in use at that time.)
+was fuzzy, and the suffix @samp{.pot} wasn't in use.)
+
+Here's an example invocation of @code{xgettext}:
+@example
+xgettext --keyword=_ --from-code=utf-8 *.c *.h
+@endexample
+This creates a @file{messages.po} file with all translatable strings
+found in @samp{.c} and @samp{.h} files in the current directory.
+The @code{--keyword} option specifies @code{_} as an additional keyword for
+@code{gettext} calls; you must use this argument if you declared @code{_} as
+a macro for @code{gettext}. Also the @code{--from-code} option specifies
+encoding of the input files; you need it if your translatable strings
+contain non-ASCII characters.
 
 @c FIXME: Rewrite.
 
diff --git a/gettext-tools/doc/xgettext.texi b/gettext-tools/doc/xgettext.texi
index b2c6374fa..c23aee2d8 100644
--- a/gettext-tools/doc/xgettext.texi
+++ b/gettext-tools/doc/xgettext.texi
@@ -5,17 +5,17 @@
 @pindex xgettext
 @cindex @code{xgettext} program, usage
 @example
-xgettext [@var{option}] [@var{inputfile}] @dots{}
+xgettext [@var{option}] @dots{} [@var{inputfile}] @dots{}
 @end example
 
 The @code{xgettext} program extracts translatable strings from given
-input files.
+input file(s) and generates an output PO file.
 
-@subsection Input file location
+@subsection Input files location
 
 @table @samp
 @item @var{inputfile} @dots{}
-Input files.
+Input file(s).
 
 @item -f @var{file}
 @itemx --files-from=@var{file}
@@ -465,7 +465,7 @@ See @ref{The --style option} for details.
 
 @item --force-po
 @opindex --force-po@r{, @code{xgettext} option}
-Always write an output file even if no message is defined.
+Always write an output file even if no translatable string is found.
 
 @item -i
 @itemx --indent
-- 
2.20.1