Editorial changes

8 files changed, 643 insertions, 471 deletions

diff --git a/lib/public_key/doc/src/cert_records.xml b/lib/public_key/doc/src/cert_records.xml
index 857a39bf40..4d4533fe21 100644
--- a/lib/public_key/doc/src/cert_records.xml
+++ b/lib/public_key/doc/src/cert_records.xml
@@ -23,7 +23,7 @@
   The Initial Developer of the Original Code is Ericsson AB.
     </legalnotice>
 
-    <title>Certificate records</title>
+    <title>Certificate Records</title>
     <prepared>Ingela Anderton Andin</prepared>
     <responsible></responsible>
     <docno></docno>
@@ -34,66 +34,81 @@
     <file>cert_records.xml</file>
   </header>
 
-  <p>This chapter briefly describes erlang records derived from ASN1
-  specifications used to handle <c> X509 certificates</c> and <c>CertificationRequest</c>.
- The intent is to describe the data types
-and not to specify the semantics of each component. For information on the
-semantics, please see <url
+  <p>This section briefly describes Erlang records derived from ASN.1
+  specifications used to handle <c>X509 certificates</c> and <c>CertificationRequest</c>.
+  The scope is to describe the data types of each component,
+  not the semantics. For information on the semantics, refer to <url
   href="http://www.ietf.org/rfc/rfc5280.txt">RFC 5280</url> and
   <url href="http://www.ietf.org/rfc/rfc5967.txt">PKCS-10</url>.
   </p>
 
   <p>Use the following include directive to get access to the
-    records and constant macros (OIDs) described in the following sections.</p>
+    records and constant macros (OIDs) described in the following sections:</p>
   
   <code> -include_lib("public_key/include/public_key.hrl"). </code>
 
-  <p>The used ASN1 specifications are available <c>asn1</c> subdirectory
-    of the application <c>public_key</c>.
-  </p>
+  <p>The used ASN.1 specifications are available in the <c>asn1</c> subdirectory
+    of the <c>public_key</c> application.</p>
 
   <section>
     <title>Common Data Types</title>   
 
-    <p>Common non standard erlang
-    data types used to described the record fields in the
-    below sections are defined in <seealso
-     marker="public_key">public key reference manual </seealso> or
-    follows here.</p>
-
-    <p><c>time() = uct_time() | general_time()</c></p>
-    
-    <p><c>uct_time() = {utcTime, "YYMMDDHHMMSSZ"} </c></p>
-    
-    <p><c>general_time() = {generalTime, "YYYYMMDDHHMMSSZ"} </c></p>
-    
-    <p><c>
-      general_name() = {rfc822Name, string()} | {dNSName, string()}
-      | {x400Address, string()} | {directoryName,
-      {rdnSequence, [#AttributeTypeAndValue'{}]}} | 
-      | {eidPartyName, special_string()}
-      | {eidPartyName, special_string(), special_string()}
-      | {uniformResourceIdentifier, string()} | {ipAddress, string()} |
-      {registeredId, oid()} | {otherName, term()}
-    </c></p>
+    <p>Common non-standard Erlang
+    data types used to describe the record fields in the
+    following sections are defined in the <c>public_key</c> <seealso
+    marker="public_key">Reference Manual</seealso>, or
+    follows here:</p>
     
-    <p><c>
-      special_string() =
-      {teletexString, string()} | {printableString, string()} |
-      {universalString, string()} | {utf8String, binary()} |
-      {bmpString, string()}     
-    </c></p>
-    
-    <p><c>
-      dist_reason() = unused | keyCompromise | cACompromise |
-      affiliationChanged | superseded | cessationOfOperation |
-      certificateHold | privilegeWithdrawn |
-      aACompromise        
-    </c></p>
+    <taglist>
+      <tag><c>time()</c></tag>
+      <item><p>= <c>uct_time() | general_time()</c></p></item>
+
+      <tag><c>uct_time()</c></tag>
+      <item><p>= <c>{utcTime, "YYMMDDHHMMSSZ"}</c></p></item>
+
+      <tag><c>general_time()</c></tag>
+      <item><p>= <c>{generalTime, "YYYYMMDDHHMMSSZ"}</c></p></item>
+ 
+      <tag><c>general_name()</c></tag>
+      <item>= <p><c>{rfc822Name, string()}</c></p>
+      <p><c>| {dNSName, string()}</c></p>
+      <p><c>| {x400Address, string()}</c></p>
+      <p><c>| {directoryName, {rdnSequence, [#AttributeTypeAndValue'{}]}}</c></p>
+      <p><c>| {eidPartyName, special_string()}</c></p>
+      <p><c>| {eidPartyName, special_string(), special_string()}</c></p>
+      <p><c>| {uniformResourceIdentifier, string()}</c></p>
+      <p><c>| {ipAddress, string()}</c></p>
+      <p><c>| {registeredId, oid()}</c></p>
+      <p><c>| {otherName, term()}</c></p>
+      </item>
+
+      <tag><c>special_string()</c></tag>
+      <item>= <p><c>{teletexString, string()}</c></p>
+      <p><c>| {printableString, string()}</c></p>
+      <p><c>| {universalString, string()}</c></p>
+      <p><c>| {utf8String, binary()}</c></p>
+      <p><c>| {bmpString, string()}</c></p>
+      </item>
+
+      <tag><c>dist_reason()</c></tag>
+      <item>= <p><c>unused</c></p>
+      <p><c>| keyCompromise</c></p>
+      <p><c>| cACompromise</c></p>
+      <p><c>| affiliationChanged</c></p>
+      <p><c>| superseded</c></p>
+      <p><c>| cessationOfOperation</c></p>
+      <p><c>| certificateHold</c></p>
+      <p><c>| privilegeWithdrawn</c></p>
+      <p><c>| aACompromise</c></p>
+      </item>
+    </taglist>
+
   </section>
 
  <section>
-    <title> PKIX Certificates</title>   
+    <title>PKIX Certificates</title>   
+    <p>Erlang representation of PKIX certificates derived from ASN.1 
+    specifications and RFC 5280 are as follows:</p>
 <code>
 #'Certificate'{
 		tbsCertificate,        % #'TBSCertificate'{}
@@ -117,8 +132,7 @@ semantics, please see <url
 #'AlgorithmIdentifier'{
 	  algorithm,  % oid() 
 	  parameters  % der_encoded()
-	 }.
-</code>
+	 }.</code>
 
 <code>
 #'OTPCertificate'{
@@ -143,20 +157,20 @@ semantics, please see <url
 #'SignatureAlgorithm'{
 	  algorithm,  % id_signature_algorithm()
 	  parameters  % asn1_novalue | #'Dss-Parms'{}
-	 }.
-</code>
+	 }.</code>
 
-<p><c> id_signature_algorithm() = ?oid_name_as_erlang_atom</c> for available
-oid names see table below. Ex: ?'id-dsa-with-sha1'</p>
+<p>Here, <c>id_signature_algorithm()</c> = ?OID name, for available OID names, for example 
+<c>?id-dsa-with-sha1</c>. That is, by prepending "?" to the OID name, represented as an Erlang atom.</p>
+<p>The available OID names are as follows:</p>
 <table>
   <row>
-    <cell align="left" valign="middle">OID name</cell>
+    <cell align="left" valign="middle"><em>OID Name</em></cell>
   </row>
   <row>
     <cell align="left" valign="middle">id-dsa-with-sha1</cell>
       </row>
       <row>
-	<cell align="left" valign="middle">id-dsaWithSHA1 (ISO alt oid to above)</cell>
+	<cell align="left" valign="middle">id-dsaWithSHA1 (ISO or OID to above)</cell>
       </row>
        <row>
 	<cell align="left" valign="middle">md2WithRSAEncryption</cell>
@@ -168,7 +182,7 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'</p>
 	<cell align="left" valign="middle">sha1WithRSAEncryption</cell>
       </row>
       <row>
-	<cell align="left" valign="middle">sha-1WithRSAEncryption (ISO alt oid to above)</cell>
+	<cell align="left" valign="middle">sha-1WithRSAEncryption (ISO or OID to above)</cell>
       </row>
       <row>
 	<cell align="left" valign="middle">sha224WithRSAEncryption</cell>
@@ -182,21 +196,24 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'</p>
         <row>
 	  <cell align="left" valign="middle">ecdsa-with-SHA1</cell>
      </row>
-      <tcaption>Signature algorithm oids </tcaption>
+      <tcaption>Signature Algorithm OIDs </tcaption>
 </table>
     
+<p>The data type <c>'AttributeTypeAndValue'</c>, is represented as
+ the following erlang record:</p>
+
 <code>
 #'AttributeTypeAndValue'{
 	  type,   % id_attributes()
 	  value   % term() 
-	 }.
-</code>
+	 }.</code>
 
-<p><c>id_attributes() </c></p>
+<p>The attribute OID name atoms and their corresponding value types
+are as follows:</p>
 <table>
   <row>
-    <cell align="left" valign="middle">OID name</cell>
-    <cell align="left" valign="middle">Value type</cell>
+    <cell align="left" valign="middle"><em>OID Name</em></cell>
+    <cell align="left" valign="middle"><em>Value Type</em></cell>
   </row>
   <row>
     <cell align="left" valign="middle">id-at-name</cell>
@@ -254,9 +271,12 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'</p>
     <cell align="left" valign="middle">id-at-pseudonym</cell>
     <cell align="left" valign="middle">special_string()</cell>
   </row>
-  <tcaption>Attribute oids </tcaption>
+  <tcaption>Attribute OIDs</tcaption>
 </table>
     
+<p>The data types <c>'Validity'</c>, <c>'SubjectPublicKeyInfo'</c>, and 
+<c>'SubjectPublicKeyInfoAlgorithm'</c> are represented as the following Erlang records:</p>
+
 <code>
 #'Validity'{ 
 	  notBefore, % time()
@@ -271,13 +291,12 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'</p>
 #'SubjectPublicKeyInfoAlgorithm'{
 	  algorithm,  % id_public_key_algorithm()
 	  parameters  % public_key_params()
-	 }.
-</code>
+	 }.</code>
 
-<p><c> id_public_key_algorithm() </c></p>
+<p>The public-key algorithm OID name atoms are as follows:</p>
 <table>
   <row>
-    <cell align="left" valign="middle">OID name</cell>
+    <cell align="left" valign="middle"><em>OID Name</em></cell>
   </row>
   <row>
     <cell align="left" valign="middle">rsaEncryption</cell>
@@ -294,7 +313,7 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'</p>
       <row>
 	<cell align="left" valign="middle">id-ecPublicKey</cell>
       </row>
-      <tcaption>Public key algorithm oids </tcaption>
+      <tcaption>Public-Key Algorithm OIDs</tcaption>
 </table>
     
 <code>
@@ -302,8 +321,7 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'</p>
 	  extnID,    % id_extensions() | oid() 
 	  critical,  % boolean()
 	  extnValue  % der_encoded()
-	 }.
-</code>
+	 }.</code>
 
 <p><c>id_extensions()</c>  
   <seealso marker="#StdCertExt">Standard Certificate Extensions</seealso>, 
@@ -316,12 +334,15 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'</p>
   
 <section>
   <marker id="StdCertExt"></marker>
-  <title>Standard certificate extensions</title>
-      
+  <title>Standard Certificate Extensions</title>
+    
+  <p>The standard certificate extensions OID name atoms and their 
+  corresponding value types are as follows:</p>
+
   <table>
       <row>
-	<cell align="left" valign="middle">OID name</cell>
-	<cell align="left" valign="middle">Value type</cell>
+	<cell align="left" valign="middle"><em>OID Name</em></cell>
+	<cell align="left" valign="middle"><em>Value Type</em></cell>
       </row>
       <row>
 	<cell align="left" valign="middle">id-ce-authorityKeyIdentifier</cell>
