[PATCH] manual: fix up grammar

[Mike Frysinger <vapier at gentoo dot org>]

A while ago I was on a long trip and decided to read the glibc manual.
Crazy, but the message translation section could use a lot of grammar
fix ups, so I did that.

Signed-off-by: Mike Frysinger <vapier@gentoo.org>

2012-10-27  Mike Frysinger  <vapier@gentoo.org>

	* message.texi: Fix grammar and long sentences.
	* search.texi: Likewise.
---
 manual/message.texi | 115 ++++++++++++++++++++++++----------------------------
 manual/search.texi  |   6 +--
 2 files changed, 57 insertions(+), 64 deletions(-)

diff --git a/manual/message.texi b/manual/message.texi
index bb28717..bee5166 100644
--- a/manual/message.texi
+++ b/manual/message.texi
@@ -251,22 +251,20 @@ previously opened using the @code{catopen} function.  The
 The next two parameters, @var{set} and @var{message}, reflect the
 internal organization of the message catalog files.  This will be
 explained in detail below.  For now it is interesting to know that a
-catalog can consists of several set and the messages in each thread are
+catalog can consists of several sets and the messages in each thread are
 individually numbered using numbers.  Neither the set number nor the
 message number must be consecutive.  They can be arbitrarily chosen.
 But each message (unless equal to another one) must have its own unique
 pair of set and message number.
 
 Since it is not guaranteed that the message catalog for the language
-selected by the user exists the last parameter @var{string} helps to
-handle this case gracefully.  If no matching string can be found
+selected by the user exists, the last parameter @var{string} helps to
+handle this case gracefully.  If no matching string can be found, then
 @var{string} is returned.  This means for the programmer that
 
 @itemize @bullet
 @item
