2003-06-18 Moritz Schulte <moritz@g10code.com>
authorMoritz Schulte <mo@g10code.com>
Wed, 18 Jun 2003 14:25:08 +0000 (14:25 +0000)
committerMoritz Schulte <mo@g10code.com>
Wed, 18 Jun 2003 14:25:08 +0000 (14:25 +0000)
* gcrypt.texi: Small fixes.

doc/ChangeLog
doc/gcrypt.texi

index e8afe3b..4be5379 100644 (file)
@@ -1,3 +1,7 @@
+2003-06-18  Moritz Schulte  <moritz@g10code.com>
+
+       * gcrypt.texi: Small fixes.
+
 2003-06-16  Moritz Schulte  <moritz@g10code.com>
 
        * cipher-ref.sgml: Removed file.
index d358e79..5f906c8 100644 (file)
@@ -92,9 +92,9 @@ This is Edition @value{EDITION}, last updated @value{UPDATED}, of
 Appendices
 
 * Library Copying::             The GNU Lesser General Public License
-                                says how you can copy and share `Libgcrypt'.
+                                says how you can copy and share `@acronym{Libgcrypt}'.
 * Copying::                     The GNU General Public License says how you
-                                can copy and share some parts of `Libgcrypt'.
+                                can copy and share some parts of `@acronym{Libgcrypt}'.
 * Free Documentation License::  This manual is under the GNU Free
                                 Documentation License.
 
@@ -116,7 +116,7 @@ Preparation
 * Building sources::                    How to build sources using the library.
 * Building sources using Automake::     How to build sources with the help auf Automake.
 * Initializing the library::            How to initialize the library.
-* Multi Threading::                     How Libgcrypt can be used in a MT environment.
+* Multi Threading::                     How @acronym{Libgcrypt} can be used in a MT environment.
 
 General Functions
 * Controlling the library::     Controlling @acronym{Libgcrypt}'s behaviour.
@@ -144,7 +144,7 @@ Public Key cryptography
 * General public-key related Functions::  General functions, not implementing any cryptography.
 
 Random Numbers
-* Quality of random numbers::   @acronym{Libgcrypt} differentiates between different quality levels.
+* Quality of random numbers::   @acronym{Libgcrypt} uses different quality levels.
 * Retrieving random numbers::   How to retrieve random numbers.
 
 S-expressions
@@ -176,7 +176,7 @@ Error handling
 @c **********************************************************
 @node Introduction
 @chapter Introduction
-`Libgcrypt' is a library providing cryptographic building blocks.
+`@acronym{Libgcrypt}' is a library providing cryptographic building blocks.
 
 @menu
 * Getting Started::             How to use this manual.
@@ -187,7 +187,7 @@ Error handling
 @node Getting Started
 @section Getting Started
 
-This manual documents the `Libgcrypt' library application programming
+This manual documents the `@acronym{Libgcrypt}' library application programming
 interface (API).  All functions and data types provided by the library
 are explained.
 
@@ -221,7 +221,7 @@ subject to the terms of the GNU General Public License
 list of these parts.
 
 @item It encapsulates the low level cryptography
-`Libgcrypt' provides a high level interface to cryptographic building
+`@acronym{Libgcrypt}' provides a high level interface to cryptographic building
 blocks using an extendable and flexible API.
 
 @end table
@@ -231,11 +231,11 @@ blocks using an extendable and flexible API.
 @section Overview
 
 @noindent
-The `Libgcrypt' library is fully thread-safe; the library
+The `@acronym{Libgcrypt}' library is fully thread-safe; the library
 automagically detects whether an applications uses no threading,
 pthreads or GNU Pth.
 
-Libgcrypt depends on the library `libgpg-error' [FIXME: REF?], which
+@acronym{Libgcrypt} depends on the library `libgpg-error' [FIXME: REF?], which
 contains common error handling code for GnuPG components.
 
 @c **********************************************************
@@ -244,7 +244,7 @@ contains common error handling code for GnuPG components.
 @node Preparation
 @chapter Preparation
 
-To use `Libgcrypt', you have to perform some changes to your sources and
+To use `@acronym{Libgcrypt}', you have to perform some changes to your sources and
 the build system.  The necessary changes are small and explained in the
 following sections.  At the end of this chapter, it is described how the
 library is initialized, and how the requirements of the library are
