Merge branch 'lukas/erl_docgen/add-internal-docs'

OTP-15715

* lukas/erl_docgen/add-internal-docs:
  cerl_clauses: Fix broken link
  Fix minor typos
  Add CountingInstructions to the internal documentation
  GarbageCollection.md: Fix links to references
  emd2exml: Remove paragraphs around image tags
  emd2exml: Clean emphasis markers in link texts
  emd2exml: Allow short names of anchors for internal links
  Include figures
  erts: Fix more internal docs xmllint
  compiler: Add internal docs section
  erl_docgen: Add new internal docs chapter to docs

2 files changed, 74 insertions, 13 deletions

diff --git a/make/emd2exml.in b/make/emd2exml.in
index 24837696f4..ec3de0a7f8 100755
--- a/make/emd2exml.in
+++ b/make/emd2exml.in
@@ -462,7 +462,7 @@ url([C|Cs], Bool, Acc) ->
     url(Cs, Bool, [C|Acc]).
 
 link_or_image(Str, Type) ->
-    case link_or_image_text(Str, "") of
+    case link_or_image_text(Str) of
  	no -> no;
 	{Text, Cont1} ->
 	    case link_or_image_data(Cont1, none, Type, "", "") of
@@ -471,9 +471,14 @@ link_or_image(Str, Type) ->
  		    {["<url href=\"", text(Url), "\">", text(Text), "</url>"],
 		     Cont2};
  		{seealso, SeeAlso, _Title, Cont2} ->
-		    {["<seealso marker=\"", text(SeeAlso), "\">",
-		      text(Text), "</seealso>"],
-		     Cont2};
+                    case internal_seealso(SeeAlso) of
+                        no ->
+                            {["<seealso marker=\"", text(SeeAlso), "\">",
+                              text(Text), "</seealso>"],
+                             Cont2};
+                        {yes, SeeAlsoKey} ->
+                            {delayed, link, SeeAlsoKey, text(Text), Cont2}
+                    end;
  		{image, Image, Title, Cont2} ->
  		    {["<image file=\"", text(Image), "\"><icaption>",
 		      text(Title), "</icaption></image>"],
@@ -485,16 +490,41 @@ link_or_image(Str, Type) ->
  	    end
      end.
 
+internal_seealso("#" ++ Marker) ->
+    {yes, {internal, Marker}};
+internal_seealso(_) ->
+    no.
+
+link_or_image_text(Cs0) ->
+    {Prefix, Cs2} = case Cs0 of
+                        "__" ++ Cs1 -> {"__", Cs1};
+                        "_"  ++ Cs1 -> {"_", Cs1};
+                        "**" ++ Cs1 -> {"**", Cs1};
+                        "*"  ++ Cs1 -> {"*", Cs1};
+                        Cs1 -> {"", Cs1}
+                    end,
+    {Text0, Cs} = link_or_image_text(Cs2, []),
+    Text = case lists:prefix(Prefix, Text0) of
+               false ->
+                   lists:reverse(Text0, Prefix);
+               true ->
+                   lists:reverse(lists:nthtail(length(Prefix), Text0))
+            end,
+    case Text of
+        [] ->
+            no;
+        [_|_] ->
+            {Text, Cs}
+    end.
+
 link_or_image_text([$\\,C|Cs], Acc) ->
     link_or_image_text(Cs, [C|Acc]);
-link_or_image_text([$]|_Cs], "") ->
-    no;
 link_or_image_text([$]|Cs], Acc) ->
-    {lists:reverse(Acc), Cs};
+    {Acc, Cs};
 link_or_image_text([C|Cs], Acc) ->
     link_or_image_text(Cs, [C|Acc]);
 link_or_image_text([], _Acc) ->
-    no.
+    {[], []}.
 
 link_or_image_data([C|Cs], none, link, "", "") when C == $ ; C == $\t ->
     link_or_image_data(Cs, none, link, "", "");
@@ -615,8 +645,10 @@ put_title(S, 1, Title) ->
 put_title(#state{mlist = MList0,
 		 toc = TOC} = S0, H, Title) ->
     TitleStr = text(Title),
-    MList1 = [mk_lvl_marker(Title) | MList0],
+    TitleMarker = mk_lvl_marker(Title),
+    MList1 = [TitleMarker | MList0],
     Marker = mk_marker(MList1),