-the @var{string} parameters should contain reasonable text (this also
-helps to understand the program seems otherwise there would be no hint
-on the string which is expected to be returned.
+the @var{string} parameter should contain reasonable text.
 @item
 all @var{string} arguments should be written in the same language.
 @end itemize
@@ -294,9 +292,9 @@ set to @code{EBADF}.
 @node The message catalog files
 @subsection  Format of the message catalog files
 
-The only reasonable way the translate all the messages of a function and
-store the result in a message catalog file which can be read by the
-@code{catopen} function is to write all the message text to the
+The only reasonable way to translate all the messages of a function and
+store the result in a message catalog file which can then be read by the
+@code{catopen} function is to send the entire message text to the
 translator and let her/him translate them all.  I.e., we must have a
 file with entries which associate the set/message tuple with a specific
 translation.  This file format is specified in the X/Open standard and
@@ -308,7 +306,7 @@ Lines containing only whitespace characters or empty lines are ignored.
 
 @item
 Lines which contain as the first non-whitespace character a @code{$}
-followed by a whitespace character are comment and are also ignored.
+followed by a whitespace character are comments and are also ignored.
 
 @item
 If a line contains as the first non-whitespace characters the sequence
@@ -348,20 +346,20 @@ previously was defined.  It is an error if the name is unknown.
 @end itemize
 
 In both cases all messages in the specified set will be removed.  They
-will not appear in the output.  But if this set is later again selected
-with a @code{$set} command again messages could be added and these
-messages will appear in the output.
+will not appear in the output.  But if this set is later selected
+with a @code{$set} command, messages could be added and will appear in
+the output.
 
 @item
-If a line contains after leading whitespaces the sequence
+If a line contains, after leading whitespace, the sequence
 @code{$quote}, the quoting character used for this input file is
 changed to the first non-whitespace character following the
 @code{$quote}.  If no non-whitespace character is present before the
-line ends quoting is disable.
+line ends, quoting is disable.
 
-By default no quoting character is used.  In this mode strings are
+By default no quoting character is used.  In this mode, strings are
 terminated with the first unescaped line break.  If there is a
-@code{$quote} sequence present newline need not be escaped.  Instead a
+@code{$quote} sequence present, newlines need not be escaped.  Instead a
 string is terminated with the first unescaped appearance of the quote
 character.
 
@@ -430,7 +428,7 @@ problem and the numbering happens automatically.
 
 While this file format is pretty easy it is not the best possible for
 use in a running program.  The @code{catopen} function would have to
-parser the file and handle syntactic errors gracefully.  This is not so
+parse the file and handle syntactic errors gracefully.  This is not so
 easy and the whole process is pretty slow.  Therefore the @code{catgets}
 functions expect the data in another more compact and ready-to-use file
 format.  There is a special program @code{gencat} which is explained in
@@ -527,10 +525,10 @@ generated the old output files are not in the generated header file.
 @node Common Usage
 @subsection How to use the @code{catgets} interface
 
-The @code{catgets} functions can be used in two different ways.  By
-following slavishly the X/Open specs and not relying on the extension
-and by using the GNU extensions.  We will take a look at the former
-method first to understand the benefits of extensions.
+The @code{catgets} functions can be used in two different ways: by
+following slavishly the X/Open specs and not relying on the extension,
+or by using the GNU extensions.  We will take a look at the former
+method first to understand the benefits of the GNU extensions.
 
 @subsubsection Not using symbolic names
 
@@ -612,11 +610,10 @@ As can be seen the various symbols given in the source file are mangled
 to generate unique identifiers and these identifiers get numbers
 assigned.  Reading the source file and knowing about the rules will
 allow to predict the content of the header file (it is deterministic)
-but this is not necessary.  The @code{gencat} program can take care for
+but this is not necessary.  The @code{gencat} program can take care of
 everything.  All the programmer has to do is to put the generated header
 file in the dependency list of the source files of her/his project and
-to add a rules to regenerate the header of any of the input files
-change.
+to add a rule to regenerate the header when the input files change.
 
 One word about the symbol mangling.  Every symbol consists of two parts:
 the name of the message set plus the name of the message or the special
@@ -641,11 +638,11 @@ code.  (The text of the string is normally not the same; this is only
 for this example.)
 
 
-@subsubsection How does to this allow to develop
+@subsubsection Example usage
 
-To illustrate the usual way to work with the symbolic version numbers
-here is a little example.  Assume we want to write the very complex and
-famous greeting program.  We start by writing the code as usual:
+To illustrate the usual way to work with symbolic names, here is a little
+example.  Assume we want to write the very complex and famous greeting
+program.  We start by writing the code as usual:
 
 @smallexample
 #include <stdio.h>
@@ -657,8 +654,8 @@ main (void)
 @}
 @end smallexample
 
-Now we want to internationalize the message and therefore replace the
-message with whatever the user wants.
+Now we want to internationalize the message and replace the message with
+one the user can understand.
 
 @smallexample
 #include <nl_types.h>
@@ -675,16 +672,15 @@ main (void)
 @}
 @end smallexample
 
-We see how the catalog object is opened and the returned descriptor used
+We see how the catalog object is opened and the returned descriptor is used
 in the other function calls.  It is not really necessary to check for
-failure of any of the functions since even in these situations the
-functions will behave reasonable.  They simply will be return a
-translation.
+failure of any of the functions since, even in these situations, the
+functions will behave reasonably.  They will simply return a translation.
 
 What remains unspecified here are the constants @code{SetMainSet} and
 @code{SetMainHello}.  These are the symbolic names describing the
 message.  To get the actual definitions which match the information in
-the catalog file we have to create the message catalog source file and
+the catalog file, we have to create the message catalog source file and
 process it using the @code{gencat} program.
 
 @smallexample
@@ -699,7 +695,6 @@ Now we can start building the program (assume the message catalog source
 file is named @file{hello.msg} and the program source file @file{hello.c}):
 
 @smallexample
-@cartouche
 % gencat -H msgnrs.h -o hello.cat hello.msg
 % cat msgnrs.h
 #define MainSet 0x1     /* hello.msg:4 */
@@ -711,10 +706,9 @@ de
 % ./hello
 Hallo, Welt!
 %
-@end cartouche
 @end smallexample
 
