Merge branch 'ia/ssl/docs'

* ia/ssl/docs:
  ssl: Add missing tag
  ssl: Put back marker
  ssl: Fix links
  ssl: Align with application naming rules
  ssl: Keep information in one place only
  ssl: Correct makefile

9 files changed, 60 insertions, 61 deletions

diff --git a/lib/ssl/doc/src/Makefile b/lib/ssl/doc/src/Makefile
index cfbf98f6e3..143756bd39 100644
--- a/lib/ssl/doc/src/Makefile
+++ b/lib/ssl/doc/src/Makefile
@@ -37,7 +37,7 @@ RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN)
 # Target Specs
 # ----------------------------------------------------
 XML_APPLICATION_FILES = refman.xml
-XML_REF3_FILES = ssl.xml ssl_crl_cache.xml ssl_crl_cache.xml ssl_session_cache_api.xml 
+XML_REF3_FILES = ssl.xml ssl_crl_cache.xml ssl_crl_cache_api.xml ssl_session_cache_api.xml 
 XML_REF6_FILES = ssl_app.xml
 
 XML_PART_FILES = release_notes.xml usersguide.xml
diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml
index d070cb4019..cdf6870c25 100644
--- a/lib/ssl/doc/src/ssl.xml
+++ b/lib/ssl/doc/src/ssl.xml
@@ -37,8 +37,7 @@
     <title>SSL</title>
 
     <list type="bulleted">
-      <item><c>ssl</c> requires the <c>crypto</c> and <c>public_key</c> 
-      applications.</item>
+      <item>For application dependencies see <seealso marker="ssl_app"> ssl(6)</seealso> </item>
       <item>Supported SSL/TLS-versions are SSL-3.0, TLS-1.0,
       TLS-1.1, and TLS-1.2.</item>
       <item>For security reasons SSL-2.0 is not supported.</item>
@@ -46,7 +45,7 @@
       but can be configured.</item>
       <item>Ephemeral Diffie-Hellman cipher suites are supported,
       but not Diffie Hellman Certificates cipher suites.</item>
-      <item>Elliptic Curve cipher suites are supported if the <c>crypto</c> 
+      <item>Elliptic Curve cipher suites are supported if the Crypto 
       application supports it and named curves are used.
       </item>
       <item>Export cipher suites are not supported as the
@@ -64,7 +63,7 @@
   
   <section>
     <title>DATA TYPES</title>
-    <p>The following data types are used in the functions for <c>ssl</c>:</p>
+    <p>The following data types are used in the functions for SSL:</p>
 
     <taglist>
 
@@ -82,9 +81,9 @@
       <p>For valid options, see the
       <seealso marker="kernel:inet">inet(3)</seealso> and
       <seealso marker="kernel:gen_tcp">gen_tcp(3)</seealso> manual pages
-      in <c>kernel</c>.</p></item>
+      in Kernel.</p></item>
 
-      <tag><c>ssloption()</c></tag>
+      <tag><marker id="type-ssloption"></marker><c>ssloption()</c></tag>
       <item><p><c>= {verify, verify_type()}</c></p>
       <p><c>| {verify_fun, {fun(), term()}}</c></p>
       <p><c>| {fail_if_no_peer_cert, boolean()} {depth, integer()}</c></p>
@@ -262,7 +261,7 @@ atom()}} |
 	</code>
 
 	<p>The verification fun is called during the X509-path
-	validation when an error or an extension unknown to the <c>ssl</c>
+	validation when an error or an extension unknown to the SSL
 	application is encountered. It is also called
 	when a certificate is considered valid by the path validation
 	to allow access to each certificate in the path to the user
@@ -339,7 +338,7 @@ marker="public_key:public_key#pkix_path_validation-3">public_key:pkix_path_valid
       <tag><c>{crl_check, boolean() | peer | best_effort }</c></tag>
       <item>
 	Perform CRL (Certificate Revocation List) verification
-	<seealso marker="public_key:public_key#pkix_crl_validate-3">
+	<seealso marker="public_key:public_key#pkix_crls_validate-3">
 	(public_key:pkix_crls_validate/3)</seealso> on all the certificates during the path validation
 	<seealso
 	    marker="public_key:public_key#pkix_path_validation-3">(public_key:pkix_path_validation/3)