@@ -255,7 +255,7 @@ verified.
 * Building sources::                    How to build sources using the library.
 * Building sources using Automake::     How to build sources with the help auf Automake.
 * Initializing the library::            How to initialize the library.
-* Multi Threading::                     How Libgcrypt can be used in a MT environment.
+* Multi Threading::                     How @acronym{Libgcrypt} can be used in a MT environment.
 @end menu
 
 
@@ -271,12 +271,12 @@ file, like this:
 #include <gcrypt.h>
 @end example
 
-The name space of `Libgcrypt' is @code{gcry_*} for function and type
+The name space of `@acronym{Libgcrypt}' is @code{gcry_*} for function and type
 names and @code{GCRY*} for other symbols.  In addition the same name
 prefixes with one prepended underscore are reserved for internal use
 and should never be used by an application.  Furthermore
 `libgpg-error' defines functions prefixed with `gpg_' and preprocessor
-symbols prefixed with `GPG_'.  Note that Libgcrypt uses libgpg-error,
+symbols prefixed with `GPG_'.  Note that @acronym{Libgcrypt} uses libgpg-error,
 which uses @code{gpg_err_*} as name space for function and type names
 and @code{GPG_ERR_*} for other symbols, including all the error codes.
 
@@ -290,7 +290,7 @@ directory in which the header file is located to the compilers include
 file search path (via the @option{-I} option).
 
 However, the path to the include file is determined at the time the
-source is configured.  To solve this problem, `Libgcrypt' ships with a small
+source is configured.  To solve this problem, `@acronym{Libgcrypt}' ships with a small
 helper program @command{libgcrypt-config} that knows the path to the
 include file and other configuration options.  The options that need
 to be added to the compiler invocation at compile time are output by
@@ -302,7 +302,7 @@ gcc -c foo.c `libgcrypt-config --cflags`
 @end example
 
 Adding the output of @samp{libgcrypt-config --cflags} to the compilers
-command line will ensure that the compiler can find the `Libgcrypt' header
+command line will ensure that the compiler can find the `@acronym{Libgcrypt}' header
 file.
 
 A similar problem occurs when linking the program with the library.
@@ -311,8 +311,8 @@ the path to the library files has to be added to the library search path
 (via the @option{-L} option).  For this, the option @option{--libs} to
 @command{libgcrypt-config} can be used.  For convenience, this option
 also outputs all other options that are required to link the program
-with the `Libgcrypt' libraries (in particular, the @samp{-lgcrypt}
-option).  The example shows how to link @file{foo.o} with the `Libgcrypt'
+with the `@acronym{Libgcrypt}' libraries (in particular, the @samp{-lgcrypt}
+option).  The example shows how to link @file{foo.o} with the `@acronym{Libgcrypt}'
 library to a program @command{foo}.
 
 @example
@@ -362,7 +362,7 @@ LDADD = $(LIBGCRYPT_LIBS)
 @node Initializing the library
 @section Initializing the library
 
-It is often desirable to check that the version of `Libgcrypt' used is
+It is often desirable to check that the version of `@acronym{Libgcrypt}' used is
 indeed one which fits all requirements.  Even with binary compatibility
 new features may have been introduced but due to problem with the
 dynamic linker an old version is actually used.  So you may want to
@@ -377,13 +377,13 @@ version number.
 
 In either case, the function initializes some sub-systems, and for
 this reason alone it must be invoked early in your program, before you
-make use of the other functions of Libgcrypt.
+make use of the other functions of @acronym{Libgcrypt}.
 @end deftypefun
 
 @node Multi Threading
 @section Multi Threading
 
-As mentioned earlier, the `Libgcrypt' library is fully thread-safe;
+As mentioned earlier, the `@acronym{Libgcrypt}' library is fully thread-safe;
 the library automagically detects whether an applications uses no
 threading, pthreads or GNU Pth.
 
@@ -457,7 +457,7 @@ initialize_gcrypt (void)
 @deftypefun gpg_error_t gcry_control (enum gcry_ctl_cmds @var{cmd}, ...)
 
 This function can be used to influence the general behaviour of