@@ -333,7 +354,7 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'</p>
       </row>
       <row>
 	<cell align="left" valign="middle">id-ce-keyUsage</cell>
-	<cell align="left" valign="middle"> [key_usage()]</cell>
+	<cell align="left" valign="middle">[key_usage()]</cell>
       </row>
       <row>
 	<cell align="left" valign="middle">id-ce-privateKeyUsagePeriod</cell>
@@ -400,17 +421,26 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'</p>
       <tcaption>Standard Certificate Extensions</tcaption>
     </table>
 
-    <p><c>
-      key_usage() =  digitalSignature | nonRepudiation | keyEncipherment|
-      dataEncipherment | keyAgreement | keyCertSign | cRLSign | encipherOnly |
-      decipherOnly 
-    </c></p>
+    <p>Here:</p>
+    <taglist>
+      <tag><c>key_usage()</c></tag>
+      <item>= <p><c>digitalSignature</c></p>
+      <p><c>| nonRepudiation</c></p>
+      <p><c>| keyEncipherment</c></p>
+      <p><c>| dataEncipherment</c></p>
+      <p><c>| keyAgreement</c></p>
+      <p><c>| keyCertSign</c></p>
+      <p><c>| cRLSign</c></p>
+      <p><c>| encipherOnly</c></p>
+      <p><c>| decipherOnly </c></p>
+      </item>
+    </taglist>
    
-    <p><c> id_key_purpose()</c></p>
+    <p>And for <c>id_key_purpose()</c>:</p>
     
 <table>
   <row>
-    <cell align="left" valign="middle">OID name</cell>
+    <cell align="left" valign="middle"><em>OID Name</em></cell>
   </row>
   <row>
     <cell align="left" valign="middle">id-kp-serverAuth</cell>
@@ -430,7 +460,7 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'</p>
        <row>
 	<cell align="left" valign="middle">id-kp-OCSPSigning</cell>
       </row>
-      <tcaption>Key purpose oids </tcaption>
+      <tcaption>Key Purpose OIDs</tcaption>
 </table>
     
     <code>
@@ -501,8 +531,7 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'</p>
 	  [#AttributeTypeAndValue{}]}
 	  reasons,           % [dist_reason()]
 	  cRLIssuer          % [general_name()]
-	 }).
-</code>
+	 }).</code>
 
 </section>
 
@@ -510,10 +539,13 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'</p>
    <marker id="PrivIntExt"></marker>
    <title>Private Internet Extensions</title>   
 
+   <p>The private internet extensions OID name atoms and their corresponding value 
+   types are as follows:</p>
+
    <table>
         <row>
-          <cell align="left" valign="middle">OID name</cell>
-          <cell align="left" valign="middle">Value type</cell>
+          <cell align="left" valign="middle"><em>OID Name</em></cell>
+          <cell align="left" valign="middle"><em>Value Type</em></cell>
         </row>
         <row>
           <cell align="left" valign="middle">id-pe-authorityInfoAccess</cell>
@@ -530,13 +562,15 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'</p>
 #'AccessDescription'{
            accessMethod,    % oid()
 	   accessLocation   % general_name()
-	 }).
-</code>
+	 }).</code>
 
  </section>
  
 <section>
-    <title> CRL and CRL Extensions Profile</title>   
+    <title>CRL and CRL Extensions Profile</title>
+
+    <p>Erlang representation of CRL and CRL extensions profile 
+    derived from ASN.1 specifications and RFC 5280 are as follows:</p>
 
  <code>
 #'CertificateList'{
@@ -559,17 +593,19 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'</p>
          userCertificate,      % integer()
  	 revocationDate,       % timer()
 	 crlEntryExtensions    % [#'Extension'{}]
-	 }).
- </code>
+	 }).</code>
  
  <section>
    <marker id="CRLCertExt"></marker>
-   <title>CRL Extensions </title>
+   <title>CRL Extensions</title>
+
+   <p>The CRL extensions OID name atoms and their corresponding value types are as follows:</p>
+   
    
         <table>
         <row>
-          <cell align="left" valign="middle">OID name</cell>
-          <cell align="left" valign="middle">Value type</cell>
+          <cell align="left" valign="middle"><em>OID Name</em></cell>
+          <cell align="left" valign="middle"><em>Value Type</em></cell>
         </row>
         <row>
           <cell align="left" valign="middle">id-ce-authorityKeyIdentifier</cell>
@@ -599,6 +635,9 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'</p>
         <tcaption>CRL Extensions</tcaption>
       </table>
       
+      <p>Here, the data type <c>'IssuingDistributionPoint'</c> is represented as 
+      the following Erlang record:</p>
+
       <code>
 #'IssuingDistributionPoint'{
           distributionPoint,         % {fullName, [general_name()]} | {nameRelativeToCRLIssuer,
@@ -608,18 +647,19 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'</p>
 	  onlySomeReasons,           % [dist_reason()]
 	  indirectCRL,               % boolean()
 	  onlyContainsAttributeCerts % boolean()
-	  }).
-      </code> 
+	  }).</code> 
  </section>
  
  <section>
    <marker id="CRLEntryExt"></marker>
-   <title> CRL Entry Extensions </title>
+   <title>CRL Entry Extensions</title>
+
+   <p>The CRL entry extensions OID name atoms and their corresponding value types are as follows:</p>
 
        <table>
         <row>
-          <cell align="left" valign="middle">OID name</cell>
-          <cell align="left" valign="middle">Value type</cell>
+          <cell align="left" valign="middle"><em>OID Name</em></cell>
+          <cell align="left" valign="middle"><em>Value Type</em></cell>
         </row>
         <row>
           <cell align="left" valign="middle">id-ce-cRLReason</cell>
@@ -639,17 +679,31 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'</p>
            </row>
 	   <tcaption>CRL Entry Extensions</tcaption>
        </table>
-       <p><c>
-	 crl_reason() = unspecified | keyCompromise | cACompromise |
-	 affiliationChanged | superseded | cessationOfOperation |
-	 certificateHold | removeFromCRL | privilegeWithdrawn |
-	 aACompromise        
-       </c></p>
+
+
+       <p>Here:</p>
+       <taglist>
+      <tag><c>crl_reason()</c></tag>
+      <item>= <p><c>unspecified</c>c></p>
+      <p><c>| keyCompromise</c></p>
+      <p><c>| cACompromise</c></p>
+      <p><c>| affiliationChanged</c></p>
+      <p><c>| superseded</c></p>
+      <p><c>| cessationOfOperation</c></p>
+      <p><c>| certificateHold</c></p>
+      <p><c>| removeFromCRL</c></p>
+      <p><c>| privilegeWithdrawn</c></p>
+      <p><c>| aACompromise</c></p>
+      </item>
+       </taglist>
+
  </section>
 
  <section>
    <marker id="PKCS10"></marker>
    <title>PKCS#10 Certification Request</title>
+   <p>Erlang representation of a PKCS#10 certification request 
+   derived from ASN.1 specifications and RFC 5280 are as follows:</p>
    <code>
 #'CertificationRequest'{
           certificationRequestInfo #'CertificationRequestInfo'{},
@@ -682,8 +736,7 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'</p>
 #'AttributePKCS-10'{
     type = oid(),
     values = [der_encoded()]
-}  
-   </code> 
+}  </code> 
  </section>
 
 </section>
diff --git a/lib/public_key/doc/src/introduction.xml b/lib/public_key/doc/src/introduction.xml
index bf11a092d8..17f4e5155a 100644
--- a/lib/public_key/doc/src/introduction.xml
+++ b/lib/public_key/doc/src/introduction.xml
@@ -36,27 +36,28 @@
 
   <section>
     <title>Purpose</title>
-    <p> public_key deals with public key related file formats, digital
-    signatures and <url href="http://www.ietf.org/rfc/rfc5280.txt">
+    <p>The <c>public_key</c> application deals with public-key related file 
+    formats, digital signatures, and <url href="http://www.ietf.org/rfc/rfc5280.txt">
     X-509 certificates</url>. It is a library application that
-    provides encode/decode, sign/verify, encrypt/decrypt and similar
-    functionality, it does not read or write files it expects or returns
+    provides encode/decode, sign/verify, encrypt/decrypt, and similar
+    functionality. It does not read or write files, it expects or returns
     file contents or partial file contents as binaries.
     </p>
   </section>
 
   <section>
     <title>Prerequisites</title>
-    <p>It is assumed that the reader has a basic understanding
-    of the concepts of using public keys and digital certificates.</p>
+    <p>It is assumed that the reader is familiar with the Erlang programming 
+    language and has a basic understanding of the concepts of using public-keys 
+    and digital certificates.</p>
   </section>
 
   <section>
-    <title>Performance tips</title>
-    <p>The public_key decode and encode functions will try to use the NIFs
-    which are in the ASN1 compilers runtime modules if they can be found.
-    So for the best  performance you want to have the ASN1 application in the
-    path of your system. </p>
+    <title>Performance Tips</title>
+    <p>The <c>public_key</c> decode- and encode-functions try to use the NIFs
+    in the <c>ASN.1</c> compilers runtime modules, if they can be found.
+    Thus, to have the <c>ASN.1</c> application in the
+    path of your system gives the best performance.</p>
   </section>
 
 </chapter>
diff --git a/lib/public_key/doc/src/part.xml b/lib/public_key/doc/src/part.xml
index 73146c8e2a..d3cc9303bd 100644
--- a/lib/public_key/doc/src/part.xml
+++ b/lib/public_key/doc/src/part.xml
@@ -31,15 +31,14 @@
     <file>part.xml</file>
   </header>
   <description>
-    <p> This application provides an API to public key infrastructure
+    <p>This application provides an API to public-key infrastructure
     from <url href="http://www.ietf.org/rfc/rfc5280.txt">RFC
-    5280</url> (X.509 certificates) and public key formats defined by
+    5280</url> (X.509 certificates) and public-key formats defined by
     the <url href="http://en.wikipedia.org/wiki/PKCS">
-    PKCS-standard</url></p>
+    PKCS</url> standard.</p>
   </description>
   <xi:include href="introduction.xml"/>
-  <xi:include href="public_key_records.xml"/>
-  <xi:include href="cert_records.xml"/>
+  <xi:include href="records.xml"/>
   <xi:include href="using_public_key.xml"/>
 </part>
 
diff --git a/lib/public_key/doc/src/public_key.xml b/lib/public_key/doc/src/public_key.xml
index b86d0fe0ab..ddaa8c2530 100644
--- a/lib/public_key/doc/src/public_key.xml
+++ b/lib/public_key/doc/src/public_key.xml
@@ -31,11 +31,11 @@
     <rev></rev>
   </header>
   <module>public_key</module>
-  <modulesummary> API module for public key infrastructure.</modulesummary>
+  <modulesummary>API module for public-key infrastructure.</modulesummary>
   <description>
-    <p>This module provides functions to handle public key infrastructure. It can
-    encode/decode different file formats (PEM, openssh), sign and verify digital signatures and validate
-    certificate paths and certificate revocation lists.
+    <p>This module provides functions to handle public-key infrastructure. It can
+    encode/decode different file formats (PEM, OpenSSH), sign and verify digital signatures, 
+    and validate certificate paths and certificate revocation lists.
     </p>
   </description>
 
@@ -43,94 +43,152 @@
     <title>public_key</title>
 
     <list type="bulleted">
-      <item>public_key requires the crypto and asn1 applications, the latter since R16 (hopefully the runtime dependency on asn1 will
-      be removed again in the future).</item>
+      <item><c>public_key</c> requires the <c>crypto</c> and <c>ASN.1</c> applications, 
+      the latter as OTP R16 (hopefully the runtime dependency on <c>ASN.1</c> will
+     be removed again in the future).</item>
 
       <item>Supports <url href="http://www.ietf.org/rfc/rfc5280.txt">RFC 5280 </url> -