@@ -376,14 +375,15 @@ marker="public_key:public_key#pkix_path_validation-3">public_key:pkix_path_valid
       <tag><c>{partial_chain, fun(Chain::[DerCert]) -> {trusted_ca, DerCert} |
       unknown_ca }</c></tag>
       <item><p>Claim an intermediate CA in the chain as trusted. TLS then
-      performs <c>public_key:pkix_path_validation/3</c>
+      performs <seealso
+      marker="public_key:public_key#pkix_path_validation-3">public_key:pkix_path_validation/3</seealso>
       with the selected CA as trusted anchor and the rest of the chain.</p></item>
 
       <tag><c>{versions, [protocol()]}</c></tag>
       <item><p>TLS protocol versions supported by started clients and servers.
       This option overrides the application environment option
       <c>protocol_version</c>. If the environment option is not set, it defaults
-      to all versions, except SSL-3.0, supported by the <c>ssl</c> application.
+      to all versions, except SSL-3.0, supported by the SSL application.
       See also <seealso marker="ssl:ssl_app">ssl(6).</seealso></p></item>
 
       <tag><c>{hibernate_after, integer()|undefined}</c></tag>
@@ -1000,21 +1000,21 @@ fun(srp, Username :: string(), UserState :: term()) ->
     <func>
       <name>start() -> </name>
       <name>start(Type) -> ok | {error, Reason}</name>
-      <fsummary>Starts the <c>ssl</c>application.</fsummary>
+      <fsummary>Starts the SSL application.</fsummary>
       <type>
         <v>Type = permanent | transient | temporary</v>
       </type>
       <desc>
-        <p>Starts the <c>ssl</c> application. Default type
+        <p>Starts the SSL application. Default type
           is <c>temporary</c>.</p>
       </desc>
     </func>
 
     <func>
       <name>stop() -> ok </name>
-      <fsummary>Stops the <c>ssl</c> application.</fsummary>
+      <fsummary>Stops the SSL application.</fsummary>
       <desc>
-        <p>Stops the <c>ssl</c> application.</p>
+        <p>Stops the SSL application.</p>
       </desc>
     </func>
 
@@ -1056,16 +1056,16 @@ fun(srp, Username :: string(), UserState :: term()) ->
     <func>
       <name>versions() -> [versions_info()]</name>
       <fsummary>Returns version information relevant for the