-The call of the @code{gencat} program creates the missing header file
+Running the @code{gencat} program creates the missing header file
 @file{msgnrs.h} as well as the message catalog binary.  The former is
 used in the compilation of @file{hello.c} while the later is placed in a
 directory in which the @code{catopen} function will try to locate it.
@@ -732,7 +726,7 @@ Since this approach fits better in the development process of free
 software it is also used throughout the GNU project and the GNU
 @file{gettext} package provides support for this outside @theglibc{}.
 
-The code of the @file{libintl} from GNU @file{gettext} is the same as
+The code of the @file{libintl} library from GNU @file{gettext} is the same as
 the code in @theglibc{}.  So the documentation in the GNU
 @file{gettext} manual is also valid for the functionality here.  The
 following text will describe the library functions in detail.  But the
@@ -757,10 +751,9 @@ functions are not available.
 @node Message catalogs with gettext
 @subsection The @code{gettext} family of functions
 
-The paradigms underlying the @code{gettext} approach to message
-translations is different from that of the @code{catgets} functions the
-basic functionally is equivalent.  There are functions of the following
-categories:
+While the paradigms underlying the @code{gettext} approach to message
+translations are different from that of the @code{catgets} functions, the
+basic functionally is equivalent.
 
 @menu
 * Translation with gettext::       What has to be done to translate a message.
@@ -897,7 +890,7 @@ no relation to the environments variables of this name.
 The @code{dcgettext} function is only implemented for compatibility with
 other systems which have @code{gettext} functions.  There is not really
 any situation where it is necessary (or useful) to use a different value
-but @code{LC_MESSAGES} in for the @var{category} parameter.  We are
+other than @code{LC_MESSAGES} for the @var{category} parameter.  We are
 dealing with messages here and any other choice can only be irritating.
 
 As for @code{gettext} the return value type is @code{char *} which is an
@@ -1095,8 +1088,8 @@ things we can differ between (and even inside language families);
 
 @itemize @bullet
 @item
