File 5433-stdlib-Update-shell_docs-normalize-to-always-have-bl.patch of Package erlang
From a8f592d105f4ef9d2b240cecc49381c0b4566731 Mon Sep 17 00:00:00 2001
From: Lukas Larsson <lukas@erlang.org>
Date: Wed, 6 Dec 2023 13:28:47 +0100
Subject: [PATCH 3/4] stdlib: Update shell_docs:normalize to always have blocks
at top level
This change makes ExDoc rendering look nicer for edoc content.
---
lib/edoc/src/edoc_layout_chunks.erl | 4 +++-
lib/edoc/test/eep48_SUITE.erl | 19 +++++++++++++++----
lib/stdlib/src/shell_docs.erl | 23 ++++++++++++++++++++++-
3 files changed, 40 insertions(+), 6 deletions(-)
diff --git a/lib/edoc/src/edoc_layout_chunks.erl b/lib/edoc/src/edoc_layout_chunks.erl
index fd397d12be..69e377ca9b 100644
--- a/lib/edoc/src/edoc_layout_chunks.erl
+++ b/lib/edoc/src/edoc_layout_chunks.erl
@@ -479,7 +479,9 @@ xpath_to_text(XPath, Doc, Opts) ->
[] -> <<>>;
[#xmlAttribute{} = Attr] ->
{_ , Value} = format_attribute(Attr),
- hd(shell_docs:normalize([Value]));
+ case shell_docs:normalize([Value]) of
+ [{p,[],[Normal]}] -> Normal
+ end;
[#xmlElement{}] = Elements ->
xmerl_to_binary(Elements, Opts);
[_|_] ->
diff --git a/lib/edoc/test/eep48_SUITE.erl b/lib/edoc/test/eep48_SUITE.erl
index e56e88e93e..1db3fb9522 100644
--- a/lib/edoc/test/eep48_SUITE.erl
+++ b/lib/edoc/test/eep48_SUITE.erl
@@ -516,10 +516,21 @@ lookup_entry(Kind, Function, Arity, Docs) ->
get_metadata({_, _, _, _, Metadata}) -> Metadata.
get_doc_link(KNA, Docs) ->
- [Link] = [ Node || {a, _, _} = Node <- get_doc(KNA, Docs) ],
- {a, Attrs, _} = Link,
- <<"https://erlang.org/doc/link/", ShortRel/bytes>> = fetch(rel, Attrs),
- {ShortRel, fetch(href, Attrs)}.
+ D = get_doc(KNA, Docs),
+ case lists:foldl(fun F({a, _, _} = E, Acc) ->
+ [E | Acc];
+ F({_E, _, Es}, Acc) when is_list(Es) ->
+ lists:foldl(F, Acc, Es);
+ F(_, Acc) ->
+ Acc
+ end, [], D) of
+ [{a, Attrs, _}] ->
+ <<"https://erlang.org/doc/link/", ShortRel/bytes>> = fetch(rel, Attrs),
+ {ShortRel, fetch(href, Attrs)};
+ _Else ->
+ ct:log("Could not find link in ~p",[D]),
+ ct:fail("Did not find link in docs")
+ end.
get_anno(Kind, Name, Arity, Docs) ->
{_, Anno, _, _, _} = lookup_entry(Kind, Name, Arity, Docs),
diff --git a/lib/stdlib/src/shell_docs.erl b/lib/stdlib/src/shell_docs.erl
index 1962c97b07..1b51bc1a62 100644
--- a/lib/stdlib/src/shell_docs.erl
+++ b/lib/stdlib/src/shell_docs.erl
@@ -195,7 +195,8 @@ validate_docs([],_) ->
NormalizedDocs :: chunk_elements().
normalize(Docs) ->
Trimmed = normalize_trim(Docs,true),
- normalize_space(Trimmed).
+ Space = normalize_space(Trimmed),
+ normalize_paragraph(Space).
normalize_trim(Bin,true) when is_binary(Bin) ->
%% Remove any whitespace (except \n) before or after a newline
@@ -341,6 +342,26 @@ trim_last([{Elem,Attr,Content} = Tag|T],What) ->
trim_last([],_What) ->
{[],false}.
+%% Any non-block elements at top level are wrapped in a p so that tools
+%% don't have to deal with that.
+normalize_paragraph([{Tag,_,_} = Block | T]) when ?IS_BLOCK(Tag) ->
+ [Block | normalize_paragraph(T)];
+normalize_paragraph([{_,_,[]} = NoContent | T]) ->
+ %% If an inline tag has no content we don't wrap it in a <p>. This is
+ %% aimed at fixing <a id=""/> tags at top-level.
+ [NoContent | normalize_paragraph(T)];
+normalize_paragraph([]) ->
+ [];
+normalize_paragraph(Elems) ->
+ case lists:splitwith(
+ fun(E) ->
+ is_binary(E) orelse
+ (?IS_INLINE(element(1, E)) andalso element(3, E) =/= [])
+ end, Elems) of
+ {NotP, P} ->
+ [{p,[],NotP} | normalize_paragraph(P)]
+ end.
+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% API function for dealing with the function documentation
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
--
2.35.3
