changeset 7552:5ecaf7845098

--- instead of --; non-naive naive.
author Karl Berry <karl@freefriends.org>
date Mon, 23 Oct 2006 22:37:50 +0000
parents 0efdbb895e51
children 0d12485b8cd4
files doc/gnulib-intro.texi
diffstat 1 files changed, 41 insertions(+), 39 deletions(-) [+]
line wrap: on
line diff
--- a/doc/gnulib-intro.texi
+++ b/doc/gnulib-intro.texi
@@ -11,11 +11,11 @@
 @node Portability and Application Code
 @section Portability and Application Code
 
-One of the goals of Gnulib is to make portable programming easy, on the
-basis of the standards relevant for Unix.  The objective behind that is to
-avoid a fragmentation of the user community into disjoint user communities
-according to the operating system, and instead allow synergies between
-users on different operating systems.
+One of the goals of Gnulib is to make portable programming easy, on
+the basis of the standards relevant for GNU (and Unix).  The objective
+behind that is to avoid a fragmentation of the user community into
+disjoint user communities according to the operating system, and
+instead allow synergies between users on different operating systems.
 
 Another goal of Gnulib is to provide application code that can be shared
 between several applications.  Some people wonder: "What? glibc doesn't
@@ -26,17 +26,19 @@
 There is no clear borderline between both areas.
 
 For example, Gnulib has a facility for generating the name of backup
-files.  While this task is an applicative one -- no standard specifies an
-API for it --, the na@"ive code has some portability problems because on
-some platforms the length of file name components is limited to 30
-characters or so.  Gnulib handles that.
+files.  While this task is entirely at the application level---no
+standard specifies an API for it---the na@"{@dotless{i}}ve code has
+some portability problems because on some platforms the length of file
+name components is limited to 30 characters or so.  Gnulib handles
+that.
 
-Similarly, Gnulib has a facility for executing a command in a subprocess.
-It is at the same time a portability enhancement (it works on Unix and
-Windows, compared to the classical @code{fork()}/@code{exec()} which is
-not portable to Windows), as well as an application aid: it takes care of
-redirecting stdin and/or stdout if desired, and emits an error message if
-the subprocess failed.
+Similarly, Gnulib has a facility for executing a command in a
+subprocess.  It is at the same time a portability enhancement (it
+works on GNU/Unix and Windows, compared to the classical
+@code{fork()}/@code{exec()} which is not portable to Windows), as well
+as an application aid: it takes care of redirecting stdin and/or
+stdout if desired, and emits an error message if the subprocess
+failed.
 
 @node Modules
 @section Modules
@@ -51,14 +53,14 @@
 the @file{m4/} subdirectory.  Build scripts reside in the
 @file{build-aux/} subdirectory.
 
-The module description contains the list of files -- @code{gnulib-tool}
-copies these files.  It contains the module's dependencies --
-@code{gnulib-tool} installs them as well.  It also contains the autoconf
-macro invocation (usually a single line or nothing at all) --
-@code{gnulib-tool} ensures this is invoked from the package's
-@file{configure.ac} file.  And also a @file{Makefile.am} snippet --
-@code{gnulib-tool} collects these into a @file{Makefile.am} for the
-tailored Gnulib part.  The module description and include file
+The module description contains the list of files---@code{gnulib-tool}
+copies these files.  It contains the module's
+dependencies---@code{gnulib-tool} installs them as well.  It also
+contains the autoconf macro invocation (usually a single line or
+nothing at all)---@code{gnulib-tool} ensures this is invoked from the
+package's @file{configure.ac} file.  And also a @file{Makefile.am}
+snippet---@code{gnulib-tool} collects these into a @file{Makefile.am}
+for the tailored Gnulib part.  The module description and include file
 specification are for documentation purposes; they are combined into
 @file{MODULES.html}.
 
@@ -68,8 +70,8 @@
 @item
 It ensures consistency of the used autoconf macros and @file{Makefile.am}
 rules with the source code.  For example, source code which uses the
-@code{getopt_long} function -- this is a common way to implement parsing
-of command line options in a way that complies with the GNU standards --
+@code{getopt_long} function---this is a common way to implement parsing
+of command line options in a way that complies with the GNU standards---
 needs the source code (@file{lib/getopt.c} and others), the autoconf macro
 which detects whether the system's libc already has this function (in
 @file{m4/getopt.m4}), and a few @file{Makefile.am} lines that create the
@@ -144,18 +146,18 @@
 @subsection Enhancements of ISO C or POSIX functions
 
 These are sometimes POSIX functions with GNU extensions also found in
-glibc -- examples: @samp{getopt}, @samp{fnmatch} --, and often new APIs
--- for example, for all functions that allocate memory in one way or the
-other, we have variants which also include the error checking against the
-out-of-memory condition.
+glibc--examples: @samp{getopt}, @samp{fnmatch}---and often new
+APIs---for example, for all functions that allocate memory in one way
+or the other, we have variants which also include the error checking
+against the out-of-memory condition.
 
 @subsection Portable general use facilities
 
-Examples are a module for copying a file -- the portability problems
-relate to the copying of the file's modification time, access rights, and
-extended attributes -- or a module for extracting the tail component of a
-file name -- here the portability to Woe32 requires a different API than
-the classical POSIX @code{basename} function.
+Examples are a module for copying a file---the portability problems
+relate to the copying of the file's modification time, access rights,
+and extended attributes---or a module for extracting the tail
+component of a file name---here the portability to Woe32 requires a
+different API than the classical POSIX @code{basename} function.
 
 @subsection Reusable application code
 
@@ -207,15 +209,15 @@
 @node Copyright
 @section Copyright
 
-Most modules are under the GPL.  Some -- mostly modules which can
-reasonably be used in libraries -- are under LGPL.  The source files
+Most modules are under the GPL.  Some, mostly modules which can
+reasonably be used in libraries, are under LGPL.  The source files
 always say "GPL", but the real license specification is in the module
 description file.
 
 If you want to use some Gnulib modules under LGPL, you can do so by
-passing the option --lgpl to @code{gnulib-tool}.  This will replace the
-GPL header with an LGPL header while copying the source files to your
-package.
+passing the option @samp{--lgpl} to @code{gnulib-tool}.  This will
+replace the GPL header with an LGPL header while copying the source
+files to your package.
 
 Keep in mind that when you submit patches to files in Gnulib, you should
 license them under a compatible license.  This means that sometimes the