-The form how plural forms are build differs.  This is a problem with
-language which have many irregularities.  German, for instance, is a
+The way plural forms are built differs.  This is a problem with
+languages which have many irregularities.  German, for instance, is a
 drastic case.  Though English and German are part of the same language
 family (Germanic), the almost regular forming of plural noun forms
 (appending an `s') is hardly found in German.
@@ -1115,14 +1108,14 @@ solve the problem in their code.  This would be localization since it is
 only usable for certain, hardcoded language environments.  Instead the
 extended @code{gettext} interface should be used.
 
-These extra functions are taking instead of the one key string two
-strings and an numerical argument.  The idea behind this is that using
+These extra functions take, instead of the one key string, two
+strings and a numerical argument.  The idea behind this is that using
 the numerical argument and the first string as a key, the implementation
 can select using rules specified by the translator the right plural
 form.  The two string arguments then will be used to provide a return
 value in case no message catalog is found (similar to the normal
 @code{gettext} behavior).  In this case the rules for Germanic language
-is used and it is assumed that the first string argument is the singular
+are used and it is assumed that the first string argument is the singular
 form, the second the plural form.
 
 This has the consequence that programs without language catalogs can
@@ -1202,7 +1195,7 @@ Plural-Forms: nplurals=2; plural=n == 1 ? 0 : 1;
 The @code{nplurals} value must be a decimal number which specifies how
 many different plural forms exist for this language.  The string
 following @code{plural} is an expression which is using the C language
-syntax.  Exceptions are that no negative number are allowed, numbers
+syntax.  Exceptions are that no negative numbers are allowed, numbers
 must be decimal, and the only variable allowed is @code{n}.  This
 expression will be evaluated whenever one of the functions
 @code{ngettext}, @code{dngettext}, or @code{dcngettext} is called.  The
@@ -1453,8 +1446,8 @@ One place where the @code{gettext} functions, if used normally, have big
 problems is within programs with graphical user interfaces (GUIs).  The
 problem is that many of the strings which have to be translated are very
 short.  They have to appear in pull-down menus which restricts the
-length.  But strings which are not containing entire sentences or at
-least large fragments of a sentence may appear in more than one
+length.  But strings which do not contain entire sentences, or at
+least large fragments of a sentence, may appear in more than one
 situation in the program but might have different translations.  This is
 especially true for the one-word strings which are frequently used in
 GUI programs.
@@ -1567,17 +1560,17 @@ examples above used @code{|} which is a quite good choice because it
 resembles a notation frequently used in this context and it also is a
 character not often used in message strings.
 
-But what if the character is used in message strings.  Or if the chose
+But what if the character is used in message strings.  Or if the chosen
 character is not available in the character set on the machine one
 compiles (e.g., @code{|} is not required to exist for @w{ISO C}; this is
 why the @file{iso646.h} file exists in @w{ISO C} programming environments).
 @end itemize
 
 There is only one more comment to make left.  The wrapper function above
-require that the translations strings are not extended themselves.
+requires that the translations strings are not extended themselves.
 This is only logical.  There is no need to disambiguate the strings
 (since they are never used as keys for a search) and one also saves
-quite some memory and disk space by doing this.
+quite a bit of memory and disk space by doing this.
 
 
 @node Using gettextized software
@@ -1658,7 +1651,7 @@ exactly one specification of a locale the @code{LANGUAGE} variable's
 value can consist of a colon separated list of locale names.  The
 attentive reader will realize that this is the way we manage to
 implement one of our additional demands above: we want to be able to
-specify an ordered list of language.
+specify an ordered list of languages.
 
 Back to the constructed filename we have only one component missing.
 The @var{domain_name} part is the name which was either registered using
@@ -1669,7 +1662,7 @@ closely related to the program/package name.  E.g., for @theglibc{}
 the domain name is @code{libc}.
 
 @noindent
-A limit piece of example code should show how the programmer is supposed
+A limited piece of example code should show how the programmer is supposed
 to work:
 
 @smallexample
@@ -1739,7 +1732,7 @@ following list:
 The @code{language} field will never be dropped for obvious reasons.
 
 The only new thing is the @code{normalized codeset} entry.  This is
-another goodie which is introduced to help reducing the chaos which
+another goodie which is introduced to help reduce the chaos which
 derives from the inability of the people to standardize the names of
 character sets.  Instead of @w{ISO-8859-1} one can often see @w{8859-1},
 @w{88591}, @w{iso8859-1}, or @w{iso_8859-1}.  The @code{normalized
@@ -1752,11 +1745,11 @@ Remove all characters beside numbers and letters.
 @item
 Fold letters to lowercase.
 @item
-If the same only contains digits prepend the string @code{"iso"}.
+If the name only contains digits prepend the string @code{"iso"}.
 @end enumerate
 
 @noindent
-So all of the above name will be normalized to @code{iso88591}.  This
+So all of the above names will be normalized to @code{iso88591}.  This
 allows the program user much more freely choosing the locale name.
 
 Even this extended functionality still does not help to solve the
diff --git a/manual/search.texi b/manual/search.texi
index 498832b..be92311 100644
--- a/manual/search.texi
+++ b/manual/search.texi
@@ -66,7 +66,7 @@ int comparison_fn_t (const void *, const void *);
 
 Generally searching for a specific element in an array means that
 potentially all elements must be checked.  @Theglibc{} contains
-functions to perform linear search.  The prototypes for the following
+functions to perform linear searches.  The prototypes for the following
 two functions can be found in @file{search.h}.
 
 @comment search.h
@@ -277,9 +277,9 @@ arbitrarily many hashing tables.
 It is possible to use more than one hashing table in the program run if
 the former table is first destroyed by a call to @code{hdestroy}.
 
-The function returns a non-zero value if successful.  If it return zero
+The function returns a non-zero value if successful.  If it returns zero,
 something went wrong.  This could either mean there is already a hashing
-table in use or the program runs out of memory.
+table in use or the program ran out of memory.
 @end deftypefun
 
 @comment search.h
-- 
1.7.12