-      Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile </item>
-      <item>Supports <url href="http://www.ietf.org/rfc/rfc3447.txt"> PKCS-1 </url> - RSA Cryptography Standard </item>
-      <item>Supports <url href="http://csrc.nist.gov/publications/fips/fips186-3/fips_186-3.pdf"> DSS</url>- Digital Signature Standard (DSA - Digital Signature Algorithm)</item>
-      <item>Supports <url href="http://www.emc.com/emc-plus/rsa-labs/standards-initiatives/pkcs-3-diffie-hellman-key-agreement-standar.htm"> PKCS-3 </url> - Diffie-Hellman Key Agreement Standard </item>
-      <item>Supports <url href="http://www.ietf.org/rfc/rfc2898.txt"> PKCS-5</url> - Password-Based Cryptography Standard </item>
-      <item>Supports <url href="http://www.ietf.org/rfc/rfc5208.txt"> PKCS-8</url> - Private-Key Information Syntax Standard</item>
-      <item>Supports <url href="http://www.ietf.org/rfc/rfc5967.txt"> PKCS-10</url> - Certification Request Syntax Standard</item>
+      Internet X.509 Public-Key Infrastructure Certificate and Certificate Revocation List 
+      (CRL) Profile </item>
+      <item>Supports <url href="http://www.ietf.org/rfc/rfc3447.txt"> PKCS-1 </url> - 
+      RSA Cryptography Standard </item>
+      <item>Supports <url href="http://csrc.nist.gov/publications/fips/fips186-3/fips_186-3.pdf"> DSS</url> - 
+      Digital Signature Standard (DSA - Digital Signature Algorithm)</item>
+      <item>Supports 
+      <url href="http://www.emc.com/emc-plus/rsa-labs/standards-initiatives/pkcs-3-diffie-hellman-key-agreement-standar.htm"> PKCS-3 </url> - 
+      Diffie-Hellman Key Agreement Standard </item>
+      <item>Supports <url href="http://www.ietf.org/rfc/rfc2898.txt"> PKCS-5</url> - 
+      Password-Based Cryptography Standard </item>
+      <item>Supports <url href="http://www.ietf.org/rfc/rfc5208.txt"> PKCS-8</url> - 
+      Private-Key Information Syntax Standard</item>
+      <item>Supports <url href="http://www.ietf.org/rfc/rfc5967.txt"> PKCS-10</url> - 
+      Certification Request Syntax Standard</item>
     </list>
   </section>
 
   <section>
-    <title>COMMON DATA TYPES </title> 
+    <title>DATA TYPES</title> 
     
-    <note><p>All records used in this manual 
+    <note><p>All records used in this Reference Manual 
     <!--     except #policy_tree_node{}  -->
     are generated from ASN.1 specifications
     and are documented in the User's Guide. See <seealso 
-    marker="public_key_records">Public key records</seealso> and <seealso 
-    marker="cert_records">X.509 Certificate records</seealso>. 
+    marker="public_key_records">Public-key Records</seealso> and <seealso 
+    marker="cert_records">X.509 Certificate Records</seealso>. 
     </p></note>
     
     <p>Use the following include directive to get access to the 
-    records and constant macros described here and in the User's Guide.</p>
+    records and constant macros described here and in the User's Guide:</p>
     
     <code> -include_lib("public_key/include/public_key.hrl").</code>
 