-Libgcrypt in several ways.  Depending on @var{cmd}, more arguments can
+@acronym{Libgcrypt} in several ways.  Depending on @var{cmd}, more arguments can
 or have to be provided.
 
 @end deftypefun
@@ -468,8 +468,8 @@ or have to be provided.
 @node Handler Functions
 @chapter Handler Functions
 
-Libgcrypt makes it possible to install so called `handler functions',
-which get called by Libgcrypt in case of certain events.
+@acronym{Libgcrypt} makes it possible to install so called `handler functions',
+which get called by @acronym{Libgcrypt} in case of certain events.
 
 @menu
 * Progress handler::            Using a progress handler function.
@@ -753,7 +753,7 @@ Make sure that all operations are allocated in secure memory.  This is
 useful, when the key material is highly confidential.
 @item GCRY_CIPHER_ENABLE_SYNC
 This flag enables the CFB sync mode, which is a special feature of
-Libgcrypt's CFB mode implementation to allow for OpenPGP's CFB variant. 
+@acronym{Libgcrypt}'s CFB mode implementation to allow for OpenPGP's CFB variant. 
 See @code{gcry_cipher_sync}.
 @item GCRY_CIPHER_CBC_CTS
 Enable cipher text stealing (CTS) for the CBC mode.  Cannot be used
@@ -1299,7 +1299,7 @@ enabled for the digest object @var{h}.
 
 
 Tracking bugs related to hashing is often a cumbersome task which
-requires to add a lot of printf statements into the code.  Libgcrypt
+requires to add a lot of printf statements into the code.  @acronym{Libgcrypt}
 provides an easy way to avoid this.  The actual data hashed can be
 written to files on request.  The following 2 macros should be used to
 implement such a debugging facility:
@@ -1342,7 +1342,7 @@ easy way for key management and to provide digital signatures.
 @node Available algorithms
 @section Available algorithms
 
-Libgcrypt supports the RSA (Rivest-Shamir-Adleman) algorithms as well
+@acronym{Libgcrypt} supports the RSA (Rivest-Shamir-Adleman) algorithms as well
 as DSA (Digital Signature Algorithm) and ElGamal.  The versatile
 interface allows to add more algorithms in the future.
 
@@ -1369,7 +1369,7 @@ The following information are stored in S-expressions:
 @end table
 
 @noindent
-To describe how Libgcrypt expect keys, we use some examples. Note that
+To describe how @acronym{Libgcrypt} expect keys, we use some examples. Note that
 words in
 @ifnottex
 uppercase
@@ -1486,7 +1486,7 @@ a more complex S-expression which also allows to specify flags for
 operation, like e.g. padding rules.
 
 @noindent
-If you don't want to let Libgcrypt handle the padding, you must pass an
+If you don't want to let @acronym{Libgcrypt} handle the padding, you must pass an
 appropriate MPI using this expression for @var{data}:
 
 @example 
@@ -1585,7 +1585,7 @@ there was no @code{flags} element in @var{data}; if at least an empty
 Another operation commonly performed using public keys are digital
 signature.  In some sense they are even more important than the
 encryption because digital signature are an important instrument for key
-management.  Libgcrypt support digital signatures using 2 functions,
+management.  @acronym{Libgcrypt} support digital signatures using 2 functions,
 similar to the encryption functions:
 
 @deftypefun gpg_error_t gcry_pk_sign (@w{gcry_sexp_t *@var{r_sig},} @w{gcry_sexp_t @var{data},} @w{gcry_sexp_t @var{skey}})
@@ -1594,7 +1594,7 @@ This function creates a digital signature for @var{data} using the
 private key @var{skey} and place it into the variable at the address of
 @var{r_sig}.  @var{data} may either be the simple old style S-expression
 with just one MPI or a modern and more versatile S-expression which