-	<c>ssl</c> application.</fsummary>
+	SSL application.</fsummary>
       <type>
 	<v>versions_info() = {app_vsn, string()} | {supported | available, [protocol()] </v>
       </type>
       <desc>
-	<p>Returns version information relevant for the <c>ssl</c>
+	<p>Returns version information relevant for the SSL
 	application.</p>
 	<taglist>
 	  <tag><c>app_vsn</c></tag>
-	  <item>The application version of the <c>ssl</c> application.</item>
+	  <item>The application version of the SSL application.</item>
 
 	  <tag><c>supported</c></tag>
 	  <item>TLS/SSL versions supported by default.
@@ -1078,8 +1078,8 @@ fun(srp, Username :: string(), UserState :: term()) ->
 	  </seealso>.</item>
   
 	  <tag><c>available</c></tag>
-	  <item>All TLS/SSL versions supported by the <c>ssl</c> application.
-	  TLS 1.2 requires sufficient support from the <c>crypto</c>
+	  <item>All TLS/SSL versions supported by the SSL application.
+	  TLS 1.2 requires sufficient support from the Crypto
 	  application.</item>
 	</taglist>
       </desc>
@@ -1095,4 +1095,3 @@ fun(srp, Username :: string(), UserState :: term()) ->
   </section>
 
 </erlref>
-
diff --git a/lib/ssl/doc/src/ssl_app.xml b/lib/ssl/doc/src/ssl_app.xml
index 43c69ba377..f17f5cb9fe 100644
--- a/lib/ssl/doc/src/ssl_app.xml
+++ b/lib/ssl/doc/src/ssl_app.xml
@@ -35,21 +35,21 @@
   <description></description>
   <section>
     <title>DEPENDENCIES</title>
-    <p>The <c>ssl</c> application uses the <c>public_key</c> and
-    <c>crypto</c> application to handle public keys and encryption, hence
-    these applications must be loaded for the <c>ssl</c> application to work. 
+    <p>The SSL application uses the <c>public_key</c> and
+    Crypto application to handle public keys and encryption, hence
+    these applications must be loaded for the SSL application to work. 
     In an embedded environment this means they must be started with
-    <c>application:start/[1,2]</c> before the <c>ssl</c> application is 
+    <c>application:start/[1,2]</c> before the SSL application is 
     started.</p>
   </section>
 
   <section>
     <title>CONFIGURATION</title>
     <p>The application environment configuration parameters in this section 
-    are defined for the <c>ssl</c> application. For more information 
+    are defined for the SSL application. For more information 
     about configuration parameters, see the 
     <seealso marker="kernel:application">application(3)</seealso>
-    manual page in <c>kernel</c>.</p>
+    manual page in Kernel.</p>
 
     <p>The environment parameters can be set on the command line,
     for example:</p>
@@ -60,7 +60,7 @@
       <tag><c><![CDATA[protocol_version =  <seealso marker="kernel:error_logger">ssl:protocol()</seealso> <optional>]]></c>.</tag>
       <item><p>Protocol supported by started clients and
       servers. If this option is not set, it defaults to all
-      protocols currently supported by the <c>ssl</c> application.
+      protocols currently supported by the SSL application.
       This option can be overridden by the version option
       to <c>ssl:connect/[2,3]</c> and <c>ssl:listen/2</c>.</p></item>
 
@@ -91,7 +91,7 @@
 
   <section>
     <title>ERROR LOGGER AND EVENT HANDLERS</title>
-    <p>The <c>ssl</c> applications uses the default <seealso marker="kernel:error_logger">OTP error logger</seealso> to log unexpected errors and TLS alerts. The logging of TLS alerts may be turned off with the <c>log_alert</c> option. </p>
+    <p>The SSL application uses the default <seealso marker="kernel:error_logger">OTP error logger</seealso> to log unexpected errors and TLS alerts. The logging of TLS alerts may be turned off with the <c>log_alert</c> option. </p>
   </section>
 
   <section>
diff --git a/lib/ssl/doc/src/ssl_crl_cache.xml b/lib/ssl/doc/src/ssl_crl_cache.xml
index 62bf2ea7b7..83b03375b1 100644
--- a/lib/ssl/doc/src/ssl_crl_cache.xml
+++ b/lib/ssl/doc/src/ssl_crl_cache.xml
@@ -29,7 +29,7 @@
     <p>
       Implements an internal CRL (Certificate Revocation List) cache.
       In addition to implementing the <seealso
-      marker="ssl_cache_crl_api"> ssl_cache_crl_api</seealso> behaviour
+      marker="ssl_crl_cache_api"> ssl_crl_cache_api</seealso> behaviour
       the following functions are available.
     </p>
   </description>
@@ -44,7 +44,7 @@
 	  <v> Reason = term()</v>
 	</type>
 	<desc>
-	  Delete CRLs from the ssl applications local cache.
+	  <p>Delete CRLs from the ssl applications local cache. </p>
 	</desc>
       </func>     
       <func>
@@ -58,7 +58,7 @@
 	  <v> Reason = term()</v>
 	</type>
 	<desc>
-	Insert CRLs into the ssl applications local cache.
+	 <p>Insert CRLs into the ssl applications local cache. </p>
 	</desc>
       </func>
     </funcs>
diff --git a/lib/ssl/doc/src/ssl_crl_cache_api.xml b/lib/ssl/doc/src/ssl_crl_cache_api.xml
index 557b7814b8..1d9353a2cc 100644
--- a/lib/ssl/doc/src/ssl_crl_cache_api.xml
+++ b/lib/ssl/doc/src/ssl_crl_cache_api.xml
@@ -70,7 +70,7 @@
       </type>
       <desc>
 	<p> <c>fun fresh_crl/2 </c> will be used as input option <c>update_crl</c> to
-	<seealso marker="public_key#pkix_path_validation-3">public_key:pkix_crls_validate/3 </seealso> </p>
+	<seealso marker="public_key:public_key#pkix_crls_validate-3">public_key:pkix_crls_validate/3 </seealso> </p>
       </desc>
     </func>
     
diff --git a/lib/ssl/doc/src/ssl_distribution.xml b/lib/ssl/doc/src/ssl_distribution.xml
index c9f7b1b27f..effb304938 100644
--- a/lib/ssl/doc/src/ssl_distribution.xml
+++ b/lib/ssl/doc/src/ssl_distribution.xml
@@ -38,11 +38,11 @@
       connection-based protocol as bearer. However, a module that 
       implements the protocol-specific parts of the connection setup is 
       needed. The default distribution module is <c>inet_tcp_dist</c> 
-      in the <c>kernel</c> application. When starting an
+      in the Kernel application. When starting an
       Erlang node distributed, <c>net_kernel</c> uses this module to
       set up listen ports and connections.</p>
 
-      <p>In the <c>ssl</c> application, an exra distribution
+      <p>In the SSL application, an exra distribution
       module, <c>inet_tls_dist</c>, can be used as an
       alternative. All distribution connections will use SSL and
       all participating Erlang nodes in a distributed system must use
@@ -57,7 +57,7 @@
 
       <list type="bulleted">
       <item><em>Step 1:</em> Build boot scripts including the
-      <c>ssl</c> application.</item>
+      SSL application.</item>
       <item><em>Step 2:</em> Specify the distribution module for 
       <c>net_kernel</c>.</item>
       <item><em>Step 3:</em> Specify the security options and other 
@@ -74,8 +74,8 @@
       see the <c>sasl</c> documentation. This is only an example of
       what can be done.</p>
 
-      <p>The simplest boot script possible includes only the <c>kernel</c> 
-      and <c>stdlib</c> applications. Such a script is located in the 
+      <p>The simplest boot script possible includes only the Kernel 
+      and STDLIB applications. Such a script is located in the 
       <c>bin</c> directory of the Erlang distribution. The source for the 
       script is found under the Erlang installation top directory under
       <c><![CDATA[releases/<OTP version>/start_clean.rel]]></c>.</p>
@@ -84,12 +84,12 @@
       <list type="bulleted">
 	<item><p>Copy that script to another location (and preferably another 
       name).</p></item>
-        <item><p>Add the applications <c>crypto</c>, <c>public_key</c>, and 
-	<c>ssl</c> with their current version numbers after the 
-	<c>stdlib</c>application.</p></item>
+        <item><p>Add the applications Crypto, Public Key, and 
+	SSL with their current version numbers after the 
+	STDLIB application.</p></item>
       </list>
 
-    <p>The following shows an example <c>.rel</c> file with <c>ssl</c> 
+    <p>The following shows an example <c>.rel</c> file with SSL 
     added:</p>
     <code type="none">
       {release, {"OTP  APN 181 01","R15A"}, {erts, "5.9"},
@@ -132,27 +132,27 @@ Eshell V5.0  (abort with ^G)
 1> whereis(ssl_manager).
 <0.41.0>    ]]></code>
 
