[commit-womb] qualitycode qualitycode.texi

[Karl Berry]

CVSROOT:        /sources/womb
Module name:    qualitycode
Changes by:     Karl Berry <karl>       10/12/02 17:38:54

Modified files:
        .              : qualitycode.texi 

Log message:
        recommit

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/qualitycode/qualitycode.texi?cvsroot=womb&r1=1.6&r2=1.7

Patches:
Index: qualitycode.texi
===================================================================
RCS file: /sources/womb/qualitycode/qualitycode.texi,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -b -r1.6 -r1.7
--- qualitycode.texi    23 Nov 2010 08:48:29 -0000      1.6
+++ qualitycode.texi    2 Dec 2010 17:38:54 -0000       1.7
@@ -1,9 +1,12 @@
 \input texinfo   @c -*-texinfo-*-
address@hidden $Id: qualitycode.texi,v 1.6 2010/11/23 08:48:29 civodul Exp $
address@hidden $Id: qualitycode.texi,v 1.7 2010/12/02 17:38:54 karl Exp $
 @comment %**start of header
 @setfilename qualitycode.info
address@hidden UPDATED 18 November 2010
address@hidden UPDATED 26 November 2010
 @settitle GNU Quality Code
address@hidden op
address@hidden fn cp
address@hidden op cp
 @syncodeindex pg cp
 @syncodeindex vr cp
 @comment %**end of header
@@ -43,7 +46,8 @@
 @node Top
 @top GNU Quality Code
 
-This document gives GNU quality code recommendations (@value{UPDATED}).
+This document gives recommendations for writing quality code in GNU
+(@value{UPDATED}).
 @end ifnottex
 
 @menu
@@ -57,17 +61,19 @@
 @node Memory management
 @chapter Memory management
 
-C, C++, and similar languages let programmers in charge of managing
-memory and ensuring that application code does not access invalid memory
-regions.  This section describes common tools and techniques to test the
-memory management discipline of such programs and help find out and
-debug problems.
-
-Of course, many languages provide automatic memory management thanks to
-a @dfn{garbage collector}, and guarantee that application code can only
-access memory regions that contain valid objects.  Among them is GNU
-Guile, the extension language of the GNU System (@pxref{Introduction,,,
-guile, GNU Guile Reference Manual}).
address@hidden Memory management
+
+In C, C++, and similar languages, programmers are in charge of
+managing memory and ensuring that application code does not access
+invalid memory regions.  This section describes common tools and
+techniques to help find out and debug problems in memory management
+discipline.
+
+Other languages provide automatic memory management thanks to
address@hidden collection}, and can guarantee that application code can
+only access memory regions that contain valid objects.  Among these is
+GNU Guile, the extension language of the GNU System
+(@pxref{Introduction,,, guile, GNU Guile Reference Manual}).
 
 @menu
 * Valgrind::                    Run-time memory management analysis.
@@ -83,10 +89,10 @@
 
 @url{http://valgrind.org, Valgrind} is a dynamic analysis tool,
 meaning it is used during runtime, without any re-compilation.  It is
-typically only useful to check compiled languages that support
-low-level memory management, such as C and C++.  Valgrind can find
-many memory management and threading bugs.  The simplest way is to run
-Valgrind manually on your application, for example:
+typically only useful with compiled languages that support low-level
+memory management, such as C and C++.  Valgrind can find many memory
+management and threading bugs.  The simplest way is to run Valgrind
+manually on your application, for example:
 
 @example
 $ valgrind -- ./foo --bar
@@ -98,8 +104,10 @@
 way.  With the @code{--leak-check=full} option, Valgrind and
 @code{memcheck} also report memory leaks.
 
-Valgrind's @url{http://valgrind.org@/docs/manual@/dh-manual.html,
-dynamic heap analysis tool} (DHAT) can be used to find out
address@hidden DHAT
address@hidden dynamic heap analysis tool
+The @url{http://valgrind.org@/docs/manual@/dh-manual.html, dynamic
+heap analysis tool} (DHAT) in Valgrind can be used to find out
 process-lifetime leaks (i.e., steady heap allocations that get freed
 only at program exit) as well as unused memory regions.
 
@@ -116,8 +124,9 @@
 @code{valgrind} which provides a @file{valgrind-tests.m4} file that
 will search for the valgrind tool and provides the @code{VALGRIND}
 variable to contain commands used to launch it.  By default it runs
-Valgrind in quiet mode to avoid output when there is no problem.  The
-variable can be used in your tests/Makefile.am like this:
+Valgrind in quiet mode, so output is generated only when there is a
+problem.  The variable can be used in your @file{tests/Makefile.am}
+like this:
 
 @vindex TESTS_ENVIRONMENT
 @example
@@ -131,16 +140,21 @@
 @node Compiler support
 @section Compiler support
 
address@hidden compiler support and options
+
 @c FIXME: Incomplete.
-The GNU Compiler Collection provides support for detecting common memory
-errors at run-time:
+The GNU Compiler Collection provides support for detecting common
+memory errors at run-time:
 
 @enumerate
 @item
address@hidden Mudflap
address@hidden -fmudflap
 Mudflap, which instruments memory accesses (@pxref{Optimize Options,
 @code{-fmudflap},, gcc, GCC Reference Manual}).
 
 @item
address@hidden -fstackprotector
 @code{-fstack-protector} (@pxref{Optimize Options,
 @code{-fstack-protector},, gcc, GCC Reference Manual}).
 @end enumerate
@@ -149,26 +163,34 @@
 @node C library support
 @section C library support
 
address@hidden glibc support
address@hidden libc support
address@hidden malloc
+
 The GNU C Library provides debugging facilities for heap memory
-management issues.  They can be used for any applications that use
address@hidden and related functions from the C library without having to
-recompile or relink them, and they incur little overhead at run time.
+management issues.  They can be used with any application using
address@hidden and related functions from the C library without having
+to recompile or relink them, and they incur little overhead at run
+time.
 
 @c FIXME: Incomplete.
 @itemize
 @item
address@hidden, to detect heap consistency errors, such as buffer
-overruns (@pxref{Heap Consistency Checking, @code{MALLOC_CHECK_},, libc,
-The GNU C Library Reference Manual}).
address@hidden MALLOC_CHECK_
address@hidden, to detect heap consistency errors, such as
+buffer overruns (@pxref{Heap Consistency Checking,
address@hidden,, libc, The GNU C Library Reference Manual}).
 
 @item
address@hidden, which can be used to force initialization of the
-heap to a given value, thereby helping find out accesses to
address@hidden MALLOC_PERTURB_
address@hidden, which can be used to force initialization of
+the heap to a given value, thereby helping find out accesses to
 uninitialized memory regions.
 
 @item
address@hidden memusage.sh
 The (undocumented) @code{memusage.sh} script allows heap usage to be
-profiled, thus helping find out memory leaks.
+profiled, thus helping discover memory leaks.
 @end itemize
 
 
@@ -192,20 +214,25 @@
 * Practical details::           Support for test suites.
 @end menu
 
+
 @node Test coverage
 @section Test coverage
 
address@hidden test coverage
+
 TODO: Write about feedback from test coverage report tools such as
 @ref{Debugging Options, GCC's @code{--coverage},, gcc, GCC Reference
 Manual} and @url{http://ltp.sourceforge.net@/coverage@/lcov.php, LCOV};
 same for @ref{Code Coverage, Guile,, guile, GNU Guile Reference Manual}.
 
+
 @node Writing new tests
 @section Writing new tests
 
 TODO: Write something about test-driven development, and the addition of
 a test for each bug fix.
 
+
 @node Practical details
 @section Practical details