-allows to let Libgcrypt handle padding:
+allows to let @acronym{Libgcrypt} handle padding:
 
 @example 
 (data
@@ -1606,7 +1606,7 @@ allows to let Libgcrypt handle padding:
 This example requests to sign the data in @var{block} after applying
 PKCS#1 block type 1 style padding.  @var{hash-algo} is a string with the
 hash algorithm to be encoded into the signature, this may be any hash
-algorithm name as supported by Libgcrypt.  Most likely, this will be
+algorithm name as supported by @acronym{Libgcrypt}.  Most likely, this will be
 "sha1", "rmd160" or "md5".  It is obvious that the length of @var{block}
 must match the size of that message digests; the function checks that
 this and other constraints are valid.
@@ -1654,7 +1654,7 @@ used with "elg" replacing "dsa".
 
 @noindent
 The operation most commonly used is definitely the verification of a
-signature.  Libgcrypt provides this function:
+signature.  @acronym{Libgcrypt} provides this function:
 
 @deftypefun gpg_error_t gcry_pk_verify (@w{gcry_sexp_t @var{sig}}, @w{gcry_sexp_t @var{data}}, @w{gcry_sexp_t @var{pkey}})
 
@@ -1799,7 +1799,7 @@ and @var{buflen} must have the value @code{sizeof (int)}.
 @c end gcry_pk_ctl
 
 @noindent
-Libgcrypt also provides a function to generate public key pairs:
+@acronym{Libgcrypt} also provides a function to generate public key pairs:
 
 @deftypefun gpg_error_t gcry_pk_genkey (@w{gcry_sexp_t *@var{r_key}}, @w{gcry_sexp_t @var{parms}})
 
@@ -1845,7 +1845,7 @@ Reserved
 @end table
 
 @noindent
-If this parameter is not used, Libgcrypt uses for historic reasons
+If this parameter is not used, @acronym{Libgcrypt} uses for historic reasons
 65537.
 
 @end table
@@ -1897,7 +1897,7 @@ useful information.
 @chapter Random Numbers
 
 @menu
-* Quality of random numbers::   @acronym{Libgcrypt} differentiates between different quality levels.
+* Quality of random numbers::   @acronym{Libgcrypt} uses different quality levels.
 * Retrieving random numbers::   How to retrieve random numbers.
 @end menu
 
@@ -1952,7 +1952,7 @@ allocated in a ``secure'' area of the memory.
 
 S-expressions are used by the public key functions to pass complex data
 structures around.  These LISP like objects are used by some
-cryptographic protocols (cf. RFC-2692) and Libgcrypt provides functions
+cryptographic protocols (cf. RFC-2692) and @acronym{Libgcrypt} provides functions
 to parse and construct them.  For detailed information, see
 @cite{Ron Rivest, code and description of S-expressions,
 @uref{http://theory.lcs.mit.edu/~rivest/sexp.html}}.
@@ -1966,7 +1966,7 @@ to parse and construct them.  For detailed information, see
 @section Data types for S-expressions
 
 @deftp {Data type} gcry_sexp_t
-The @code{gcry_sexp_t} type describes an object with the Libgcrypt internal
+The @code{gcry_sexp_t} type describes an object with the @acronym{Libgcrypt} internal
 representation of an S-expression.
 @end deftp
 
@@ -1974,7 +1974,7 @@ representation of an S-expression.
 @section Working with S-expressions
 
 @noindent
-There are several functions to create an Libgcrypt S-expression object
+There are several functions to create an @acronym{Libgcrypt} S-expression object
 from its external representation or from a string template.  There is
 also a function to convert the internal representation back into one of
 the external formats:
@@ -2001,7 +2001,7 @@ argument @var{freefnc}, which, when not set to @code{NULL}, is expected
 to be a function to release the @var{buffer}; most likely the standard
 @code{free} function is used for this argument.  This has the effect of
 transferring the ownership of @var{buffer} to the created object in
-@var{r_sexp}.  The advantage of using this function is that Libgcrypt
+@var{r_sexp}.  The advantage of using this function is that @acronym{Libgcrypt}
 might decide to directly use the provided buffer and thus avoid extra
 copying.
 @end deftypefun
@@ -2082,7 +2082,7 @@ Returns the S-expression in advanced format.
 
 @deftypefun void gcry_sexp_dump (@w{gcry_sexp_t @var{sexp}})
 
-Dumps @var{sexp} in a format suitable for debugging to Libgcrypt's
+Dumps @var{sexp} in a format suitable for debugging to @acronym{Libgcrypt}'s
 logging stream.
 @end deftypefun
 
@@ -2174,7 +2174,7 @@ printf ("my name is %.*s\n", (int)len, name);
 
 This function is used to get and convert data from a @var{list}. This
 data is assumed to be an MPI stored in the format described by
-@var{mpifmt} and returned as a standard Libgcrypt MPI.  The caller must
+@var{mpifmt} and returned as a standard @acronym{Libgcrypt} MPI.  The caller must
 release this returned value using @code{gcry_mpi_release}.  If there is
 no data at the given index, the index represents a list or the value
 can't be converted to an MPI, @code{NULL} is returned.
@@ -2200,7 +2200,7 @@ can't be converted to an MPI, @code{NULL} is returned.
 Public key cryptography is based on mathematics with large numbers.  To
 implement the public key functions, a library for handling these large
 numbers is required.  Because of the general usefulness of such a
-library, its interface is exposed by Libgcrypt.  The implementation is
+library, its interface is exposed by @acronym{Libgcrypt}.  The implementation is
 based on an old release of GNU Multi-Precision Library (GMP) but in the
 meantime heavily modified and stripped down to what is required for
 cryptography. For a lot of CPUs, high performance assembler
@@ -2208,7 +2208,7 @@ implementations of some very low level functions are used to gain much
 better performance than with the standard C implementation.
 
 @noindent
-In the context of Libgcrypt and in most other applications, these large
+In the context of @acronym{Libgcrypt} and in most other applications, these large
 numbers are called MPIs (multi-precision-integers).
 
 @node Data types
@@ -2230,7 +2230,7 @@ numbers.  This can be done with one of these functions:
 Allocate a new MPI object, initialize it to 0 and initially allocate
 enough memory for a number of at least @var{nbits}.  This pre-allocation is
 only a small performance issue and not actually necessary because
-Libgcrypt automatically re-allocates the required memory.
+@acronym{Libgcrypt} automatically re-allocates the required memory.
 @end deftypefun
 
 @deftypefun gcry_mpi_t gcry_mpi_snew (@w{unsigned int @var{nbits}})
@@ -2283,7 +2283,7 @@ Swap the values of @var{a} and @var{b}.
 
 @noindent
 The following functions are used to convert between an external
-representation of an MPI and the internal one of Libgcrypt.
+representation of an MPI and the internal one of @acronym{Libgcrypt}.
 
 @deftypefun int gcry_mpi_scan (@w{gcry_mpi_t *@var{r_mpi}}, @w{enum gcry_mpi_format @var{format}}, @w{const char *@var{buffer}}, @w{size_t *@var{nbytes}})
 
@@ -2588,7 +2588,7 @@ Release the memory area pointed to by @var{p}.
 @node Error Handling
 @chapter Error Handling
 
-Most functions in Libgcrypt return an error if they fail.  For this
+Most functions in @acronym{Libgcrypt} return an error if they fail.  For this
 reason, the application should always catch the error condition and
 take appropriate measures, for example by releasing the resources and
 passing the error up to the caller, or by displaying a descriptive
@@ -2669,7 +2669,7 @@ Invalid operation code or control command.
 Out of core; not enough memory available to perform operation.
 
 @item GPG_ERR_INTERNAL
-Internal error.  This is most likely a bug in Libgcrypt or due to an
+Internal error.  This is most likely a bug in @acronym{Libgcrypt} or due to an
 incomplete build or installation.
 
 @item GPG_ERR_INV_OBJ
@@ -2800,12 +2800,12 @@ Invalid operation code or control command.
 Out of core; not enough memory available to perform operation.
 
 @item GCRYERR_INTERNAL
-Internal error.  This is most likely a bug in Libgcrypt or due to an
+Internal error.  This is most likely a bug in @acronym{Libgcrypt} or due to an
 incomplete build or installation.
 
 @item GCRYERR_EOF = 64
 End-of-file condition. Note, that some functions usually return
-@code{-1} to indicate this; Libgcrypt error function maps this to this
+@code{-1} to indicate this; @acronym{Libgcrypt} error function maps this to this
 value.
 
 @item GCRYERR_INV_OBJ