From ac568ebbe879e74e8d3a1d052f0f2fc3117051f0 Mon Sep 17 00:00:00 2001
From: Sverker Eriksson <sverker@erlang.org>
Date: Fri, 28 Jun 2019 17:55:14 +0200
Subject: doc: Add links between dist flags and external tags (DTD updated)

DTD updated to allow seealso-marker inside taglist.
---
 erts/doc/src/erl_dist_protocol.xml | 32 ++++++++++++++++++++++++++------
 erts/doc/src/erl_ext_dist.xml      | 33 ++++++++++++++++++---------------
 lib/erl_docgen/priv/dtd/common.dtd |  2 +-
 3 files changed, 45 insertions(+), 22 deletions(-)

diff --git a/erts/doc/src/erl_dist_protocol.xml b/erts/doc/src/erl_dist_protocol.xml
index 5dfe34cfae..0c1100d394 100644
--- a/erts/doc/src/erl_dist_protocol.xml
+++ b/erts/doc/src/erl_dist_protocol.xml
@@ -811,7 +811,8 @@ DiB == gen_digest(ChA, ICA)?
         </item>
         <tag><c>-define(DFLAG_NEW_FUN_TAGS,16#80).</c></tag>
         <item>
-          <p>The node understand new fun tags.</p>
+	  <p>The node understands the <seealso marker="erl_ext_dist#NEW_FUN_EXT">
+	    <c>NEW_FUN_EXT</c></seealso> tag.</p>
         </item>
         <tag><c>-define(DFLAG_EXTENDED_PIDS_PORTS,16#100).</c></tag>
         <item>
@@ -820,13 +821,18 @@ DiB == gen_digest(ChA, ICA)?
         </item>
         <tag><c>-define(DFLAG_EXPORT_PTR_TAG,16#200).</c></tag>
         <item>
+	  <p>The node understands the <seealso marker="erl_ext_dist#EXPORT_EXT">
+	    <c>EXPORT_EXT</c></seealso> tag.</p>
         </item>
         <tag><c>-define(DFLAG_BIT_BINARIES,16#400).</c></tag>
         <item>
+	  <p>The node understands the <seealso marker="erl_ext_dist#BIT_BINARY_EXT">
+	    <c>BIT_BINARY_EXT</c></seealso> tag.</p>
         </item>
         <tag><c>-define(DFLAG_NEW_FLOATS,16#800).</c></tag>
         <item>
-          <p>The node understands new float format.</p>
+	  <p>The node understands the <seealso marker="erl_ext_dist#NEW_FLOAT_EXT">
+	    <c>NEW_FLOAT_EXT</c></seealso> tag.</p>
         </item>
         <tag><c>-define(DFLAG_UNICODE_IO,16#1000).</c></tag>
         <item>
@@ -835,21 +841,34 @@ DiB == gen_digest(ChA, ICA)?
         <item>
           <p>The node implements atom cache in distribution header.</p>
         </item>
+	<marker id="DFLAG_SMALL_ATOM_TAGS"/>
         <tag><c>-define(DFLAG_SMALL_ATOM_TAGS, 16#4000).</c></tag>
         <item>
-          <p>The node understand the <c>SMALL_ATOM_EXT</c> tag.</p>
+          <p>The node understands the <seealso marker="erl_ext_dist#SMALL_ATOM_EXT">
+	  <c>SMALL_ATOM_EXT</c></seealso> tag.</p>
         </item>
+	<marker id="DFLAG_UTF8_ATOMS"/>
         <tag><c>-define(DFLAG_UTF8_ATOMS, 16#10000).</c></tag>
         <item>
-          <p>The node understand UTF-8 encoded atoms.</p>
+          <p>The node understands UTF-8 atoms encoded with
+	    <seealso marker="erl_ext_dist#ATOM_UTF8_EXT">
+	    <c>ATOM_UTF8_EXT</c></seealso> and
+	    <seealso marker="erl_ext_dist#SMALL_ATOM_UTF8_EXT">
+	    <c>SMALL ATOM_UTF8_EXT</c></seealso>.</p>
         </item>
         <tag><c>-define(DFLAG_MAP_TAG, 16#20000).</c></tag>
         <item>
-          <p>The node understand the map tag.</p>
+          <p>The node understands the map tag
+	  <seealso marker="erl_ext_dist#MAP_EXT"><c>MAP_EXT</c></seealso>.</p>
         </item>
+	<marker id="DFLAG_BIG_CREATION"/>
         <tag><c>-define(DFLAG_BIG_CREATION, 16#40000).</c></tag>
         <item>
-          <p>The node understand big node creation.</p>
+          <p>The node understands big node creation tags
+	  <seealso marker="erl_ext_dist#NEW_PID_EXT"><c>NEW_PID_EXT</c></seealso>,
+	  <seealso marker="erl_ext_dist#NEW_PORT_EXT"><c>NEW_PORT_EXT</c></seealso> and
+	  <seealso marker="erl_ext_dist#NEWER_REFERENCE_EXT"><c>NEWER_REFERENCE_EXT</c></seealso>.
+	  </p>
         </item>
         <tag><c>-define(DFLAG_SEND_SENDER, 16#80000).</c></tag>
         <item>
@@ -873,6 +892,7 @@ DiB == gen_digest(ChA, ICA)?
             <seealso marker="#control_message">control message</seealso>s
             instead of the non-PAYLOAD variants.</p>
         </item>
+	<marker id="DFLAG_FRAGMENTS"/>
         <tag><c>-define(DFLAG_FRAGMENTS, 16#800000).</c></tag>
         <item>
           <p>Use <seealso marker="erl_ext_dist#fragments">fragmented</seealso>
diff --git a/erts/doc/src/erl_ext_dist.xml b/erts/doc/src/erl_ext_dist.xml
index 5d6605b69a..1b736813af 100644
--- a/erts/doc/src/erl_ext_dist.xml
+++ b/erts/doc/src/erl_ext_dist.xml
@@ -264,7 +264,7 @@
         consists of. Length is a 2 byte big-endian integer
         if flag <c>LongAtoms</c> has been set, otherwise a 1 byte
         integer. When distribution flag
-        <seealso marker="erl_dist_protocol#dflags">
+        <seealso marker="erl_dist_protocol#DFLAG_UTF8_ATOMS">
         <c>DFLAG_UTF8_ATOMS</c></seealso>
         has been exchanged between both nodes in the
         <seealso marker="erl_dist_protocol#distribution_handshake">
@@ -316,8 +316,8 @@
       </p>
       <p>Fragmented distribution messages are only used if the receiving node
       signals that it supports them via the
-      <seealso marker="erl_dist_protocol#dflags">DFLAG_FRAGMENTS</seealso> distribution
-      flag.</p>
+      <seealso marker="erl_dist_protocol#DFLAG_FRAGMENTS">DFLAG_FRAGMENTS</seealso>
+      distribution flag.</p>
       <p>A process must complete the sending of a fragmented message before it
       can start sending any other message on the same distribution channel.</p>
 
@@ -640,8 +640,9 @@
 	<p><c>NEW_PORT_EXT</c> was introduced in OTP 19, but only to be decoded
 	  and echoed back. Not encoded for local ports.
 	</p>
-	<p>In OTP 23 distribution flag <seealso	marker="erl_dist_protocol#dflags">
-	  <c>DFLAG_BIG_CREATION</c></seealso> became mandatory. All ports are now
+	<p>In OTP 23 distribution flag
+	  <seealso marker="erl_dist_protocol#DFLAG_BIG_CREATION"><c>DFLAG_BIG_CREATION</c></seealso>
+	  became mandatory. All ports are now
 	  encoded using <c>NEW_PORT_EXT</c>, even external ports received as <seealso
 	  marker="#PORT_EXT"><c>PORT_EXT</c></seealso> from older nodes.
 	</p>
@@ -724,10 +725,11 @@
 	<p><c>NEW_PID_EXT</c> was introduced in OTP 19, but only to be decoded
 	  and echoed back. Not encoded for local processes.
 	</p>
-	<p>In OTP 23 distribution flag <seealso	marker="erl_dist_protocol#dflags">
-	  <c>DFLAG_BIG_CREATION</c></seealso> became mandatory. All pids are now
-	  encoded using <c>NEW_PID_EXT</c>, even external pids received as <seealso
-	  marker="#PID_EXT"><c>PID_EXT</c></seealso> from older nodes.
+	<p>In OTP 23 distribution flag
+	  <seealso marker="erl_dist_protocol#DFLAG_BIG_CREATION"><c>DFLAG_BIG_CREATION</c></seealso>
+	  became mandatory. All pids are now encoded using <c>NEW_PID_EXT</c>,
+	  even external pids received as
+	  <seealso marker="#PID_EXT"><c>PID_EXT</c></seealso> from older nodes.
 	</p>
     </section>
 
@@ -1054,11 +1056,12 @@
 	<p><c>NEWER_REFERENCE_EXT</c> was introduced in OTP 19, but only to be decoded
 	  and echoed back. Not encoded for local references.
 	</p>
-	<p>In OTP 23 distribution flag <seealso	marker="erl_dist_protocol#dflags">
-	  <c>DFLAG_BIG_CREATION</c></seealso> became mandatory. All references are now
-	  encoded using <c>NEWER_REFERENCE_EXT</c>, even external references
-	  received as <seealso marker="#NEW_REFERENCE_EXT"><c>NEW_REFERENCE_EXT</c>
-	  </seealso> from older nodes.
+	<p>In OTP 23 distribution flag
+	  <seealso marker="erl_dist_protocol#DFLAG_BIG_CREATION"><c>DFLAG_BIG_CREATION</c></seealso>
+	  became mandatory. All references are now encoded using
+	  <c>NEWER_REFERENCE_EXT</c>, even external references received as
+	  <seealso marker="#NEW_REFERENCE_EXT"><c>NEW_REFERENCE_EXT</c></seealso>
+	  from older nodes.
 	</p>
     </section>
 
@@ -1415,7 +1418,7 @@
 	<p>
 	  <c>SMALL_ATOM_EXT</c> was introduced in ERTS 5.7.2 and
 	  require an exchange of distribution flag
-	  <seealso marker="erl_dist_protocol#dflags">
+	  <seealso marker="erl_dist_protocol#DFLAG_SMALL_ATOM_TAGS">
 	  <c>DFLAG_SMALL_ATOM_TAGS</c></seealso> in the
 	  <seealso marker="erl_dist_protocol#distribution_handshake">
 	  distribution handshake</seealso>.
diff --git a/lib/erl_docgen/priv/dtd/common.dtd b/lib/erl_docgen/priv/dtd/common.dtd
index 0ccd52068b..0feb09eac2 100644
--- a/lib/erl_docgen/priv/dtd/common.dtd
+++ b/lib/erl_docgen/priv/dtd/common.dtd
@@ -67,7 +67,7 @@
 
 <!ELEMENT list                (item+) >
 <!ATTLIST list                 type (ordered|bulleted) "bulleted" >
-<!ELEMENT taglist             (tag,item+)+ >
+<!ELEMENT taglist             (marker*,tag,item+)+ >
 <!ELEMENT tag                 (#PCDATA|c|i|em|br|seealso|url|marker|anno)* >
 <!ELEMENT item                (%inline;|%block;|warning|note|dont|do|quote)* >
 
-- 
cgit v1.2.3