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

* anders/diameter/doc/OTP-10471:
  Add missing diameter_codec(3) content
  Add content to diameter_codec(3) and diameter_make(3)
  Add reference pages diameter_codec(3) and diameter_make(3)

1 files changed, 47 insertions, 16 deletions

diff --git a/lib/diameter/doc/src/diameter_dict.xml b/lib/diameter/doc/src/diameter_dict.xml
index 4a6cccc276..eb6cf9ba86 100644
--- a/lib/diameter/doc/src/diameter_dict.xml
+++ b/lib/diameter/doc/src/diameter_dict.xml
@@ -1,5 +1,11 @@
 <?xml version="1.0" encoding="latin1" ?>
 <!DOCTYPE erlref SYSTEM "fileref.dtd" [
+  <!ENTITY format
+           '<seealso marker="#FILE_FORMAT">FILE FORMAT</seealso>'>
+  <!ENTITY records
+           '<seealso marker="#MESSAGE_RECORDS">MESSAGE RECORDS</seealso>'>
+  <!ENTITY types
+           '<seealso marker="#DATA_TYPES">DATA TYPES</seealso>'>
   <!ENTITY % also SYSTEM "seealso.ent" >
   <!ENTITY % here SYSTEM "seehere.ent" >
   %also;
@@ -45,29 +51,28 @@ under the License.
 
 <description>
 <p>
-A diameter service as configured with &mod_start_service;
+A diameter service, as configured with &mod_start_service;,
 specifies one or more supported Diameter applications.
 Each Diameter application specifies a dictionary module that knows how
 to encode and decode its messages and AVPs.
 The dictionary module is in turn generated from a file that defines
 these messages and AVPs.
-The format of such a file is defined in
-<seealso marker="#FILE_FORMAT">FILE FORMAT</seealso> below.
+The format of such a file is defined in &format; below.
 Users add support for their specific applications by creating
 dictionary files, compiling them to Erlang modules using
-<seealso marker="diameterc">diameterc</seealso> and configuring the
+either &man_compile; or &man_make; and configuring the
 resulting dictionaries modules on a service.</p>
 
 <p>
-The codec generation also results in a hrl file that defines records
-for the messages and grouped AVPs defined for the application, these
-records being what a user of the diameter application sends and receives.
-(Modulo other available formats as discussed in &man_app;.)
+Dictionary module generation also results in a hrl file that defines
+records for the messages and Grouped AVPs defined by the
+dictionary, these records being what a user of the diameter
+application sends and receives, modulo other possible formats as
+discussed in &man_app;.
 These records and the underlying Erlang data types corresponding to
-Diameter data formats are discussed in <seealso
-marker="#MESSAGE_RECORDS">MESSAGE RECORDS</seealso> and <seealso
-marker="#DATA_TYPES">DATA TYPES</seealso> respectively.
-The generated hrl also contains defines for the possible values of
+Diameter data formats are discussed in &records; and &types;
+respectively.
+The generated hrl also contains macro definitions for the possible values of
 AVPs of type Enumerated.</p>
 
 <p>
@@ -111,6 +116,8 @@ The order in which sections are specified is unimportant.</p>
 
 <taglist>
 
+<marker id="id"/>
+
 <tag><c>@id Number</c></tag>
 <item>
 <p>
@@ -134,6 +141,8 @@ Example:</p>
 
 </item>
 
+<marker id="name"/>
+
 <tag><c>@name Mod</c></tag>
 <item>
 <p>
@@ -155,6 +164,8 @@ Example:</p>
 
 </item>
 
+<marker id="prefix"/>
+
 <tag><c>@prefix Name</c></tag>
 <item>
 <p>
@@ -178,6 +189,8 @@ Example:</p>
 
 </item>
 
+<marker id="vendor"/>
+
 <tag><c>@vendor Number Name</c></tag>
 <item>
 <p>
@@ -198,6 +211,8 @@ Example:</p>
 
 </item>
 
+<marker id="avp_vendor_id"/>
+
 <tag><c>@avp_vendor_id Number</c></tag>
 <item>
 <p>
@@ -218,6 +233,8 @@ Region-Set
 
 </item>
 
+<marker id="inherits"/>
+
 <tag><c>@inherits Mod</c></tag>
 <item>
 <p>
@@ -253,6 +270,8 @@ Example:</p>
 
 </item>
 
+<marker id="avp_types"/>
+
 <tag><c>@avp_types</c></tag>
 <item>
 <p>
@@ -263,7 +282,7 @@ The section consists of definitions of the form</p>
 
 <p>
 where Code is the integer AVP code, Type identifies an AVP Data Format
-as defined in <seealso marker="#DATA_TYPES">DATA TYPES</seealso> below,
+as defined in section &types; below,
 and Flags is a string of V, M and P characters indicating the flags to be
 set on an outgoing AVP or a single <c>'-'</c> (minus) character if
 none are to be set.</p>
@@ -287,6 +306,8 @@ to conform to the current draft standard.</p>
 
 </item>
 
+<marker id="custom_types"/>
+
 <tag><c>@custom_types Mod</c></tag>
 <item>
 <p>
@@ -308,6 +329,8 @@ Framed-IP-Address
 </pre>
 </item>
 
+<marker id="codecs"/>
+
 <tag><c>@codecs Mod</c></tag>
 <item>
 <p>
@@ -325,6 +348,8 @@ Framed-IP-Address
 </pre>
 </item>
 
+<marker id="messages"/>
+
 <tag><c>@messages</c></tag>
 <item>
 <p>
@@ -370,6 +395,8 @@ RTA ::= &lt; Diameter Header: 287, PXY >
 
 </item>
 
+<marker id="grouped"/>
+
 <tag><c>@grouped</c></tag>
 <item>
 <p>
@@ -395,6 +422,8 @@ Specifying a Vendor-Id in the definition of a grouped AVP is
 equivalent to specifying it with <c>@avp_vendor_id</c>.</p>
 </item>
 
+<marker id="enum"/>
+
 <tag><c>@enum Name</c></tag>
 <item>
 <p>
@@ -421,6 +450,8 @@ REMOVE_SIP_SERVER        3
 </pre>
 </item>
 
+<marker id="end"/>
+
 <tag><c>@end</c></tag>
 <item>
 <p>
@@ -447,8 +478,8 @@ The hrl generated from a dictionary specification defines records for the
 messages and grouped AVPs defined in <c>@messages</c> and
 <c>@grouped</c> sections.
 For each message or grouped AVP definition, a record is defined whose
-name is the message or AVP name prefixed with any dictionary prefix
-defined with <c>@prefix</c> and whose fields are the names of the AVPs
+name is the message or AVP name, prefixed with any dictionary prefix
+defined with <c>@prefix</c>, and whose fields are the names of the AVPs
 contained in the message or grouped AVP in the order specified in the
 definition in question.
 For example, the grouped AVP</p>
@@ -640,7 +671,7 @@ Values of these types are not currently parsed by diameter.</p>
 <title>SEE ALSO</title>
 
 <p>
-&man_compile;, &man_main;, &man_app;</p>
+&man_compile;, &man_main;, &man_app;, &man_codec;, &man_make;</p>
 
 </section>