Merge branch 'anders/diameter/doc/OTP-10568' into maint

* anders/diameter/doc/OTP-10568:
  Update doc for RFC 6733
  Add copies of RFC's 6733 and 6737

lib/diameter/doc/src/diameter.xml

@@ -56,7 +56,7 @@ under the License.
 <p>
 This module provides the interface with which a user can
 implement a Diameter node that sends and receives messages using the
-Diameter protocol as defined in RFC 3588.</p>
+Diameter protocol as defined in &the_rfc;.</p>
 
 <p>
 Basic usage consists of creating a representation of a
@@ -73,7 +73,7 @@ Beware the difference between <em>diameter</em> (not capitalised) and
 <em>Diameter</em> (capitalised).
 The former refers to the Erlang application named diameter whose main
 api is defined here, the latter to Diameter protocol in the sense of
-RFC 3588.</p>
+&the_rfc;.</p>
 
 <p>
 The diameter application must be started before calling most functions
@@ -97,7 +97,7 @@ in this module.</p>
 <tag><c>UTF8String()</c></tag>
 <item>
 <p>
-Types corresponding to RFC 3588 AVP Data Formats.
+Types corresponding to &the_rfc; AVP Data Formats.
 Defined in &dict_data_types;.</p>
 
 <marker id="application_alias"/>
@@ -318,7 +318,7 @@ returns an address list.</p>
 Origin-State-Id is optional but will be included in outgoing messages
 sent by diameter itself: CER/CEA, DWR/DWA and DPR/DPA.
 Setting a value of <c>0</c> (zero) is equivalent to not setting a
-value as documented in RFC 3588.
+value as documented in &the_rfc;.
 The function &origin_state_id;
 can be used as to retrieve a value that is computed when the diameter
 application is started.</p>
@@ -753,7 +753,7 @@ as follows.</p>
 (H bsl N) bor (Id band ((1 bsl N) - 1))
 </pre>
 <p>
-Note that RFC 3588 requires that End-to-End identifiers remain unique
+Note that &the_rfc; requires that End-to-End identifiers remain unique
 for a period of at least 4 minutes and that this and the call rate
 places a lower bound on the appropriate values of <c>N</c>:
 at a rate of <c>R</c> requests per second an <c>N</c>-bit counter
@@ -955,7 +955,7 @@ Tc = &dict_Unsigned32;
 </pre>
 
 <p>
-For a connecting transport, the RFC 3588 Tc timer, in milliseconds.
+For a connecting transport, the &the_rfc; Tc timer, in milliseconds.
 Note that this timer determines the frequency with which a transport
 will attempt to establish a connection with its peer only <em>before</em>
 an initial connection is established: once there is an initial
@@ -1622,7 +1622,7 @@ Return the list of started services.</p>
 Return a value for a Session-Id AVP.</p>
 
 <p>
-The value has the form required by section 8.8 of RFC 3588.
+The value has the form required by section 8.8 of &the_rfc;.
 Ident should be the Origin-Host of the peer from which
 the message containing the returned value will be sent.</p>
 

lib/diameter/doc/src/diameter_app.xml

@@ -558,7 +558,7 @@ where <c>Avps</c> sets the Origin-Host, Origin-Realm, the specified
 Result-Code and (if the request sent one) Session-Id AVP's.</p>
 
 <p>
-Note that RFC 3588 mandates that only answers with a 3xxx series
+Note that &the_rfc; mandates that only answers with a 3xxx series
 Result-Code (protocol errors) may set the E bit.
 Returning a non-3xxx value in a <c>protocol_error</c> tuple
 will cause the request process in question to fail.</p>

lib/diameter/doc/src/diameter_dict.xml

@@ -77,7 +77,7 @@ AVPs of type Enumerated.</p>
 
 <p>
 The diameter application includes three dictionary modules
-corresponding to applications defined in section 2.4 of RFC 3588:
+corresponding to applications defined in section 2.4 of &the_rfc;:
 <c>diameter_gen_base_rfc3588</c> for the Diameter Common Messages
 application with application identifier 0,
 <c>diameter_gen_accounting</c> for the Diameter Base Accounting
@@ -258,7 +258,7 @@ is equivalent to using <c>@avp_vendor_id</c> with a copy of the
 dictionary's definitions but the former makes for easier reuse.</p>
 
 <p>
-All dictionaries should typically inherit RFC3588 AVPs from
+All dictionaries should typically inherit &the_rfc; AVPs from
 <c>diameter_gen_base_rfc3588</c>.</p>
 
 <p>
@@ -299,9 +299,7 @@ Requested-Information  353  Enumerated   V
 
 <warning>
 <p>
-The P flag has been deprecated by the Diameter Maintenance
-and Extensions Working Group of the IETF and should be omitted
-to conform to the current draft standard.</p>
+The P flag has been deprecated by &the_rfc;.</p>
 </warning>
 
 </item>
@@ -355,7 +353,7 @@ Framed-IP-Address
 <p>
 Defines the messages of the application.
 The section content consists of definitions of the form specified in
-section 3.2 of RFC 3588, "Command Code ABNF specification".</p>
+section 3.2 of &the_rfc;, "Command Code Format Specification".</p>
 
 <!-- RFC 4740 RTR/RTA -->
 <pre>
@@ -403,7 +401,7 @@ RTA ::= &lt; Diameter Header: 287, PXY >
 Defines the contents of the AVPs of the application having type
 Grouped.
 The section content consists of definitions of the form specified in
-section 4.4 of RFC 3588, "Grouped AVP Values".</p>
+section 4.4 of &the_rfc;, "Grouped AVP Values".</p>
 
 <p>
 Example:</p>
