diff options
author | Björn Gustavsson <[email protected]> | 2019-04-05 10:26:39 +0200 |
---|---|---|
committer | Björn Gustavsson <[email protected]> | 2019-04-05 10:26:39 +0200 |
commit | c0989dcede812c47290f1c61d39e46caa0edf547 (patch) | |
tree | cfdb9482774f27363dfc542e84c646c0053e8f72 /make | |
parent | 041de278a8b8639d5fc975218c39226be3bf1e16 (diff) | |
parent | 07b9eacff8c65df4ac00a21010c748217c908eb9 (diff) | |
download | otp-c0989dcede812c47290f1c61d39e46caa0edf547.tar.gz otp-c0989dcede812c47290f1c61d39e46caa0edf547.tar.bz2 otp-c0989dcede812c47290f1c61d39e46caa0edf547.zip |
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
Diffstat (limited to 'make')
-rwxr-xr-x | make/emd2exml.in | 85 | ||||
-rw-r--r-- | make/otp_release_targets.mk | 2 |
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)) |