+    MarkerKey = string:lowercase(TitleMarker),
     S1 = chk_h1(H, 
 		S0#state{toc = [TOC,
 				lists:duplicate(H,"  "),
@@ -624,13 +656,15 @@ put_title(#state{mlist = MList0,
 				"<seealso marker=\"#",Marker,"\">",
 				TitleStr,"</seealso>",nl()],
 			 h = H,
-			 mlist = MList1}),
+			 mlist = MList1
+                        }),
     S2 = put_chars(S1, ["<marker id=\"", Marker, "\"/>",nl()]),
+    S3 = write_delayed(S2, {internal, MarkerKey}, {"#" ++ Marker, ""}),
     {STag, ETag} = case H > ?MAX_HEADING of
 		       true -> {"<p><strong>", "</strong></p>"};
 		       false -> {"<title>", "</title>"}
 		   end,
-    put_chars(S2, [STag, TitleStr, ETag, nl()]).
+    put_chars(S3, [STag, TitleStr, ETag, nl()]).
 
 setext_heading(H, #state{line = Line, h = OldH} = S0) ->
     S1 = sections(H, OldH, S0),
@@ -1204,7 +1238,7 @@ put_delayed(#state{out = Out} = S, Key, Data) ->
     S#state{out = [{delayed, Key, Data} | Out]}.
 
 put_chars(#state{out = Out} = S, Chars) ->
-    S#state{out = [[Chars] | Out]}.
+    S#state{out = [Chars | Out]}.
 
 put_line(#state{out = Out} = S, String) ->
     S#state{out = [[String, nl()] | Out]}.
@@ -1219,6 +1253,15 @@ complete_output(S, [], Out) ->
 		   Out]};
 complete_output(S, [{delayed, IX}|Rest], Out) ->
     complete_output(S, Rest, [read_delayed(S, IX)|Out]);
+complete_output(S, [{delayed, {internal, Key0}, {link, Text, _Line}}|Rest], Out) ->
+    Key = [C || C <- Key0, C =/= $_],
+    case read_delayed(S, {internal, Key}) of
+        {value, {Url, _}} ->
+            complete_output(S, Rest, [mk_link(Text, Url)|Out]);
+        none ->
+            Url = "#" ++ Key0,
+            complete_output(S, Rest, [mk_link(Text, Url)|Out])
+    end;
 complete_output(S, [{delayed, Key, {link, Text, Line}}|Rest], Out) ->
     case read_delayed(S, Key) of
 	{value, {Url, _Title}} ->
@@ -1235,9 +1278,27 @@ complete_output(S, [{delayed, Key, {image, _Text, Line}}|Rest], Out) ->
 	    {File, _} = S#state.ifile,
 	    error(File, Line, "Image definition name `~ts' not found~n", [Key])
     end;
+complete_output(S, [["</p>","\n"]=ParaStart,
+                    Contents,
+                    ["<p>","\n"]=ParaEnd|Rest], Out) ->
+    case is_image_tag(Contents) of
+        true ->
+            %% Get rid of the paragraph around an image tag. It would mess up
+            %% figure numbering.
+            complete_output(S, Rest, [Contents|Out]);
+        false ->
+            complete_output(S, [Contents,ParaEnd|Rest], [ParaStart|Out])
+    end;
 complete_output(S, [Next|Rest], Out) ->
     complete_output(S, Rest, [Next|Out]).
 
+is_image_tag("<image" ++ _) ->
+    true;
+is_image_tag([[_|_]=H | _]) ->
+    is_image_tag(H);
+is_image_tag(_) ->
+    false.
+
 write_output(_OFD, []) ->
     ok;
 write_output(OFD, [O|Os]) ->
diff --git a/make/otp_release_targets.mk b/make/otp_release_targets.mk
index d1fbf6c58f..615bf1adb7 100644
--- a/make/otp_release_targets.mk
+++ b/make/otp_release_targets.mk
@@ -156,7 +156,7 @@ endif
 
 
 ## These are the patterns of file names that xmllint cannot currently parse
-XI_INC_FILES:=%user_man.xml %usersguide.xml %refman.xml %ref_man.xml %part.xml %book.xml
+XI_INC_FILES:=%user_man.xml %usersguide.xml %refman.xml %ref_man.xml %part.xml %book.xml %internal.xml
 
 ## These are the files that we should run the xmllint on
 LINT_XI_INC_FILES := $(filter-out $(XI_INC_FILES), $(ALL_XI_INC_FILES))