@@ -507,7 +505,7 @@ type and number of times the AVP can occur.
 In particular, an AVP which is specified as occurring exactly once is
 encoded as a value of the AVP's type while an AVP with any other
 specification is encoded as a list of values of the AVP's type.
-The AVP's type is as specified in the AVP definition, the RFC 3588
+The AVP's type is as specified in the AVP definition, the &the_rfc;
 types being described below.</p>
 
 <marker id="DATA_TYPES"/>
@@ -520,7 +518,7 @@ types being described below.</p>
 
 <p>
 The data formats defined in sections 4.2 ("Basic AVP Data
-Formats") and 4.3 ("Derived AVP Data Formats") of RFC 3588 are encoded
+Formats") and 4.3 ("Derived AVP Data Formats") of &the_rfc; are encoded
 as values of the types defined here.
 Values are passed to &mod_call;
 in a request record when sending a request, returned in a resulting
@@ -595,8 +593,8 @@ where
 
 <p>
 Additionally, values that can be encoded are
-limited by way of their encoding as four octets as required by RFC
-3588 with the required extension from RFC 2030.
+limited by way of their encoding as four octets as required by
+&the_rfc; with the required extension from RFC 2030.
 In particular, only values between <c>{{1968,1,20},{3,14,8}}</c>
 and <c>{{2104,2,26},{9,42,23}}</c> (both inclusive) can be encoded.</p>
 
@@ -640,7 +638,7 @@ where
 On encode, fields port, transport and protocol default to 3868, sctp
 and diameter respectively.
 The grammar of an OctetString-valued DiameterURI() is as specified in
-section 4.3 of RFC 3588.
+section 4.3 of &the_rfc;.
 The record representation is used on decode.</p>
 
 <marker id="Enumerated"/>

lib/diameter/doc/src/diameter_intro.xml

@@ -1,5 +1,8 @@
 <?xml version="1.0" encoding="latin1" ?>
-<!DOCTYPE chapter SYSTEM "chapter.dtd">
+<!DOCTYPE chapter SYSTEM "chapter.dtd" [
+  <!ENTITY % also SYSTEM "seealso.ent">
+  %also;
+]>
 
 <chapter>
 <header>
@@ -35,7 +38,7 @@ under the License.
 
 <p>
 The diameter application is an implementation of the Diameter protocol
-as defined by RFC 3588.
+as defined by &the_rfc;.
 It supports arbitrary Diameter applications by way of a
 <em>dictionary</em> interface that allows messages and AVP's to be
 defined and input into diameter as configuration.
@@ -86,9 +89,9 @@ dictionary module
 that provide encode/decode functionality for outgoing/incoming
 Diameter messages belonging to the application.
 A dictionary module is generated from a <seealso
-marker="diameter_dict">specification file</seealso> using the <seealso
+marker="diameter_dict">dictionary file</seealso> using the <seealso
 marker="diameterc">diameterc</seealso> utility.
-Dictionaries for the RFC 3588 Diameter Common Messages, Base
+Dictionaries for the &the_rfc; Diameter Common Messages, Base
 Accounting and Relay applications are provided with the diameter
 application.</p>
 

lib/diameter/doc/src/diameter_soc.xml

@@ -1,11 +1,15 @@
 <?xml version="1.0" encoding="latin1" ?>
-<!DOCTYPE chapter SYSTEM "chapter.dtd">
+<!DOCTYPE chapter SYSTEM "chapter.dtd" [
+  <!ENTITY % also SYSTEM "seealso.ent" >
+  %also;
+]>
 
 <chapter>
 
 <header>
 <copyright>
 <year>2011</year>
+<year>2012</year>
 <holder>Ericsson AB. All Rights Reserved.</holder>
 </copyright>
 
@@ -41,38 +45,20 @@ Known points of questionable or non-compliance.</p>
 <!-- ===================================================================== -->
 
 <section>
-<title>RFC 3588</title>
+<title>&the_rfc;</title>
 
 <list>
 
 <item>
 <p>
-The End-to-End Security framework (section 2.9) isn't implemented
-since it is largely unspecified.
-The document that was to describe it
-(reference [AAACMS]) was abandoned in an uncompleted state several
-years ago and the current draft RFC deprecates the framework,
-including the P Flag in the AVP header.</p>
-</item>
-
-<item>
-<p>
-There is no TLS support over SCTP.
-RFC 3588 requires that a Diameter server support TLS but in
-practise this seems to mean TLS over SCTP since there are limitations
-with running over SCTP: see RFC 6083 (DTLS over SCTP), which is a
-response to RFC 3436 (TLS over SCTP).
-The current RFC 3588 draft acknowledges this by equating
-TLS with TLS/TCP and DTLS/SCTP but we do not yet support DTLS.</p>
+There is no support for DTLS over SCTP.</p>
 </item>
 
 <item>
 <p>
 There is no explicit support for peer discovery (section 5.2).
 It can possibly be implemented on top of diameter as is but this is
-probably something that diameter should do.
-The current draft deprecates portions of the original RFC's mechanisms
-however.</p>
+probably something that diameter should do.</p>
 </item>
 
 <item>

lib/diameter/doc/src/diameter_tcp.xml

@@ -66,7 +66,7 @@ It can be specified as the value of a <c>transport_module</c> option to
 and implements the behaviour documented in
 &man_transport;.
 TLS security is supported, both as an upgrade following
-capabilities exchange as specified by RFC 3588 and
+capabilities exchange as specified by &the_rfc; and
 at connection establishment as in the current draft standard.</p>
 
 <p>

lib/diameter/doc/src/seealso.ent

@@ -32,6 +32,8 @@ significant.
 
 -->
 
+<!ENTITY the_rfc 'RFC 6733'>
+
 <!-- diameter -->
 
 <!ENTITY mod_add_transport '<seealso marker="diameter#add_transport-2">diameter:add_transport/2</seealso>'>