-    <p><em>Data Types </em></p>
-    
-    <p><code>oid() - Object Identifier, a tuple of integers as generated by the ASN1 compiler.</code></p>
-
-    <p><code>boolean() = true | false</code></p>
-
-    <p><code>string() = [bytes()]</code></p>
-
-    <p><code>der_encoded() = binary()</code></p>
-   
-    <p><code>pki_asn1_type() = 'Certificate' | 'RSAPrivateKey'| 'RSAPublicKey' |
-    'DSAPrivateKey' | 'DSAPublicKey' | 'DHParameter' |
-    'SubjectPublicKeyInfo' | 'PrivateKeyInfo' |
-    'CertificationRequest' | 'ECPrivateKey' | 'EcpkParameters'</code></p>
-    
-    <p><code>pem_entry () = {pki_asn1_type(), binary(), %% DER or encrypted DER
-    not_encrypted | cipher_info()}</code></p>
-
-    <p><code>cipher_info()  =  {"RC2-CBC | "DES-CBC" | "DES-EDE3-CBC",
-    crypto:rand_bytes(8) | {#'PBEParameter{}, digest_type()} |#'PBES2-params'{}}</code></p>
-	  
-    <p><code>public_key()  = rsa_public_key() | dsa_public_key() | ec_public_key()</code></p>
-    <p><code>private_key() = rsa_private_key() | dsa_private_key() | ec_private_key()</code></p>
-    <p><code>rsa_public_key()  = #'RSAPublicKey'{}</code></p>
-
-    <p><code>rsa_private_key() = #'RSAPrivateKey'{}</code></p>
-
-    <p><code>dsa_public_key()  = {integer(),  #'Dss-Parms'{}}</code></p>
-
-    <p><code>dsa_private_key() = #'DSAPrivateKey'{}</code></p>
-
-    <p><code>ec_public_key()   = {#'ECPoint'{}, #'EcpkParameters'{} |
-    {namedCurve, oid()}}</code></p>
-    
-    <p><code>ec_private_key()  = #'ECPrivateKey'{}</code></p>
-
-    <p><code>public_crypt_options() = [{rsa_pad, rsa_padding()}].</code></p>
-
-    <p><code>rsa_padding() =  'rsa_pkcs1_padding' | 'rsa_pkcs1_oaep_padding' |
-    'rsa_no_padding'</code></p>
+    <p>The following data types are used in the functions for <c>public_key</c>:</p>
 
-    <p><code>digest_type() - Union of below digest types</code></p>
+    <taglist>
+      <tag><c>oid()</c></tag>
+      <item><p>Object identifier, a tuple of integers as generated by the <c>ASN.1</c> compiler.</p></item>
+
+      <tag><c>boolean()</c></tag>
+      <item><p>= <c>true | false</c></p></item>
+
+      <tag><c>string()</c></tag>
+      <item><p>= <c>[bytes()]</c></p></item>
+
+      <tag><c>der_encoded()</c></tag>
+      <item><p>= <c>binary()</c></p></item>
+
+      <tag><c>pki_asn1_type()</c></tag>
+      <item>= <p><c>'Certificate'</c></p>
+      <p><c>| 'RSAPrivateKey'</c></p>
+      <p><c>| 'RSAPublicKey'</c></p>
+      <p><c>| 'DSAPrivateKey'</c></p>
+      <p><c>| 'DSAPublicKey'</c></p>
+      <p><c>| 'DHParameter'</c></p>
+      <p><c>| 'SubjectPublicKeyInfo'</c></p>
+      <p><c>| 'PrivateKeyInfo'</c></p>
+      <p><c>| 'CertificationRequest'</c></p>
+      <p><c>| 'ECPrivateKey'</c></p>
+      <p><c>| 'EcpkParameters'</c></p></item>
+
+      <tag><c>pem_entry ()</c></tag>
+      <item><p>= <c>{pki_asn1_type(), binary(), %% DER or encrypted DER not_encrypted</c></p>
+      <p><c>| cipher_info()}</c></p></item>
+
+      <tag><c>cipher_info()</c></tag>
+      <item><p>= <c>{"RC2-CBC" | "DES-CBC" | "DES-EDE3-CBC", crypto:rand_bytes(8)</c></p>
+      <p><c>| {#'PBEParameter{}, digest_type()} | #'PBES2-params'{}}</c></p>
+      </item>
+      
+      <tag><c>public_key()</c></tag>
+      <item><p>= <c>rsa_public_key() | dsa_public_key() | ec_public_key()</c></p></item>
+
+      <tag><c>private_key()</c></tag>
+      <item><p>= <c>rsa_private_key() | dsa_private_key() | ec_private_key()</c></p></item>
+
+      <tag><c>rsa_public_key()</c></tag>
+      <item><p>= <c>#'RSAPublicKey'{}</c></p></item>
+
+      <tag><c>rsa_private_key()</c></tag>
+      <item><p>= <c>#'RSAPrivateKey'{}</c></p></item>
+
+      <tag><c>dsa_public_key()</c></tag>
+      <item><p>= <c>{integer(),  #'Dss-Parms'{}}</c></p></item>
+
+      <tag><c>dsa_private_key()</c></tag>
+      <item><p>= <c>#'DSAPrivateKey'{}</c></p></item>
+
+      <tag><c>ec_public_key()</c></tag>
+      <item><p>= <c>{#'ECPoint'{}, #'EcpkParameters'{} | {namedCurve, oid()}}</c></p></item>
+
+      <tag><c>ec_private_key()</c></tag>
+      <item><p>= <c>#'ECPrivateKey'{}</c></p></item>
+
+      <tag><c>public_crypt_options()</c></tag>
+      <item><p>= <c>[{rsa_pad, rsa_padding()}]</c></p></item>
+
+      <tag><c>rsa_padding()</c></tag>
+      <item><p>= <c>'rsa_pkcs1_padding'</c></p>
+      <p><c>| 'rsa_pkcs1_oaep_padding'</c></p>
+      <p><c>| 'rsa_no_padding'</c></p>
+      </item>
+
+      <tag><c>digest_type()</c></tag>
+      <item><p>Union of <c>rsa_digest_type()</c>, <c>dss_digest_type()</c>, 
+      and <c>ecdsa_digest_type()</c>.</p></item>
+
+      <tag><c>rsa_digest_type()</c></tag>
+      <item><p>= <c>'md5' | 'sha' | 'sha224' | 'sha256' | 'sha384' | 'sha512'</c></p></item>
+
+      <tag><c>dss_digest_type()</c></tag>
+      <item><p>= <c>'sha'</c></p></item>
+
+      <tag><c>ecdsa_digest_type()</c></tag>
+      <item><p>= <c>'sha'| 'sha224' | 'sha256' | 'sha384' | 'sha512'</c></p></item>
+
+      <tag><c>crl_reason()</c></tag>
+      <item><p>= <c>unspecified</c></p>
+      <p><c>| keyCompromise</c></p>
+      <p><c>| cACompromise</c></p>
+      <p><c>| affiliationChanged</c></p>
+      <p><c>| superseded</c></p>
+      <p><c>| cessationOfOperation</c></p>
+      <p><c>| certificateHold</c></p>
+      <p><c>| privilegeWithdrawn</c></p>
+      <p><c>| aACompromise</c></p>
+      </item>
+
+      <tag><c>issuer_name()</c></tag>
+      <item><p>= <c>{rdnSequence,[#'AttributeTypeAndValue'{}]}</c></p>  
+      </item>
+
+      <tag><c>ssh_file()</c></tag>
+      <item><p>= <c>openssh_public_key</c></p>
+      <p><c>| rfc4716_public_key</c></p>
+      <p><c>| known_hosts</c></p>
+      <p><c>| auth_keys</c></p>
+      </item>
+    </taglist>
     
-    <p><code>rsa_digest_type()   = 'md5' | 'sha' | 'sha224' | 'sha256' | 'sha384' |
-    'sha512'</code></p>
-
-    <p><code>dss_digest_type()   = 'sha'</code></p>
-
-    <p><code>ecdsa_digest_type() = 'sha'| 'sha224' | 'sha256' | 'sha384' | 'sha512'</code></p>
-
-    <p><code>crl_reason()  = unspecified | keyCompromise | cACompromise |
-    affiliationChanged | superseded | cessationOfOperation |
-    certificateHold | privilegeWithdrawn | aACompromise</code></p>
-
-    <p><code>issuer_name() = {rdnSequence,[#'AttributeTypeAndValue'{}]} </code> </p>
-
-    <p><code>ssh_file()  = openssh_public_key | rfc4716_public_key | known_hosts |
-    auth_keys</code></p>
     
 <!--     <p><code>policy_tree() = [Root, Children]</code></p> -->
     
@@ -138,12 +196,12 @@
 
 <!--     <p><code>Children = [] | policy_tree()</code></p> -->
 	
-<!--     <p> The policy_tree_node record has the following fields:</p> -->
+<!--     <p>The <c>policy_tree_node</c> record has the following fields:</p> -->
     
 <!--     <taglist> -->
       
 <!--       <tag>valid_policy</tag> -->
-<!--       <item> Is a single policy OID representing a -->
+<!--       <item>A single policy OID representing a -->
 <!--          valid policy for the path of length x.</item> -->
       
 <!--       <tag>qualifier_set</tag> -->
@@ -151,13 +209,13 @@
 <!--          with the valid policy in certificate x.</item> -->
       
 <!--       <tag>critically_indicator</tag> -->
-<!--       <item>The critically_indicator indicates whether the -->
+<!--       <item>Indicates whether the -->
 <!--          certificate policy extension in certificate x was marked as -->
-<!--          critical. </item> -->
+<!--          critical.</item> -->
       
 <!--       <tag>expected_policy_set</tag> -->
-<!--       <item>The expected_policy_set contains one or more policy OIDs -->
-<!--          that would satisfy this policy in the certificate x+1. </item>         -->
+<!--       <item>Contains one or more policy OIDs -->
+<!--          that would satisfy this policy in the certificate x+1.</item>         -->
 <!--     </taglist> -->
   </section> 
 
@@ -166,27 +224,27 @@
   <func>
     <name>compute_key(OthersKey, MyKey)-></name>
     <name>compute_key(OthersKey, MyKey, Params)-></name>
-    <fsummary> Compute shared secret</fsummary>
+    <fsummary>Computes shared secret.</fsummary>
     <type>
       <v>OthersKey = #'ECPoint'{} | binary(), MyKey = #'ECPrivateKey'{} | binary()</v>
       <v>Params =  #'DHParameter'{}</v>
     </type>
   <desc>
-    <p> Compute shared secret </p>
+    <p>Computes shared secret.</p>
   </desc>
   </func>
 
   <func>
     <name>decrypt_private(CipherText, Key) -> binary()</name>
     <name>decrypt_private(CipherText, Key, Options) -> binary()</name>
-    <fsummary>Public key decryption.</fsummary>
+    <fsummary>Public-key decryption.</fsummary>
     <type>
       <v>CipherText = binary()</v>
       <v>Key = rsa_private_key()</v>
       <v>Options = public_crypt_options()</v>
   </type> 
   <desc> 
-    <p>Public key decryption using the private key. See also <seealso
+    <p>Public-key decryption using the private key. See also <seealso
 	marker="crypto:crypto#private_decrypt/4">crypto:private_decrypt/4</seealso></p> 
   </desc> 
   </func>
@@ -194,156 +252,156 @@
   <func>
     <name>decrypt_public(CipherText, Key) - > binary()</name>
     <name>decrypt_public(CipherText, Key, Options) - > binary()</name>
-    <fsummary></fsummary>
+    <fsummary>Public-key decryption.</fsummary>
     <type>
       <v>CipherText = binary()</v>
       <v>Key = rsa_public_key()</v>
       <v>Options = public_crypt_options()</v>
   </type> 
   <desc> 
-    <p> Public key decryption using the public key. See also <seealso
+    <p>Public-key decryption using the public key. See also <seealso
 	marker="crypto:crypto#public_decrypt/4">crypto:public_decrypt/4</seealso></p> 
   </desc> 
   </func> 
 
   <func>
     <name>der_decode(Asn1type, Der) -> term()</name>
-    <fsummary> Decodes a public key ASN.1 DER encoded entity.</fsummary>
+    <fsummary>Decodes a public-key ASN.1 DER encoded entity.</fsummary>
     <type>
       <v>Asn1Type = atom()</v>
-      <d> ASN.1 type present in the public_key applications
-      asn1 specifications.</d>
+      <d>ASN.1 type present in the <c>public_key</c> applications
+      ASN.1 specifications.</d>
       <v>Der = der_encoded()</v>
     </type> 
     <desc> 
-      <p> Decodes a public key ASN.1 DER encoded entity.</p>
+      <p>Decodes a public-key ASN.1 DER encoded entity.</p>
     </desc> 
   </func>
     
   <func>
     <name>der_encode(Asn1Type, Entity) -> der_encoded()</name>
-    <fsummary> Encodes a public key entity with asn1 DER encoding.</fsummary>
+    <fsummary>Encodes a public-key entity with ASN.1 DER encoding.</fsummary>
     <type>
       <v>Asn1Type = atom()</v>
-      <d> Asn1 type present in the public_key applications
+      <d>ASN.1 type present in the public_key applications
 	 ASN.1 specifications.</d>
       <v>Entity = term()</v>
-      <d>The erlang representation of <c>Asn1Type</c></d>
+      <d>Erlang representation of <c>Asn1Type</c></d>
   </type> 
   <desc> 
-    <p> Encodes a public key entity with ASN.1 DER encoding.</p>
+    <p>Encodes a public-key entity with ASN.1 DER encoding.</p>
   </desc> 
   </func>
 
   <func>
     <name>generate_key(Params) -> {Public::binary(), Private::binary()}  | #'ECPrivateKey'{} </name>
-    <fsummary>Generates a new keypair</fsummary>
+    <fsummary>Generates a new keypair.</fsummary>
     <type>
-      <v> Params = #'DHParameter'{} |  {namedCurve, oid()} |  #'ECParameters'{} </v>
+      <v>Params = #'DHParameter'{} |  {namedCurve, oid()} |  #'ECParameters'{}</v>
     </type>
   <desc>
-    <p>Generates a new keypair</p>
+    <p>Generates a new keypair.</p>
   </desc>
   </func>
 
   <func>
     <name>pem_decode(PemBin) -> [pem_entry()]</name>
-    <fsummary>Decode PEM binary data and return
-    entries as ASN.1 DER encoded entities. </fsummary>
+    <fsummary>Decodes PEM binary data and returns
+    entries as ASN.1 DER encoded entities.</fsummary>
     <type>
       <v>PemBin = binary()</v>
       <d>Example {ok, PemBin} = file:read_file("cert.pem").</d>
     </type> 
   <desc> 
-    <p>Decode PEM binary data and return
+    <p>Decodes PEM binary data and returns
     entries as ASN.1 DER encoded entities.</p>
   </desc> 
   </func> 
     
    <func>
     <name>pem_encode(PemEntries) -> binary()</name>
-    <fsummary>Creates a PEM binary</fsummary>
+    <fsummary>Creates a PEM binary.</fsummary>
     <type>
       <v> PemEntries = [pem_entry()] </v> 
   </type> 
   <desc> 
-    <p>Creates a PEM binary</p> 
+    <p>Creates a PEM binary.</p> 
   </desc> 
   </func>
 
    <func>
     <name>pem_entry_decode(PemEntry) -> term()</name>
     <name>pem_entry_decode(PemEntry, Password) -> term()</name>
-    <fsummary>Decodes a pem entry.</fsummary>
+    <fsummary>Decodes a PEM entry.</fsummary>
     <type>
-      <v> PemEntry = pem_entry() </v> 
-      <v> Password = string() </v> 
+      <v>PemEntry = pem_entry()</v> 
+      <v>Password = string()</v> 
   </type> 
   <desc> 
-    <p>Decodes a PEM entry. pem_decode/1 returns a list of PEM
-    entries. Note that if the PEM entry is of type
-    'SubjectPublickeyInfo' it will be further decoded to an
-    rsa_public_key() or dsa_public_key().</p>
+    <p>Decodes a PEM entry. <c>pem_decode/1</c> returns a list of PEM
+    entries. Notice that if the PEM entry is of type
+    'SubjectPublickeyInfo', it is further decoded to an
+    <c>rsa_public_key()</c> or <c>dsa_public_key()</c>.</p>
   </desc> 
   </func>
 
    <func>
     <name>pem_entry_encode(Asn1Type, Entity) -> pem_entry()</name>
     <name>pem_entry_encode(Asn1Type, Entity, {CipherInfo, Password}) -> pem_entry()</name>
-    <fsummary> Creates a PEM entry that can be fed to pem_encode/1.</fsummary>
+    <fsummary>Creates a PEM entry that can be fed to <c>pem_encode/1</c>.</fsummary>
     <type>
       <v>Asn1Type = pki_asn1_type()</v>
       <v>Entity = term()</v>
-      <d>The Erlang representation of
-      <c>Asn1Type</c>.  If <c>Asn1Type</c> is 'SubjectPublicKeyInfo'
-      then <c>Entity</c> must be either an rsa_public_key() or a
-      dsa_public_key() and this function will create the appropriate
+      <d>Erlang representation of
+      <c>Asn1Type</c>.  If <c>Asn1Type</c> is 'SubjectPublicKeyInfo',
+      <c>Entity</c> must be either an <c>rsa_public_key()</c> or a
+      <c>dsa_public_key()</c> and this function creates the appropriate
       'SubjectPublicKeyInfo' entry.
       </d>
       <v>CipherInfo = cipher_info()</v>
       <v>Password = string()</v> 
   </type> 
   <desc> 
-    <p> Creates a PEM entry that can be feed to pem_encode/1.</p>
+    <p>Creates a PEM entry that can be feed to <c>pem_encode/1</c>.</p>
   </desc> 
   </func>
 
   <func>
     <name>encrypt_private(PlainText, Key) -> binary()</name>
-    <fsummary> Public key encryption using the private key.</fsummary>
+    <fsummary>Public-key encryption using the private key.</fsummary>
     <type>
       <v>PlainText = binary()</v>
       <v>Key = rsa_private_key()</v> 
   </type> 
   <desc> 
-    <p> Public key encryption using the private key.
+    <p>Public-key encryption using the private key.
      See also <seealso
-	marker="crypto:crypto#private_encrypt/4">crypto:private_encrypt/4</seealso></p> 
+	marker="crypto:crypto#private_encrypt/4">crypto:private_encrypt/4</seealso>.</p> 
   </desc> 
   </func>   
 
   <func>
     <name>encrypt_public(PlainText, Key) -> binary()</name>
-    <fsummary> Public key encryption using the public key.</fsummary>
+    <fsummary>Public-key encryption using the public key.</fsummary>
     <type>
       <v>PlainText = binary()</v>
       <v>Key = rsa_public_key()</v> 
   </type> 
   <desc> 
-    <p> Public key encryption using the public key.  See also <seealso
-	marker="crypto:crypto#public_encrypt/4">crypto:public_encrypt/4</seealso></p> 
+    <p>Public-key encryption using the public key. See also <seealso
+	marker="crypto:crypto#public_encrypt/4">crypto:public_encrypt/4</seealso>.</p> 
   </desc> 
   </func>   
   
   <func>
     <name>pkix_decode_cert(Cert, otp|plain) ->  #'Certificate'{} | #'OTPCertificate'{}</name>
-    <fsummary> Decodes an ASN.1 DER encoded PKIX x509 certificate.</fsummary>
+    <fsummary>Decodes an ASN.1 DER-encoded PKIX x509 certificate.</fsummary>
     <type>
       <v>Cert = der_encoded()</v> 
   </type> 
   <desc> 
-    <p>Decodes an ASN.1 DER encoded PKIX certificate.  The otp option
-    will use the customized ASN.1 specification OTP-PKIX.asn1 for
+    <p>Decodes an ASN.1 DER-encoded PKIX certificate. Option <c>otp</c>
+    uses the customized ASN.1 specification OTP-PKIX.asn1 for
     decoding and also recursively decode most of the standard
     parts.</p>
   </desc> 
@@ -355,54 +413,54 @@
     certificate.</fsummary>
     <type>
       <v>Asn1Type = atom()</v>
-      <d>The ASN.1 type can be 'Certificate', 'OTPCertificate' or a subtype of either .</d>
+      <d>The ASN.1 type can be 'Certificate', 'OTPCertificate' or a subtype of either.</d>
       <v>Entity = #'Certificate'{} | #'OTPCertificate'{} | a valid subtype</v>
   </type> 
   <desc> 
     <p>DER encodes a PKIX x509 certificate or part of such a
     certificate. This function must be used for encoding certificates or parts of certificates
-    that are decoded/created in the otp format, whereas for the plain format this
-    function will directly call der_encode/2. </p> 
+    that are decoded/created in the <c>otp</c> format, whereas for the plain format this
+    function directly calls <c>der_encode/2</c>.</p> 
   </desc> 
   </func>
 
  <func>
     <name>pkix_is_issuer(Cert, IssuerCert) -> boolean()</name>
-    <fsummary> Checks if <c>IssuerCert</c> issued <c>Cert</c> </fsummary>
+    <fsummary>Checks if <c>IssuerCert</c> issued <c>Cert</c>.</fsummary>
     <type>
       <v>Cert = der_encoded() | #'OTPCertificate'{}</v>
       <v>IssuerCert = der_encoded() | #'OTPCertificate'{}</v>
   </type> 
   <desc> 
-    <p> Checks if <c>IssuerCert</c> issued <c>Cert</c> </p> 
+    <p>Checks if <c>IssuerCert</c> issued <c>Cert</c>.</p> 
   </desc> 
   </func>
   
   <func>
     <name>pkix_is_fixed_dh_cert(Cert) -> boolean()</name>
-    <fsummary> Checks if a Certificate is a fixed Diffie-Hellman Cert.</fsummary>
+    <fsummary>Checks if a certificate is a fixed Diffie-Hellman certificate.</fsummary>
     <type>
         <v>Cert = der_encoded() | #'OTPCertificate'{}</v>
   </type> 
   <desc> 
-    <p> Checks if a Certificate is a fixed Diffie-Hellman Cert.</p> 
+    <p>Checks if a certificate is a fixed Diffie-Hellman certificate.</p> 
   </desc> 
   </func>  
   
   <func>
     <name>pkix_is_self_signed(Cert) -> boolean()</name>
-    <fsummary> Checks if a Certificate is self signed.</fsummary>
+    <fsummary>Checks if a certificate is self-signed.</fsummary>
     <type>
        <v>Cert = der_encoded() | #'OTPCertificate'{}</v>
   </type> 
   <desc> 
-    <p> Checks if a Certificate is self signed.</p> 
+    <p>Checks if a certificate is self-signed.</p> 
   </desc> 
   </func>
 
   <func>
     <name>pkix_issuer_id(Cert, IssuedBy) -> {ok, IssuerID} | {error, Reason}</name>
-    <fsummary> Returns the issuer id.</fsummary>
+    <fsummary>Returns the issuer id.</fsummary>
     <type>
         <v>Cert = der_encoded() | #'OTPCertificate'{}</v>
 	<v>IssuedBy = self | other</v>
@@ -411,43 +469,43 @@
 	<v>Reason = term()</v>
     </type> 
     <desc> 
-      <p> Returns the issuer id.</p> 
+    <p>Returns the issuer id.</p> 
     </desc> 
   </func>
   
  
   <func>
     <name>pkix_normalize_name(Issuer) -> Normalized</name>
-    <fsummary>Normalizes a issuer name so that it can be easily
-    compared to another issuer name. </fsummary>
+    <fsummary>Normalizes an issuer name so that it can be easily
+    compared to another issuer name.</fsummary>
     <type>
       <v>Issuer = issuer_name()</v>
       <v>Normalized = issuer_name()</v>
   </type> 
   <desc> 
-    <p>Normalizes a issuer name so that it can be easily
+    <p>Normalizes an issuer name so that it can be easily
     compared to another issuer name.</p> 
   </desc> 
   </func>
    
   <func>
     <name>pkix_path_validation(TrustedCert, CertChain, Options) -> {ok, {PublicKeyInfo, PolicyTree}} | {error, {bad_cert, Reason}} </name>
-    <fsummary> Performs a basic path validation according to RFC 5280.</fsummary>
+    <fsummary>Performs a basic path validation according to RFC 5280.</fsummary>
      <type>
-       <v> TrustedCert =  #'OTPCertificate'{} | der_encoded() | atom()  </v>
-       <d>Normally a trusted certificate but it can also be a path validation
+       <v>TrustedCert =  #'OTPCertificate'{} | der_encode() | atom()</v>
+       <d>Normally a trusted certificate, but it can also be a path-validation
        error that can be discovered while
-       constructing the input to this function and that should be run through the <c>verify_fun</c>.
-       For example <c>unknown_ca </c> or <c>selfsigned_peer </c>
+       constructing the input to this function and that is to be run through the <c>verify_fun</c>.
+       Examples are <c>unknown_ca</c> and <c>selfsigned_peer.</c>
        </d>
-       <v> CertChain = [der_encoded()]</v>
-       <d>A list of DER encoded certificates in trust order ending with the peer certificate.</d>
-       <v> Options = proplists:proplist()</v>
+       <v>CertChain = [der_encode()]</v>
+       <d>A list of DER-encoded certificates in trust order ending with the peer certificate.</d>
+       <v>Options = proplists:proplist()</v>
        <v>PublicKeyInfo = {?'rsaEncryption' | ?'id-dsa',
        rsa_public_key() | integer(), 'NULL' | 'Dss-Parms'{}}</v>
-       <v> PolicyTree = term() </v>
-       <d>At the moment this will always be an empty list as Policies are not currently supported</d>
-       <v> Reason = cert_expired | invalid_issuer | invalid_signature | name_not_permitted |
+       <v>PolicyTree = term()</v>
+       <d>At the moment this is always an empty list as policies are not currently supported.</d>
+       <v>Reason = cert_expired | invalid_issuer | invalid_signature | name_not_permitted |
        missing_basic_constraint | invalid_key_usage | {revoked, crl_reason()} | atom()
        </v>
      </type>
@@ -455,17 +513,17 @@
        <p>
 	 Performs a basic path validation according to
 	 <url href="http://www.ietf.org/rfc/rfc5280.txt">RFC 5280.</url>
-	 However CRL validation is done separately by <seealso
-	 marker="#pkix_crls_validate-3">pkix_crls_validate/3 </seealso> and should be called
-	 from the supplied <c>verify_fun</c>
+	 However, CRL validation is done separately by <seealso
+	 marker="#pkix_crls_validate-3">pkix_crls_validate/3 </seealso> and is to be called
+	 from the supplied <c>verify_fun</c>.
        </p>
 
-       <taglist>
-	 <p> Available options are: </p>
+       <p>Available options:</p>
 
+       <taglist>
 	<tag>{verify_fun, fun()}</tag>
 	<item>
-	  <p>The fun should be defined as:</p>
+	  <p>The fun must be defined as:</p>
 
 	  <code>
 fun(OtpCert :: #'OTPCertificate'{},
@@ -478,53 +536,53 @@ fun(OtpCert :: #'OTPCertificate'{},
 	{unknown, UserState :: term()}.
 	  </code>
 
-	<p>If the verify callback fun returns {fail, Reason}, the
+	<p>If the verify callback fun returns <c>{fail, Reason}</c>, the
 	verification process is immediately stopped. If the verify
-	callback fun returns {valid, UserState}, the verification
-	process is continued, this can be used to accept specific path
-	validation errors such as <c>selfsigned_peer</c> as well as
-	verifying application specific extensions.  If called with an
-	extension unknown to the user application the return value
-	{unknown, UserState} should be used.</p>
+	callback fun returns <c>{valid, UserState}</c>, the verification
+	process is continued. This can be used to accept specific path
+	validation errors, such as <c>selfsigned_peer</c>, as well as
+	verifying application-specific extensions. If called with an
+	extension unknown to the user application, the return value
+	<c>{unknown, UserState}</c> is to be used.</p>
 
 	</item>
 	<tag>{max_path_length, integer()}</tag>
 	<item>
 	  The <c>max_path_length</c> is the maximum number of non-self-issued
-	  intermediate certificates that may follow the peer certificate
-	  in a valid certification path.  So if <c>max_path_length</c> is 0 the PEER must
-	  be signed by the trusted ROOT-CA directly, if 1 the path can
-	  be PEER, CA, ROOT-CA, if it is 2 PEER, CA, CA, ROOT-CA and so
-	  on.
+	  intermediate certificates that can follow the peer certificate
+	  in a valid certification path. So, if <c>max_path_length</c> is 0, the PEER must
+	  be signed by the trusted ROOT-CA directly, if it is 1, the path can
+	  be PEER, CA, ROOT-CA, if it is 2, the path can
+	  be PEER, CA, CA, ROOT-CA, and so on.
 	</item>
       </taglist>
 
-      <p> Possible reasons for a bad certificate are: </p>
+      <p>Possible reasons for a bad certificate: </p>
       <taglist>
 	<tag>cert_expired</tag>
-	<item>The certificate is no longer valid as its expiration date has passed.</item>
+	<item><p>Certificate is no longer valid as its expiration date has passed.</p></item>
 
 	<tag>invalid_issuer</tag>
-	<item>The certificate issuer name does not match the name of the issuer certificate in the chain.</item>
+	<item><p>Certificate issuer name does not match the name of the issuer certificate in the chain.</p></item>
 
 	<tag>invalid_signature</tag>
-	<item>The certificate was not signed by its issuer certificate in the chain.</item>
+	<item><p>Certificate was not signed by its issuer certificate in the chain.</p></item>
 
 	<tag>name_not_permitted</tag>
-	<item>Invalid Subject Alternative Name extension.</item>
+	<item><p>Invalid Subject Alternative Name extension.</p></item>
 
 	<tag>missing_basic_constraint</tag>
-	<item>Certificate, required to have the basic constraints extension, does not have
-	a basic constraints extension.</item>
+	<item><p>Certificate, required to have the basic constraints extension, does not have
+	a basic constraints extension.</p></item>
 
 	<tag>invalid_key_usage</tag>
-	<item>Certificate key is used in an invalid way according to the key usage extension.</item>
+	<item><p>Certificate key is used in an invalid way according to the key-usage extension.</p></item>
 
 	<tag>{revoked, crl_reason()}</tag>
-	<item>Certificate has been revoked.</item>
+	<item><p>Certificate has been revoked.</p></item>
 
 	<tag>atom()</tag>
-	<item>Application specific error reason that should be checked by the verify_fun</item>
+	<item><p>Application-specific error reason that is to be checked by the <c>verify_fun</c>.</p></item>
       </taglist>
 
     </desc>
@@ -543,44 +601,47 @@ fun(OtpCert :: #'OTPCertificate'{},
    
    <func>
      <name>pkix_crls_validate(OTPCertificate, DPAndCRLs, Options) -> CRLStatus()</name>
-     <fsummary> Performs CRL validation.</fsummary>
+     <fsummary>Performs CRL validation.</fsummary>
      <type>
-       <v> OTPCertificate =  #'OTPCertificate'{}</v>
-       <v> DPAndCRLs  = [{DP::#'DistributionPoint'{}, {DerCRL::der_encoded(), CRL::#'CertificateList'{}}}] </v>
-       <v> Options = proplists:proplist()</v>
-       <v> CRLStatus() =  valid | {bad_cert, revocation_status_undetermined} |
+       <v>OTPCertificate =  #'OTPCertificate'{}</v>
+       <v>DPAndCRLs  = [{DP::#'DistributionPoint'{}, {DerCRL::der_encoded(), CRL::#'CertificateList'{}}}] </v>
+       <v>Options = proplists:proplist()</v>
+       <v>CRLStatus() =  valid | {bad_cert, revocation_status_undetermined} |
        {bad_cert, {revoked, crl_reason()}}</v>
      </type>
      <desc>
-      <p> Performs CRL validation. It is intended to be called from
+      <p>Performs CRL validation. It is intended to be called from
       the verify fun of  <seealso marker="#pkix_path_validation-3"> pkix_path_validation/3
-       </seealso></p>
+       </seealso>.</p>
+
+       <p>Available options:</p>
+
       <taglist>
-	<p> Available options are: </p>
+	
 	<tag>{update_crl, fun()}</tag>
 	<item>
-	  <p>The fun has the following type spec:</p>
+	  <p>The fun has the following type specification:</p>
 
 	  <code> fun(#'DistributionPoint'{}, #'CertificateList'{}) ->
         #'CertificateList'{}</code>
 
-	  <p>The fun should use the information in the distribution point to acesses
-	  the lates possible version of the CRL. If this fun is not specified
-	  public_key will use the default implementation:
+	  <p>The fun uses the information in the distribution point to access
+	  the latest possible version of the CRL. If this fun is not specified,
+	  <c>public_key</c> uses the default implementation:
 	  </p>
 	  <code> fun(_DP, CRL) -> CRL end</code>
 	</item>
 
 	<tag>{issuer_fun, fun()}</tag>
 	<item>
-	  <p>The fun has the following type spec:</p>
+	  <p>The fun has the following type specification:</p>
 
 	  <code>
 fun(#'DistributionPoint'{}, #'CertificateList'{},
     {rdnSequence,[#'AttributeTypeAndValue'{}]}, term()) ->
 	{ok, #'OTPCertificate'{}, [der_encoded]}</code>
 
-	  <p>The fun should return the root certificate and certificate chain
+	  <p>The fun returns the root certificate and certificate chain
 	  that has signed the CRL. 
 	  </p>
 	  <code> fun(DP, CRL, Issuer, UserState) -> {ok, RootCert, CertChain}</code>
@@ -635,83 +696,83 @@ fun(#'DistributionPoint'{}, #'CertificateList'{},
       <v>Key = rsa_public_key() | dsa_public_key()</v> 
     </type> 
     <desc> 
-      <p>Signs a 'OTPTBSCertificate'. Returns the corresponding
-      der encoded certificate.</p> 
+      <p>Signs an 'OTPTBSCertificate'. Returns the corresponding
+      DER-encoded certificate.</p> 
     </desc> 
   </func> 
 
   <func>
     <name>pkix_sign_types(AlgorithmId) -> {DigestType, SignatureType}</name>
-    <fsummary>Translates signature algorithm oid to erlang digest and signature algorithm types.</fsummary>
+    <fsummary>Translates signature algorithm OID to Erlang digest and signature algorithm types.</fsummary>
     <type>
       <v>AlgorithmId = oid()</v>
-      <d>Signature oid from a certificate or a certificate revocation list</d>
-      <v>DigestType = rsa_digest_type() | dss_digest_type() </v>
+      <d>Signature OID from a certificate or a certificate revocation list.</d>
+      <v>DigestType = rsa_digest_type() | dss_digest_type()</v>
       <v>SignatureType = rsa | dsa</v>
     </type>
     <desc>
-      <p>Translates signature algorithm oid to erlang digest and signature types.
+      <p>Translates signature algorithm OID to Erlang digest and signature types.
       </p>
     </desc>
   </func>
 
   <func>  
     <name>pkix_verify(Cert, Key) -> boolean()</name>
-    <fsummary> Verify pkix x.509 certificate signature.</fsummary>
+    <fsummary>Verifies PKIX x.509 certificate signature.</fsummary>
     <type>
       <v>Cert = der_encoded()</v>
       <v>Key = rsa_public_key() | dsa_public_key()</v> 
     </type> 
   <desc> 
-    <p> Verify PKIX x.509 certificate signature.</p>
+    <p>Verifies PKIX x.509 certificate signature.</p>
   </desc> 
   </func> 
 
   <func>
     <name>sign(Msg, DigestType, Key) -> binary()</name>
-    <fsummary> Create digital signature.</fsummary>
+    <fsummary>Creates a digital signature.</fsummary>
     <type>
        <v>Msg = binary() | {digest,binary()}</v>
-       <d>The msg is either the binary "plain text" data to be
-       signed or it is the hashed value of "plain text" i.e. the
+       <d>The <c>Msg</c> is either the binary "plain text" data to be
+       signed or it is the hashed value of "plain text", that is, the
        digest.</d>
        <v>DigestType = rsa_digest_type() | dss_digest_type() | ecdsa_digest_type()</v>
        <v>Key = rsa_private_key() | dsa_private_key() | ec_private_key()</v>
   </type>
   <desc>
-    <p> Creates a digital signature.</p> 
+    <p>Creates a digital signature.</p> 
   </desc> 
   </func>   
 
   <func>
     <name>ssh_decode(SshBin,  Type) -> [{public_key(), Attributes::list()}]</name>
-    <fsummary>Decodes a ssh file-binary. </fsummary>
+    <fsummary>Decodes an SSH file-binary.</fsummary>
     <type>
       <v>SshBin = binary()</v>
       <d>Example {ok, SshBin} = file:read_file("known_hosts").</d>
-      <v> Type = public_key | ssh_file()</v>
-      <d>If <c>Type</c> is <c>public_key</c> the binary may be either
-      a rfc4716 public key or a openssh public key.</d>
+      <v>Type = public_key | ssh_file()</v>
+      <d>If <c>Type</c> is <c>public_key</c> the binary can be either
+      an RFC4716 public key or an OpenSSH public key.</d>
     </type>
   <desc>
-    <p> Decodes a ssh file-binary. In the case of know_hosts or
-    auth_keys the binary may include one or more lines of the
+    <p>Decodes an SSH file-binary. In the case of <c>know_hosts</c> or
+    <c>auth_keys</c>, the binary can include one or more lines of the
     file. Returns a list of public keys and their attributes, possible
     attribute values depends on the file type represented by the
     binary.
     </p>
 
     <taglist>
-      <tag>rfc4716 attributes - see RFC 4716</tag>
-      <item>{headers, [{string(), utf8_string()}]}</item>
-      <tag>auth_key attributes - see man sshd </tag>
+      <tag>RFC4716 attributes - see RFC 4716.</tag>
+      <item><p>{headers, [{string(), utf8_string()}]}</p></item>
+      <tag>auth_key attributes - see manual page for sshd.</tag>
       <item>{comment, string()}</item>
       <item>{options, [string()]}</item>
-      <item>{bits, integer()} - In ssh version 1 files</item>
-      <tag>known_host attributes - see man sshd</tag>
+      <item><p>{bits, integer()} - In SSH version 1 files.</p></item>
+      <tag>known_host attributes - see manual page for sshd.</tag>
       <item>{hostnames, [string()]}</item>
       <item>{comment, string()}</item>
-      <item>{bits, integer()} - In ssh version 1 files</item>
+      <item><p>{bits, integer()} - In SSH version 1 files.</p></item>
     </taglist>
 
   </desc>
@@ -719,16 +780,16 @@ fun(#'DistributionPoint'{}, #'CertificateList'{},
 
   <func>
     <name>ssh_encode([{Key, Attributes}], Type) -> binary()</name>
-    <fsummary> Encodes a list of ssh file entries to a binary.</fsummary>
+    <fsummary>Encodes a list of SSH file entries to a binary.</fsummary>
     <type>
       <v>Key = public_key()</v>
       <v>Attributes = list()</v>
       <v>Type = ssh_file()</v>
     </type>
   <desc>
-    <p>Encodes a list of ssh file entries (public keys and attributes) to a binary. Possible
-    attributes depends on the file type, see <seealso
-    marker="#ssh_decode-2"> ssh_decode/2 </seealso></p>
+    <p>Encodes a list of SSH file entries (public keys and attributes) to a binary. Possible
+    attributes depend on the file type, see <seealso
+    marker="#ssh_decode-2"> ssh_decode/2 </seealso>.</p>
   </desc>
   </func>
 
@@ -737,14 +798,14 @@ fun(#'DistributionPoint'{}, #'CertificateList'{},
     <fsummary>Verifies a digital signature.</fsummary>
     <type>
       <v>Msg = binary() | {digest,binary()}</v>
-       <d>The msg is either the binary "plain text" data 
-        or it is the hashed value of "plain text" i.e. the digest.</d>
+       <d>The <c>Msg</c> is either the binary "plain text" data 
+        or it is the hashed value of "plain text", that is, the digest.</d>
       <v>DigestType = rsa_digest_type() | dss_digest_type() | ecdsa_digest_type()</v>
       <v>Signature = binary()</v>
       <v>Key = rsa_public_key() | dsa_public_key() | ec_public_key()</v>
   </type>
   <desc>
-    <p>Verifies a digital signature</p>
+    <p>Veryfies a digital signature.</p>
   </desc> 
   </func>
   
diff --git a/lib/public_key/doc/src/public_key_records.xml b/lib/public_key/doc/src/public_key_records.xml
index a7dfc41449..24f5faf38e 100644
--- a/lib/public_key/doc/src/public_key_records.xml
+++ b/lib/public_key/doc/src/public_key_records.xml
@@ -23,7 +23,7 @@
   The Initial Developer of the Original Code is Ericsson AB.
     </legalnotice>
 
-    <title>Public key records</title>
+    <title>Public-Key Records</title>
     <prepared>Ingela Anderton Andin</prepared>
     <responsible></responsible>
     <docno></docno>
@@ -34,14 +34,14 @@
     <file>public_key_records.xml</file>
   </header>
     
-  <p>This chapter briefly describes Erlang records derived from ASN1
+  <p>This section briefly describes Erlang records derived from ASN.1
   specifications used to handle public and private keys.
-  The intent is to describe the data types
-  and not to specify the semantics of each component. For information on the
-  semantics, please see the relevant standards and RFCs.</p>
+  The scope is to describe the data types of each component,
+  not the semantics. For information on the
+  semantics, refer to the relevant standards and RFCs.</p>
 
   <p>Use the following include directive to get access to the
-  records and constant macros described in the following sections.</p>
+  records and constant macros described in the following sections:</p>
   
   <code> -include_lib("public_key/include/public_key.hrl"). </code>
 
@@ -49,13 +49,15 @@
      <title>Common Data Types</title>   
 
     <p>Common non-standard Erlang
-    data types used to described the record fields in the
-    below sections are defined in <seealso
-    marker="public_key">public key reference manual </seealso></p>
+    data types used to describe the record fields in the
+    following sections are defined in the <c>public_key</c> <seealso
+    marker="public_key">Reference Manual</seealso>.</p>
   </section>
 
   <section>
-    <title>RSA as defined by the PKCS-1 standard and  <url href="http://www.ietf.org/rfc/rfc3447.txt"> RFC 3447 </url></title>
+    <title>The RSA According to PKCS-1 and RFC 3447</title>
+    <p>RSA as defined by the PKCS-1 standard and <url href="http://www.ietf.org/rfc/rfc3447.txt"> 
+    RFC 3447 </url> follows:</p>
     
     <code>
 #'RSAPublicKey'{
@@ -80,15 +82,15 @@
 	prime,           % integer()
 	exponent,        % integer()
 	coefficient      % integer()
- 	 }.	 
-    </code>
+ 	 }.	 </code>
 
   </section>
 
   <section>
-    <title>DSA as defined by
-    <url href="http://csrc.nist.gov/publications/fips/fips186-3/fips_186-3.pdf">  Digital Signature Standard (NIST FIPS PUB 186-2) </url>
-    </title>
+    <title>DSA According to DSS</title>
+    <p>The DSA as defined by the
+    <url href="http://csrc.nist.gov/publications/fips/fips186-3/fips_186-3.pdf">  
+    Digital Signature Standard (DSS), NIST FIPS PUB 186-2</url> follows:</p>
     
     <code>	 
 #'DSAPrivateKey',{
@@ -104,13 +106,13 @@
          p,         % integer()
 	 q,         % integer()
 	 g          % integer()
-	 }. 
-    </code>
+	 }. </code>
   </section>
 
   <section>
-       <title>ECC (Elliptic Curve) <url href="http://www.ietf.org/rfc/rfc3447.txt"> RFC 5480 </url> 
-    </title>
+       <title>ECC According to RFC 5480</title>
+       <p>The Elliptic Curve (ECC) as defined by <url href="http://www.ietf.org/rfc/rfc3447.txt"> 
+       RFC 5480 </url> follows:</p>
     
     <code>	 
 #'ECPrivateKey'{
diff --git a/lib/public_key/doc/src/records.xml b/lib/public_key/doc/src/records.xml
new file mode 100644
index 0000000000..75265791af
--- /dev/null
+++ b/lib/public_key/doc/src/records.xml
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE part SYSTEM "part.dtd">
+
+<part xmlns:xi="http://www.w3.org/2001/XInclude">
+  <header>
+    <copyright>
+      <year>2008</year>
+      <year>2014</year>
+      <holder>Ericsson AB, All Rights Reserved</holder>
+    </copyright>
+    <legalnotice>
+  The contents of this file are subject to the Erlang Public License,
+  Version 1.1, (the "License"); you may not use this file except in
+  compliance with the License. You should have received a copy of the
+  Erlang Public License along with this software. If not, it can be
+  retrieved online at http://www.erlang.org/.
+
+  Software distributed under the License is distributed on an "AS IS"
+  basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+  the License for the specific language governing rights and limitations
+  under the License.
+
+  The Initial Developer of the Original Code is Ericsson AB.
+    </legalnotice>
+
+    <title>Records</title>
+    <prepared>Tommy Månevik</prepared>
+    <docno></docno>
+    <date>2015-04-01</date>
+    <rev></rev>
+    <file>records.xml</file>
+  </header>
+  <description>
+    <p>This section describes Erlang records derived from ASN.1 specifications, 
+    used to handle the following:
+    </p>
+    <list type="bulleted">
+      <item>Public and private keys</item>
+      <item><c>X509 certificates</c> and <c>CertificationRequest</c></item>
+    </list>
+  </description>
+ 
+  <xi:include href="public_key_records.xml"/>
+  <xi:include href="cert_records.xml"/>
+ 
+</part>
+
diff --git a/lib/public_key/doc/src/ref_man.xml b/lib/public_key/doc/src/ref_man.xml
index b7078891d4..9c80cf4b9f 100644
--- a/lib/public_key/doc/src/ref_man.xml
+++ b/lib/public_key/doc/src/ref_man.xml
@@ -31,8 +31,8 @@
     <file>ref_man.xml</file>
   </header>
   <description>
-    <p> Provides functions to handle public key infrastructure
-    from RFC 3280 (X.509 certificates) and some parts of the PKCS-standard.
+    <p>The <c>public_key</c> application provides functions to handle public-key infrastructure
+    from RFC 3280 (X.509 certificates) and parts of the PKCS standard.
     </p>
   </description>
   <xi:include href="public_key.xml"/>
diff --git a/lib/public_key/doc/src/using_public_key.xml b/lib/public_key/doc/src/using_public_key.xml
index 450bd7e35f..69b8c0dcb9 100644
--- a/lib/public_key/doc/src/using_public_key.xml
+++ b/lib/public_key/doc/src/using_public_key.xml
@@ -22,27 +22,27 @@
     </legalnotice>
 
     <title>Getting Started</title>
+    <prepared></prepared>
+    <docno></docno>
+    <date></date>
+    <rev></rev>
     <file>using_public_key.xml</file>
   </header>
 
-  <section>
-    <title>General information</title>
+  <p>This section describes examples of how to use the 
+    <c>public_key</c> API. Keys and certificates used in the following 
+    sections are generated only for testing the <c>public_key</c> 
+    application.</p>
 
-    <p> This chapter is dedicated to showing some
-    examples of how to use the public_key API. Keys and certificates
-    used in the following sections are generated only for the purpose
-    of testing the public key application.</p>
+    <p>Some shell printouts in the following examples
+    are abbreviated for increased readability.</p>
 
-    <p>Note that some shell printouts, in the following examples,
-    have been abbreviated for increased readability.</p>
-    
-  </section>
-    
+     
   <section>
-    <title>PEM files</title>
-    <p> Public key data (keys, certificates etc) may be stored in PEM format. PEM files
-    comes from the Private Enhanced Mail Internet standard and has a
-    structure that looks like this:</p>
+    <title>PEM Files</title>
+    <p>Public-key data (keys, certificates, and so on) can be stored in 
+    Privacy Enhanced Mail (PEM) format. 
+    The PEM files have the following structure:</p>
 
     <code>&lt;text&gt;
 	-----BEGIN &lt;SOMETHING&gt;-----
@@ -51,19 +51,20 @@
 	-----END &lt;SOMETHING&gt;-----
 	&lt;text&gt;</code>
 
-    <p>A file can contain several BEGIN/END blocks. Text lines between
-    blocks are ignored.  Attributes, if present, are currently ignored except
-    for <c>Proc-Type</c> and <c>DEK-Info</c> that are used when the DER data is
-    encrypted.</p>
+    <p>A file can contain several <c>BEGIN/END</c> blocks. Text lines between
+    blocks are ignored. Attributes, if present, are ignored except
+    for <c>Proc-Type</c> and <c>DEK-Info</c>, which are used when <c>DER</c> 
+    data is encrypted.</p>
 
     <section>
-      <title>DSA private key</title>
+      <title>DSA Private Key</title>
+      <p>A DSA private key can look as follows:</p>
+      <note><p>File handling is not done by the <c>public_key</c> application.</p></note>
       
-      <p>Note file handling is not done by the public_key application. </p>
       <code>1> {ok, PemBin} = file:read_file("dsa.pem").
 {ok,&lt;&lt;"-----BEGIN DSA PRIVATE KEY-----\nMIIBuw"...&gt;&gt;}</code>
       
-      <p>This PEM file only has one entry, a private DSA key.</p>
+      <p>The following PEM file has only one entry, a private DSA key:</p>
       <code>2> [DSAEntry] =  public_key:pem_decode(PemBin).
 [{'DSAPrivateKey',&lt;&lt;48,130,1,187,2,1,0,2,129,129,0,183,
                     179,230,217,37,99,144,157,21,228,204,
@@ -80,21 +81,20 @@
     </section>
 
     <section>
-      <title>RSA private key encrypted with a password.</title>
+      <title>RSA Private Key with Password</title>
+      <p>An RSA private key encrypted with a password can look as follows:</p>
       
       <code>1> {ok, PemBin} = file:read_file("rsa.pem").
 {ok,&lt;&lt;"Bag Attribut"...&gt;&gt;}</code>
 
-    <p>This PEM file only has one entry a private RSA key.</p>
+    <p>The following PEM file has only one entry, a private RSA key:</p>
     <code>2>[RSAEntry] = public_key:pem_decode(PemBin).
 [{'RSAPrivateKey',&lt;&lt;224,108,117,203,152,40,15,77,128,126,
                     221,195,154,249,85,208,202,251,109,
                     119,120,57,29,89,19,9,...&gt;&gt;,
-                  {"DES-EDE3-CBC",&lt;&lt;"kÙeø¼pµL"&gt;&gt;}}]
-
-    </code>
+                  {"DES-EDE3-CBC",&lt;&lt;"kÙeø¼pµL"&gt;&gt;}}]</code>
 
-    <p>In this example the password is "abcd1234".</p>
+    <p>In this following example, the password is <c>"abcd1234"</c>:</p>
     <code>3> Key = public_key:pem_entry_decode(RSAEntry, "abcd1234").
     #'RSAPrivateKey'{version = 'two-prime',
                  modulus = 1112355156729921663373...2737107,
@@ -110,11 +110,12 @@
   
   <section>
     <title>X509 Certificates</title>
+    <p>The following is an example of X509 certificates:</p>
     
       <code>1> {ok, PemBin} = file:read_file("cacerts.pem").
 {ok,&lt;&lt;"-----BEGIN CERTIFICATE-----\nMIIC7jCCAl"...&gt;&gt;}</code>
 
-      <p>This file includes two certificates</p>
+      <p>The following file includes two certificates:</p>
       <code>2> [CertEntry1, CertEntry2] = public_key:pem_decode(PemBin).
 [{'Certificate',&lt;&lt;48,130,2,238,48,130,2,87,160,3,2,1,2,2,
                   9,0,230,145,97,214,191,2,120,150,48,13,
@@ -124,7 +125,7 @@
                   1,48,13,6,9,42,134,72,134,247,...&gt;&gt;>,
                 not_encrypted}]</code>
       
-      <p>Certificates may of course be decoded as usual ... </p>
+      <p>Certificates can be decoded as usual:</p>
       <code>2> Cert = public_key:pem_entry_decode(CertEntry1).
 #'Certificate'{
     tbsCertificate =
@@ -212,22 +213,23 @@
     signature =
         {0,
          &lt;&lt;163,186,7,163,216,152,63,47,154,234,139,73,154,96,120,
-           165,2,52,196,195,109,167,192,...&gt;&gt;}}
-</code>
-
-      <p> Parts of certificates can be decoded with
-      public_key:der_decode/2 using that parts ASN.1 type.
-      Although application specific certificate
-      extension requires application specific ASN.1 decode/encode-functions.
-      Example, the first value of the rdnSequence above is of ASN.1 type
-      'X520CommonName'. ({2,5,4,3} = ?id-at-commonName)</p>
+           165,2,52,196,195,109,167,192,...&gt;&gt;}}</code>
+
+      <p>Parts of certificates can be decoded with
+      <c>public_key:der_decode/2</c>, using the ASN.1 type of that part.
+      However, an application-specific certificate extension requires 
+      application-specific ASN.1 decode/encode-functions.
+      In the recent example, the first value of <c>rdnSequence</c> is 
+      of ASN.1 type <c>'X520CommonName'. ({2,5,4,3} = ?id-at-commonName)</c>:</p>
       
       <code>public_key:der_decode('X520CommonName', &lt;&lt;19,8,101,114,108,97,110,103,67,65&gt;&gt;).
 {printableString,"erlangCA"}</code>
 
-      <p>... but certificates can also be decode using the pkix_decode_cert/2 that
-      can customize and recursively decode standard parts of a certificate.</p>
+      <p>However, certificates can also be decoded using <c>pkix_decode_cert/2</c>, 
+      which can customize and recursively decode standard parts of a certificate:</p>
+
       <code>3>{_, DerCert, _} = CertEntry1.</code>
+
       <code>4> public_key:pkix_decode_cert(DerCert, otp).
 #'OTPCertificate'{
     tbsCertificate =
@@ -316,28 +318,26 @@
     signature =
         {0,
          &lt;&lt;163,186,7,163,216,152,63,47,154,234,139,73,154,96,120,
-           165,2,52,196,195,109,167,192,...&gt;&gt;}}
-</code>
+           165,2,52,196,195,109,167,192,...&gt;&gt;}}</code>
 
-      <p>This call is equivalent to public_key:pem_entry_decode(CertEntry1)</p>
+      <p>This call is equivalent to <c>public_key:pem_entry_decode(CertEntry1)</c>:</p>
       <code>5> public_key:pkix_decode_cert(DerCert, plain).
-#'Certificate'{ ...}
-</code>
+#'Certificate'{ ...}</code>
   </section>
 
   <section>
-    <title>Encoding public key data to PEM format</title>
+    <title>Encoding Public-Key Data to PEM Format</title>
 
-    <p>If you have public key data and and want to create a PEM file
-    you can do that by calling the functions
-    public_key:pem_entry_encode/2 and pem_encode/1 and then saving the
-    result to a file. For example assume you have PubKey =
-    'RSAPublicKey'{} then you can create a PEM-"RSA PUBLIC KEY" file
-    (ASN.1 type 'RSAPublicKey') or a PEM-"PUBLIC KEY" file
-    ('SubjectPublicKeyInfo' ASN.1 type).</p>
+    <p>If you have public-key data and want to create a PEM file
+    this can be done by calling functions
+    <c>public_key:pem_entry_encode/2</c> and <c>pem_encode/1</c> and 
+    saving the result to a file. For example, assume that you have 
+    <c>PubKey = 'RSAPublicKey'{}</c>. Then you can create a PEM-"RSA PUBLIC KEY" 
+    file (ASN.1 type <c>'RSAPublicKey'</c>) or a PEM-"PUBLIC KEY" file
+    (<c>'SubjectPublicKeyInfo'</c> ASN.1 type).</p>
 
-    <p> The second element of the PEM-entry will be the ASN.1 DER encoded
-    key data.</p>
+    <p>The second element of the PEM-entry is the ASN.1 <c>DER</c> encoded
+    key data:</p>
 
     <code>1> PemEntry = public_key:pem_entry_encode('RSAPublicKey', RSAPubKey).
 {'RSAPublicKey', &lt;&lt;48,72,...&gt;&gt;, not_encrypted}
@@ -348,7 +348,7 @@
 3> file:write_file("rsa_pub_key.pem", PemBin).
 ok</code>
 
-    <p> or </p>
+    <p>or:</p>
 
     <code>1> PemEntry = public_key:pem_entry_encode('SubjectPublicKeyInfo', RSAPubKey).
 {'SubjectPublicKeyInfo', &lt;&lt;48,92...&gt;&gt;, not_encrypted}
@@ -363,96 +363,106 @@ ok</code>
 </section>
 
 <section>
-      <title>RSA public key cryptography </title>
-       <p> Suppose you have PrivateKey = #'RSAPrivateKey{}' and the
-       plaintext Msg = binary() and the corresponding public key
-       PublicKey = #'RSAPublicKey'{} then you can do the following.
-       Note that you normally will only do one of the encrypt or
-       decrypt operations and the peer will do the other.
-       </p>
-
-       <p>Encrypt with the private key </p>
+      <title>RSA Public-Key Cryptography</title>
+       <p>Suppose you have the followwing private key and a corresponding public key:</p>
+       <list type="bulleted">
+	 <item><c>PrivateKey = #'RSAPrivateKey{}'</c> and 
+	 the plaintext <c>Msg = binary()</c></item>
+	 <item><c>PublicKey = #'RSAPublicKey'{}</c>
+	 </item>
+       </list>
+       <p>Then you can proceed as follows:</p>
+
+       <p>Encrypt with the private key:</p>
        <code>RsaEncrypted = public_key:encrypt_private(Msg, PrivateKey),
 Msg = public_key:decrypt_public(RsaEncrypted, PublicKey),</code>
 
-       <p>Encrypt with the public key </p>
+       <p>Encrypt with the public key:</p>
        <code>RsaEncrypted = public_key:encrypt_public(Msg, PublicKey),
 Msg = public_key:decrypt_private(RsaEncrypted, PrivateKey),</code>
+
+      <note><p>You normally do only one of the encrypt or decrypt operations, 
+      and the peer does the other.</p></note>
+
   </section>
 
   <section>
-    <title>Digital signatures</title>
+    <title>Digital Signatures</title>
 
-    <p> Suppose you have PrivateKey = #'RSAPrivateKey{}'or
-    #'DSAPrivateKey'{} and the plaintext Msg = binary() and the
-    corresponding public key PublicKey = #'RSAPublicKey'{} or
-    {integer(), #'DssParams'{}} then you can do the following.  Note
-    that you normally will only do one of the sign or verify operations
-    and the peer will do the other. </p>
+    <p>Suppose you have the following private key and a corresponding public key:</p>
+    
+    <list type="bulleted">
+       <item><c>PrivateKey = #'RSAPrivateKey{}'</c> or
+       <c>#'DSAPrivateKey'{}</c> and the plaintext <c>Msg = binary()</c></item>
+       <item><c>PublicKey = #'RSAPublicKey'{}</c> or
+       <c>{integer(), #'DssParams'{}}</c></item>
+     </list>
+     <p>Then you can proceed as follows:</p>
 
     <code>Signature = public_key:sign(Msg, sha, PrivateKey),
 true = public_key:verify(Msg, sha, Signature, PublicKey),</code>
 
-    <p>It might be appropriate to calculate the message digest before
-    calling sign or verify and then you can use the none as second
-    argument.</p>
+    <note><p>You normally do only one of the sign or verify operations,
+    and the peer does the other.</p></note>
+
+    <p>It can be appropriate to calculate the message digest before
+    calling <c>sign</c> or <c>verify</c>, and then use <c>none</c> as 
+    second argument:</p>
 
     <code>Digest = crypto:sha(Msg),
 Signature = public_key:sign(Digest, none, PrivateKey),
-true = public_key:verify(Digest, none, Signature, PublicKey),
-    </code>
+true = public_key:verify(Digest, none, Signature, PublicKey),</code>
     
   </section>
   
   <section>
-    <title>SSH files</title>
+    <title>SSH Files</title>
     
     <p>SSH typically uses PEM files for private keys but has its
-    own file format for storing public keys. The erlang public_key
-    application can be used to parse the content of SSH public key files.</p>
+    own file format for storing public keys. The <c>public_key</c>
+    application can be used to parse the content of SSH public-key files.</p>
 
     <section>
-   <title> RFC 4716 SSH public key files </title>
+   <title>RFC 4716 SSH Public-Key Files</title>
 
     <p>RFC 4716 SSH files looks confusingly like PEM files,
-       but there are some differences.</p>
+       but there are some differences:</p>
       <code>1> {ok, SshBin} = file:read_file("ssh2_rsa_pub").
 {ok, &lt;&lt;"---- BEGIN SSH2 PUBLIC KEY ----\nAAAA"...&gt;&gt;}</code>
 
-    <p>This is equivalent to calling public_key:ssh_decode(SshBin, rfc4716_public_key).
+    <p>This is equivalent to calling <c>public_key:ssh_decode(SshBin, rfc4716_public_key)</c>:
     </p>
       <code>2> public_key:ssh_decode(SshBin, public_key).
 [{#'RSAPublicKey'{modulus = 794430685...91663,
-                  publicExponent = 35}, []}]
-</code>
+                  publicExponent = 35}, []}]</code>
 
  </section>
 
  <section>
-   <title> Openssh public key format </title>
+   <title>OpenSSH Public-Key Format</title>
+   <p>OpenSSH public-key format looks as follows:</p>
       <code>1> {ok, SshBin} = file:read_file("openssh_dsa_pub").
 {ok,&lt;&lt;"ssh-dss AAAAB3Nza"...&gt;&gt;}</code>
 
-    <p>This is equivalent to calling public_key:ssh_decode(SshBin, openssh_public_key).
+    <p>This is equivalent to calling <c>public_key:ssh_decode(SshBin, openssh_public_key)</c>:
     </p>
     <code>2>  public_key:ssh_decode(SshBin, public_key).
 [{{15642692...694280725,
    #'Dss-Parms'{p = 17291273936...696123221,
                 q = 1255626590179665817295475654204371833735706001853,
                 g = 10454211196...480338645}},
-  [{comment,"dhopson@VMUbuntu-DSH"}]}]
-</code>
+  [{comment,"dhopson@VMUbuntu-DSH"}]}]</code>
  </section>
 
  <section>
-   <title> Known hosts - openssh format</title>
-
+   <title>Known Hosts - OpenSSH Format</title>
+   <p>Known hosts - OpenSSH format looks as follows:</p>
       <code>1> {ok, SshBin} = file:read_file("known_hosts").
 {ok,&lt;&lt;"hostname.domain.com,192.168.0.1 ssh-rsa AAAAB...&gt;&gt;}</code>
 
-    <p>Returns a list of public keys and their related attributes
-    each pair of key and attributes corresponds to one entry in
-    the known hosts file.</p>
+    <p>Returns a list of public keys and their related attributes.
+    Each pair of key and attribute corresponds to one entry in
+    the known hosts file:</p>
     
     <code>2>  public_key:ssh_decode(SshBin, known_hosts).
 [{#'RSAPublicKey'{modulus = 1498979460408...72721699,
@@ -461,19 +471,19 @@ true = public_key:verify(Digest, none, Signature, PublicKey),
  {#'RSAPublicKey'{modulus = 14989794604088...2721699,
                   publicExponent = 35},
   [{comment,"[email protected]"},
-   {hostnames,["|1|BWO5qDxk/cFH0wa05JLdHn+j6xQ=|rXQvIxh5cDD3C43k5DPDamawVNA="]}]}]
-</code>
+   {hostnames,["|1|BWO5qDxk/cFH0wa05JLdHn+j6xQ=|rXQvIxh5cDD3C43k5DPDamawVNA="]}]}]</code>
   </section>
 
   <section>
-    <title> Authorized keys - openssh format</title>
+    <title>Authorized Keys - OpenSSH Format</title>
+    <p>Authorized keys - OpenSSH format looks as follows:</p>
 
     <code>1> {ok, SshBin} = file:read_file("auth_keys").
 {ok, &lt;&lt;"command=\"dump /home\",no-pty,no-port-forwarding ssh-rsa AAA...&gt;&gt;}</code>
 
-    <p>Returns a list of public keys and their related attributes
-    each pair of key and attributes corresponds to one entry in
-    the authorized key file.</p>
+    <p>Returns a list of public keys and their related attributes.
+    Each pair of key and attribute corresponds to one entry in
+    the authorized key file:</p>
 
     <code>2> public_key:ssh_decode(SshBin, auth_keys).
 [{#'RSAPublicKey'{modulus = 794430685...691663,
@@ -485,16 +495,15 @@ true = public_key:verify(Digest, none, Signature, PublicKey),
    #'Dss-Parms'{p = 17291273936185...763696123221,
                 q = 1255626590179665817295475654204371833735706001853,
                 g = 10454211195705...60511039590076780999046480338645}},
-  [{comment,"dhopson@VMUbuntu-DSH"}]}]
-</code>
+  [{comment,"dhopson@VMUbuntu-DSH"}]}]</code>
     </section>
 
     <section>
-      <title> Creating an SSH file from public key data </title>
+      <title>Creating an SSH File from Public-Key Data</title>
 
       <p>If you got a public key <c>PubKey</c> and a related list of
       attributes <c>Attributes</c> as returned
-      by ssh_decode/2 you can create a new ssh file for example</p>
+      by <c>ssh_decode/2</c>, you can create a new SSH file, for example:</p>
       <code>N> SshBin = public_key:ssh_encode([{PubKey, Attributes}], openssh_public_key),
 &lt;&lt;"ssh-rsa "...&gt;&gt;
 N+1> file:write_file("id_rsa.pub", SshBin).