Typographical and wording fixes to doc/libtasn1.texi

doc/libtasn1.texi: A bunch of typographical and wording fixes
and improvements.

Signed-off-by: Simon Josefsson <simon@josefsson.org>

1 files changed, 94 insertions, 64 deletions

diff --git a/doc/libtasn1.texi b/doc/libtasn1.texi
index 13238aa..799f71f 100644
--- a/doc/libtasn1.texi
+++ b/doc/libtasn1.texi
@@ -13,7 +13,7 @@
 This manual is for GNU Libtasn1
 (version @value{VERSION}, @value{UPDATED}),
 which is a library for Abstract Syntax Notation One (ASN.1) and
-Distinguish Encoding Rules (DER) manipulation.
+Distinguished Encoding Rules (DER) manipulation.
 
 Copyright @copyright{} 2001-2012 Free Software Foundation, Inc.
 
@@ -68,21 +68,23 @@ Indices
 @node Introduction
 @chapter Introduction
 
-This document describes the Libtasn1 library developed for ASN.1
-(Abstract Syntax Notation One) structures management and DER
-(Distinguished Encoding Rules) encoding functions.
+This document describes the Libtasn1 library that provides
+Abstract Syntax Notation One (ASN.1, as specified by the X.680 ITU-T
+recommendation) parsing and structures management,
+and Distinguished Encoding Rules (DER, as per X.690) encoding and
+decoding functions.
 
 The main features of this library are:
 
 @itemize @bullet
 
-@item On line ASN1 structure management that doesn't require any
+@item On-line ASN.1 structure management that doesn't require any
 C code file generation.
 
-@item Off line ASN1 structure management with C code file generation
+@item Off-line ASN.1 structure management with C code file generation
 containing an array.
 
-@item DER (Distinguish Encoding Rules) encoding.
+@item Distinguished Encoding Rules (DER) encoding support.
 
 @item No limits for INTEGER and ENUMERATED values.
 
@@ -92,14 +94,14 @@ of the GNU Lesser General Public License version 2.1 or later.  The
 command line tools, self-tests and build infrastructure are licensed
 under the GNU General Public License version 3.0 or later.
 
-@item It's thread-safe.
+@item Thread-safety.
 @cindex threads
 No global variables are used and multiple library handles and session
 handles may be used in parallel.
 
-@item It's portable.
+@item Portability.
 @cindex Porting
-It should work on all Unix like operating systems, including Windows.
+The code should work on all Unix like operating systems, and Windows.
 The library itself should be portable to any C89 system, not even
 POSIX is required.
 @end itemize
@@ -119,9 +121,15 @@ POSIX is required.
 
 @cindex ASN.1 schema
 
-The parser is case sensitive. The comments begin with "-- " and end at
-the end of lines.  An example is in "pkix.asn" file.  ASN.1
-definitions must have this syntax:
+The parser is case sensitive.  The comments begin with @code{--} and
+end either with another @code{--}, or at the end of the respective
+line, whichever comes first.  The C-style @code{/*}, @code{*/}
+comments are not supported.
+
+For an example of the syntax, check the @file{pkix.asn} file
+distributed with the library.
+
+ASN.1 definitions must follow the syntax below:
 
 @verbatim
       definitions_name {<object definition>}
@@ -135,15 +143,15 @@ definitions must have this syntax:
       END
 @end verbatim
 
-The token "::=" must be separate from others elements, so this is a
-wrong declaration:
+The @code{::=} token must be separate from other elements, so the
+following declaration is invalid:
 
 @example
-      ;; INCORRECT
-      Version ::=INTEGER
+   -- INCORRECT
+   Version ::=INTEGER
 @end example
 
-the correct form is:
+The correct form is:
 
 @example
    Version ::= INTEGER
@@ -155,30 +163,31 @@ Here is the list of types that the parser can manage:
 
 @itemize @bullet
 
-@item INTEGER
-@item ENUMERATED
-@item BOOLEAN
-@item OBJECT IDENTIFIER
-@item NULL
-@item BIT STRING
-@item OCTET STRING
-@item UTCTime
-@item GeneralizedTime
-@item GeneralString
-@item SEQUENCE
-@item SEQUENCE OF
-@item SET
-@item SET OF
-@item CHOICE
-@item ANY
-@item ANY DEFINED BY
+@item @code{INTEGER};
+@item @code{ENUMERATED};
+@item @code{BOOLEAN};
+@item @code{OBJECT IDENTIFIER};
+@item @code{NULL};
+@item @code{BIT STRING};
+@item @code{OCTET STRING};
+@item @code{UTCTime};
+@item @code{GeneralizedTime};
+@item @code{GeneralString};
+@item @code{SEQUENCE};
+@item @code{SEQUENCE OF};
+@item @code{SET};
+@item @code{SET OF};
+@item @code{CHOICE};
+@item @code{ANY};
+@item @code{ANY DEFINED BY}.
 
 @end itemize
 
-This version doesn't manage REAL type. It doesn't allow the "EXPORT"
-and "IMPORT" sections too.
+This version doesn't handle the @code{REAL} type.  It doesn't support
+the @code{AUTOMATIC TAGS} option, and the @code{EXPORT} and
+@code{IMPORT} sections, either.
 
-The SIZE constraints are allowed, but no check is done on them.
+The @code{SIZE} constraints are allowed, but no check is done on them.
 
 @node Naming
 @section Naming
@@ -205,22 +214,26 @@ Consider this definition:
       END
 @end verbatim
 