-    <p>The <c>whereis</c> function-call verifies that the <c>ssl</c> 
+    <p>The <c>whereis</c> function-call verifies that the SSL 
       application is started.</p>
 
       <p>As an alternative to building a bootscript, you can explicitly
-      add the path to the <c>ssl</c> <c>ebin</c> directory on the command
+      add the path to the SSL <c>ebin</c> directory on the command
       line. This is done with command-line option <c>-pa</c>. This
-      works as the <c>ssl</c> application does not need to be started for the
-      distribution to come up, as a clone of the <c>ssl</c> application is
-      hooked into the <c>kernel</c> application. So, as long as the
-      <c>ssl</c> application code can be reached, the distribution starts. 
+      works as the SSL application does not need to be started for the
+      distribution to come up, as a clone of the SSL application is
+      hooked into the Kernel application. So, as long as the
+      SSL application code can be reached, the distribution starts. 
       The <c>-pa</c> method is only recommended for testing purposes.</p>
 
-      <note><p>The clone of the <c>ssl</c> application must
+      <note><p>The clone of the SSL application must
       enable the use of the SSL code in such an early bootstage as
       needed to set up the distribution. However, this makes it
-      impossible to soft upgrade the <c>ssl</c> application.</p></note>
+      impossible to soft upgrade the SSL application.</p></note>
   </section>
 
   <section>
     <title>Specifying Distribution Module for net_kernel</title>
-    <p>The distribution module for <c>ssl</c> is named <c>inet_tls_dist</c>
+    <p>The distribution module for SSL is named <c>inet_tls_dist</c>
       and is specified on the command line with option <c>-proto_dist</c>.
       The argument to <c>-proto_dist</c> is to be the module
       name without suffix <c>_dist</c>. So, this distribution