-To identify the type 'Group' you have to use the null terminated
-string "Example.Group".  These strings are used in functions that are
-described below.
+The notation to access the @samp{Group} type of the @samp{Example}
+definition above is @samp{Example.Group} (as a NUL-terminated string.)
+Such strings are used in the functions described below.
 
 Others examples:
 
-Field 'id' in 'Group' type : "Example.Group.id".
+@itemize @bullet
+
+@item field @samp{id} of the @samp{Group} type: @samp{Example.Group.id};
+
+@item field @samp{value1} of the @samp{value} field of the @samp{Group}
+type: @samp{Example.Group.value.value1}.
 
-Field 'value1' in field 'value' in type 'Group':
-"Example.Group.value.value1".
+@end itemize
 
-Elements of structured types that don't have a name, receive the name
-"?1","?2", and so on.
+Elements of structured types unnamed by the respective definition
+receive the names @code{?1}, @code{?2}, and so on.
 
-The name "?LAST" indicates the last element of a @code{SET_OF} or
-@code{SEQUENCE_OF}.
+The @code{?LAST} name indicates the last element of a @code{SET OF} or
+@code{SEQUENCE OF}.
 
 @node Library Notes
 @section Library Notes
@@ -234,20 +247,20 @@ The header file of this library is @file{libtasn1.h}.
 The main type used in it is @code{asn1_node}, and it's used to store
 the ASN.1 definitions and structures (instances).
 
-The constant @code{NULL} can be used for the variable
+The @code{NULL} constant can be used for the variable
 initialization.  For example:
 
 @example
- asn1_node definitions=NULL;
+ asn1_node definitions = NULL;
 @end example
 
-Some functions require a parameter named errorDescription of char*
-type.  The array must be already allocated and must have at least
-@code{ASN1_MAX_ERROR_DESCRIPTION_SIZE} bytes (E.g, as in @code{char
-Description[ASN1_MAX_ERROR_DESCRIPTION_SIZE];}).
+Some functions require an @code{errorDescription} argument of type
+@code{char *}, pointing to a pre-allocated buffer of at least
+@code{ASN1_MAX_ERROR_DESCRIPTION_SIZE} bytes size (e.g., as in
+@samp{char description[ASN1_MAX_ERROR_DESCRIPTION_SIZE];}).
 
-@code{ASN1_MAX_NAME_SIZE} indicates the maximum number of characters of a
-name inside a file with ASN1 definitions.
+@code{ASN1_MAX_NAME_SIZE} is the maximum number of characters allowed
+for an ASN.1 identifier.
 
 @node Future developments
 @section Future developments
@@ -258,7 +271,7 @@ name inside a file with ASN1 definitions.
 @item Add functions for a C code file generation containing equivalent
 data structures (not a single array like now).
 
-@item Type REAL.
+@item The @code{REAL} type.
 
 @end itemize
 
@@ -275,7 +288,8 @@ data structures (not a single array like now).
 @section Invoking asn1Parser
 @cindex asn1Parser program
 
-@file{asn1Parser} reads one file with ASN1 definitions and generates a
+@command{asn1Parser} reads a single file with ASN.1 definitions and
+generates a
 file with an array to use with libtasn1 functions.
 
 @verbatim
@@ -293,7 +307,7 @@ Options:
 @section Invoking asn1Coding
 @cindex asn1Coding program
 
-@file{asn1Coding} generates a DER encoding from a file with ASN1
+@command{asn1Coding} generates a DER encoding from a file with ASN.1
 definitions and another one with assignments.
 
 The file with assignments must have this syntax:
@@ -307,6 +321,11 @@ nameString  value
 ...
 @end verbatim
 
+To specify the field of a @code{CHOICE} to be used, specify its name
+as a value to the @code{CHOICE} element itself.  Use @code{''} to
+denote the root element itself.
+(as in the example below.)
+
 The output file is a binary file with the DER encoding.
 
 @verbatim
@@ -320,7 +339,7 @@ Options:
  -o file : output file.
 @end verbatim
 
-For example, consider a ASN.1 definitions file as follows:
+For example, consider an ASN.1 definitions file as follows:
 
 @verbatim
 PKIX1 { }
@@ -346,18 +365,28 @@ r 42
 s 47
 @end verbatim
 
-Running the command below will generate a file @file{assign.out}
+Running the command below will generate a @file{assign.out} file,
 containing the DER encoding of @code{PKIX1.Dss-Sig-Value}.
 
 @verbatim
 $ asn1Coding pkix.asn assign.asn1
 @end verbatim
 
+If the root element is of the @code{CHOICE} type, the assignment file
+may be like (using the types defined in @file{pkix.asn}):
+@verbatim
+elt PKIX1Implicit88.GeneralName
+
+''      dNSName
+dNSName example.org
+@end verbatim
+
 @node Invoking asn1Decoding
 @section Invoking asn1Decoding
 @cindex asn1Decoding program
 
-@file{asn1Decoding} generates an ASN1 structure from a file with ASN1
+@command{asn1Decoding} generates an ASN.1 structure from a file with
+ASN.1
 definitions and a binary file with a DER encoding.
 
 @verbatim
@@ -371,8 +400,9 @@ Options:
  -o file : output file.
 @end verbatim
 
-For example, after generating the file @file{assign.out} from the
-example section of the @code{asn1Coding} command, the following
+For example, after generating the @file{assign.out} file from the
+example section of the @command{asn1Coding} command above, the
+following
 invocation will decode the DER data.
 
 @verbatim