@@ -172,7 +172,7 @@ Eshell V5.0  (abort with ^G)
 (ssl_test@myhost)1>     </code>
 
     <p>However, a node started in this way refuses to talk
-      to other nodes, as no <c>ssl</c> parameters are supplied
+      to other nodes, as no SSL parameters are supplied
       (see the next section).</p>
   </section>
 
diff --git a/lib/ssl/doc/src/ssl_protocol.xml b/lib/ssl/doc/src/ssl_protocol.xml
index 20f53c98e1..cc49515066 100644
--- a/lib/ssl/doc/src/ssl_protocol.xml
+++ b/lib/ssl/doc/src/ssl_protocol.xml
@@ -32,19 +32,19 @@
     <file>ssl_protocol.xml</file>
   </header>
   
-  <p>The Erlang <c>ssl</c> application implements the SSL/TLS protocol
+  <p>The Erlang SSL application implements the SSL/TLS protocol
   for the currently supported versions,  see the
   <seealso marker="ssl">ssl(3)</seealso> manual page.
   </p>
 
-  <p>By default <c>ssl</c> is run over the TCP/IP protocol even
+  <p>By default SSL/TLS is run over the TCP/IP protocol even
   though you can plug in any other reliable transport protocol
   with the same Application Programming Interface (API) as the
-  <c>gen_tcp</c> module in <c>kernel</c>.</p>
+  <c>gen_tcp</c> module in Kernel.</p>
   
   <p>If a client and a server wants to use an upgrade mechanism, such as
   defined by RFC 2817, to upgrade a regular TCP/IP connection to an SSL
-  connection, this is supported by the Erlang <c>ssl</c> API. This can be 
+  connection, this is supported by the Erlang SSL application API. This can be 
   useful for, for example, supporting HTTP and HTTPS on the same port and
   implementing virtual hosting.
   </p>
@@ -143,7 +143,7 @@
      connections. Sessions are used to avoid the expensive negotiation
      of new security parameters for each connection."</p>
 
-     <p>Session data is by default kept by the <c>ssl</c> application in a
+     <p>Session data is by default kept by the SSL application in a
      memory storage, hence session data is lost at application
      restart or takeover. Users can define their own callback module
      to handle session data storage if persistent data storage is
diff --git a/lib/ssl/doc/src/ssl_session_cache_api.xml b/lib/ssl/doc/src/ssl_session_cache_api.xml
index 9cd16c5f58..c89d3874a1 100644
--- a/lib/ssl/doc/src/ssl_session_cache_api.xml
+++ b/lib/ssl/doc/src/ssl_session_cache_api.xml
@@ -108,8 +108,8 @@
 	API functions. Is called by the cache handling processes
 	<c>init</c> function, hence putting the same requirements on it
 	as a normal process <c>init</c> function. This function is
-	called twice when starting the <c>ssl</c> application, once with
-	the role client and once with the role server, as the <c>ssl</c>
+	called twice when starting the SSL application, once with
+	the role client and once with the role server, as the SSL
 	application must be prepared to take on both roles.
 	</p>
       </desc>
diff --git a/lib/ssl/doc/src/using_ssl.xml b/lib/ssl/doc/src/using_ssl.xml
index 01b7970fb6..dbbc1aa9d3 100644
--- a/lib/ssl/doc/src/using_ssl.xml
+++ b/lib/ssl/doc/src/using_ssl.xml
@@ -32,10 +32,10 @@
     <file>using_ssl.xml</file>
   </header>
   <p>To see relevant version information for ssl, call
-  <seealso marker="ssl:versions-0"><c>ssl:versions/0</c></seealso>
+  <seealso marker="ssl:ssl#versions-0"><c>ssl:versions/0</c></seealso>
   .</p>
     
-  <p>To see all supported cipher suites, call  <seealso marker="ssl:cipher_suites-1"><c>ssl:cipher_suites(all)</c> </seealso>. 
+  <p>To see all supported cipher suites, call  <seealso marker="ssl:ssl#cipher_suites-1"><c>ssl:cipher_suites(all)</c> </seealso>. 
   The available cipher suites for a connection depend on your certificate. 
   Specific cipher suites that you want your connection to use can also be 
   specified. Default is to use the strongest available.</p>