Marge Bot pushed to branch master at Glasgow Haskell Compiler / GHC Commits: c5e15b8b by Phil de Joux at 2026-02-18T05:07:36-05:00 haddock: use snippets for all list examples - generate snippet output for docs - reduce font size to better fit snippets - Use only directive to guard html snippets - Add latex snippets for lists - - - - - d388bac1 by Phil de Joux at 2026-02-18T05:07:36-05:00 haddock: Place the snippet input and output together - Put the output seemingly inside the example box - - - - - 24 changed files: - utils/haddock/doc/.gitignore - utils/haddock/doc/Makefile - + utils/haddock/doc/_static/haddock-custom.css - utils/haddock/doc/conf.py - utils/haddock/doc/markup.rst - + utils/haddock/doc/snippets/.gitignore - + utils/haddock/doc/snippets/Lists.hs - + utils/haddock/doc/snippets/Makefile - + utils/haddock/doc/snippets/Snippet-List-Bulleted.html - + utils/haddock/doc/snippets/Snippet-List-Bulleted.tex - + utils/haddock/doc/snippets/Snippet-List-Definition.html - + utils/haddock/doc/snippets/Snippet-List-Definition.tex - + utils/haddock/doc/snippets/Snippet-List-Enumerated.html - + utils/haddock/doc/snippets/Snippet-List-Enumerated.tex - + utils/haddock/doc/snippets/Snippet-List-Indentation.html - + utils/haddock/doc/snippets/Snippet-List-Indentation.tex - + utils/haddock/doc/snippets/Snippet-List-Multiline-Item.html - + utils/haddock/doc/snippets/Snippet-List-Multiline-Item.tex - + utils/haddock/doc/snippets/Snippet-List-Nested-Item.html - + utils/haddock/doc/snippets/Snippet-List-Nested-Item.tex - + utils/haddock/doc/snippets/Snippet-List-Not-Newline.html - + utils/haddock/doc/snippets/Snippet-List-Not-Newline.tex - + utils/haddock/doc/snippets/Snippet-List-Not-Separated.html - + utils/haddock/doc/snippets/Snippet-List-Not-Separated.tex Changes: ===================================== utils/haddock/doc/.gitignore ===================================== @@ -1 +1,3 @@ -.build-html \ No newline at end of file +.build-html +.build-latex +!_static ===================================== utils/haddock/doc/Makefile ===================================== @@ -1,8 +1,13 @@ SPHINX_BUILD ?= sphinx-build -all : html +all : html pdf .PHONY : html +.PHONY : pdf html : $(SPHINX_BUILD) -b html . .build-html + +pdf : + $(SPHINX_BUILD) -b latex . .build-latex + cd .build-latex && make ===================================== utils/haddock/doc/_static/haddock-custom.css ===================================== @@ -0,0 +1,19 @@ +.result.admonition { + border: solid 3px #eee; + border-top: none; + background-color: transparent; + padding: 1px 0px 10px 10px; + margin: 0px 0px -20px 0px; + position: relative; + top: -18px; +} + +.result.admonition p.admonition-title{ + position: absolute; + visibility: hidden; +} + +/* Use a small font size for code blocks so that they don't overflow. */ +pre { + font-size: 0.8em; +} ===================================== utils/haddock/doc/conf.py ===================================== @@ -31,6 +31,12 @@ pygments_style = 'tango' htmlhelp_basename = 'Haddockdoc' +html_static_path = ['_static'] + +html_css_files = [ + 'haddock-custom.css', +] + # -- Options for LaTeX output --------------------------------------------- ===================================== utils/haddock/doc/markup.rst ===================================== @@ -1004,99 +1004,162 @@ Itemized and Enumerated Lists A bulleted item is represented by preceding a paragraph with either “``*``” or “``-``”. A sequence of bulleted paragraphs is rendered as an -itemized list in the generated documentation, e.g.: :: +itemized list in the generated documentation, e.g. - -- | This is a bulleted list: - -- - -- * first item - -- - -- * second item +.. literalinclude:: snippets/Lists.hs + :lines: 3-7 + +.. admonition:: Result + :class: result + + .. only:: html + + .. raw:: html + :file: snippets/Snippet-List-Bulleted.html + + .. only:: latex + + .. raw:: latex + :file: snippets/Snippet-List-Bulleted.tex + +.. warning:: + + Separate lists from any preceding markup with at least one blank line + otherwise the list and its items will be rendered with the preceding + content. + +.. literalinclude:: snippets/Lists.hs + :lines: 10-12 + +.. admonition:: Result + :class: result + + .. only:: html + + .. raw:: html + :file: snippets/Snippet-List-Not-Separated.html + + .. only:: latex + + .. raw:: latex + :file: snippets/Snippet-List-Not-Separated.tex An enumerated list is similar, except each paragraph must be preceded by -either “``(n)``” or “``n.``” where n is any integer. e.g. :: +either “``(n)``” or “``n.``” where n is any integer. e.g. - -- | This is an enumerated list: - -- - -- (1) first item - -- - -- 2. second item +.. literalinclude:: snippets/Lists.hs + :lines: 15-19 -Lists of the same type don't have to be separated by a newline: :: +.. admonition:: Result + :class: result - -- | This is an enumerated list: - -- - -- (1) first item - -- 2. second item - -- - -- This is a bulleted list: - -- - -- * first item - -- * second item + .. only:: html -You can have more than one line of content in a list element: :: + .. raw:: html + :file: snippets/Snippet-List-Enumerated.html - -- | - -- * first item - -- and more content for the first item - -- * second item - -- and more content for the second item + .. only:: latex + + .. raw:: latex + :file: snippets/Snippet-List-Enumerated.tex + +Lists of the same type don't have to be separated by a newline: + +.. literalinclude:: snippets/Lists.hs + :lines: 22-30 + +.. admonition:: Result + :class: result + + .. only:: html + + .. raw:: html + :file: snippets/Snippet-List-Not-Newline.html + + .. only:: latex + + .. raw:: latex + :file: snippets/Snippet-List-Not-Newline.tex + +You can have more than one line of content in a list element: + +.. literalinclude:: snippets/Lists.hs + :lines: 33-37 + +.. admonition:: Result + :class: result + + .. only:: html + + .. raw:: html + :file: snippets/Snippet-List-Multiline-Item.html + + .. only:: latex + + .. raw:: latex + :file: snippets/Snippet-List-Multiline-Item.tex You can even nest whole paragraphs inside of list elements. The rules are 4 spaces for each indentation level. You're required to use a -newline before such nested paragraphs: :: - - {-| - * Beginning of list - This belongs to the list above! +newline before such nested paragraphs: - > nested - > bird - > tracks +.. literalinclude:: snippets/Lists.hs + :lines: 40-61 - * Next list - More of the indented list. +.. admonition:: Result + :class: result - * Deeper + .. only:: html - @ - even code blocks work - @ + .. raw:: html + :file: snippets/Snippet-List-Nested-Item.html - * Deeper + .. only:: latex - 1. Even deeper! - 2. No newline separation even in indented lists. - -} + .. raw:: latex + :file: snippets/Snippet-List-Nested-Item.tex The indentation of the first list item is honoured. That is, in the following example the items are on the same level. Before Haddock 2.16.1, the second item would have been nested under the first item -which was unexpected. :: +which was unexpected. - {-| - * foo +.. literalinclude:: snippets/Lists.hs + :lines: 64-68 - * bar - -} +.. admonition:: Result + :class: result + + .. only:: html + + .. raw:: html + :file: snippets/Snippet-List-Indentation.html + + .. only:: latex + + .. raw:: latex + :file: snippets/Snippet-List-Indentation.tex Definition Lists ~~~~~~~~~~~~~~~~ -Definition lists are written as follows: :: +Definition lists are written as follows: - -- | This is a definition list: - -- - -- [@foo@]: The description of @foo@. - -- - -- [@bar@]: The description of @bar@. +.. literalinclude:: snippets/Lists.hs + :lines: 71-75 + +.. admonition:: Result + :class: result + + .. only:: html -To produce output something like this: + .. raw:: html + :file: snippets/Snippet-List-Definition.html -``foo`` - The description of ``foo``. + .. only:: latex -``bar`` - The description of ``bar``. + .. raw:: latex + :file: snippets/Snippet-List-Definition.tex Each paragraph should be preceded by the “definition term” enclosed in square brackets and followed by a colon. Other markup operators may be ===================================== utils/haddock/doc/snippets/.gitignore ===================================== @@ -0,0 +1,12 @@ +*.html +*.tex +haddock-bundle.min.js +haddock.sty +linuwial.css +main.tex +meta.json +quick-jump.css +synopsis.png + +!Snippet*.html +!Snippet*.tex ===================================== utils/haddock/doc/snippets/Lists.hs ===================================== @@ -0,0 +1,76 @@ +module Lists where + +-- | This is a bulleted list: +-- +-- * first item +-- +-- * second item +data Bulleted + +-- | __Missing blank lines__ before a list: +-- * first item +-- * second item +data Before + +-- | This is an, (n) n., enumerated list: +-- +-- (1) first item +-- +-- 2. second item +data Enumerated + +-- | This is an enumerated list, with items not separated by newlines: +-- +-- (1) first item +-- 2. second item +-- +-- This is a bulleted list, with items not separated by newlines: +-- +-- * first item +-- * second item +data NotNewline + +-- | +-- * first item +-- and more content for the first item +-- * second item +-- and more content for the second item +data MultilineItem + +{-| +* Beginning of list +This belongs to the list above! + + > nested + > bird + > tracks + + * Next list + More of the indented list. + + * Deeper + + @ + even code blocks work + @ + + * Deeper + + 1. Even deeper! + 2. No newline separation even in indented lists. +-} +data NestedItem + +{-| + * foo + + * bar +-} +data Indentation + +-- | This is a definition list: +-- +-- [@foo@]: The description of @foo@. +-- +-- [@bar@]: The description of @bar@. +data DefinitionList \ No newline at end of file ===================================== utils/haddock/doc/snippets/Makefile ===================================== @@ -0,0 +1,103 @@ +# \newcommand{\haddockbegindoc}{\hfill\\[1ex]} +HDK_BEGIN := \\\\newcommand{\\haddockbegindoc}{\\hfill\\\\\[1ex]} + +# \newcommand{\haddockverb}{\small} +HDK_VERB := \\\\newcommand{\\haddockverb}{\\small} + +# \newcommand{\haddocktt}[1]{{\small \texttt{#1}}} +HDK_TT := \\\\newcommand{\\haddocktt}[1]{{\\small \\\\texttt{\#1}}} + +all: \ + Snippet-List-Bulleted.html \ + Snippet-List-Bulleted.tex \ + Snippet-List-Not-Separated.html \ + Snippet-List-Not-Separated.tex \ + Snippet-List-Enumerated.html \ + Snippet-List-Enumerated.tex \ + Snippet-List-Not-Newline.html \ + Snippet-List-Not-Newline.tex \ + Snippet-List-Multiline-Item.html \ + Snippet-List-Multiline-Item.tex \ + Snippet-List-Nested-Item.html \ + Snippet-List-Nested-Item.tex \ + Snippet-List-Indentation.html \ + Snippet-List-Indentation.tex \ + Snippet-List-Definition.html \ + Snippet-List-Definition.tex + +clean: + rm -f Lists*.html + +Lists.html: Lists.hs + haddock --html $^ + +Lists.tex: Lists.hs + haddock --latex $^ + +# Using pandoc-3.1.3 +Lists-Pretty.html: Lists.html + pandoc $^ -o $@ + +# Using tex-fmt-0.4.1 +# nix profile install github:wgunderwood/tex-fmt +Lists-Pretty.tex: Lists.tex + cp $^ $@ + tex-fmt $@ + +Snippet-List-Bulleted.html: Lists-Pretty.html + sed -n '48,52p;53q' $^ > $@ + +Snippet-List-Bulleted.tex: Lists-Pretty.tex + echo "$(HDK_BEGIN)" > $@ + sed -n '18,26p;27q' $^ >> $@ + +Snippet-List-Not-Separated.html: Lists-Pretty.html + sed -n '59,60p;61q' $^ > $@ + +Snippet-List-Not-Separated.tex: Lists-Pretty.tex + echo "$(HDK_BEGIN)" > $@ + sed -n '33,36p;37q' $^ >> $@ + +Snippet-List-Enumerated.html: Lists-Pretty.html + sed -n '68,72p;73q' $^ > $@ + +Snippet-List-Enumerated.tex: Lists-Pretty.tex + echo "$(HDK_BEGIN)" > $@ + sed -n '43,51p;52q' $^ >> $@ + +Snippet-List-Not-Newline.html: Lists-Pretty.html + sed -n '80,89p;90q' $^ > $@ + +Snippet-List-Not-Newline.tex: Lists-Pretty.tex + echo "$(HDK_BEGIN)" > $@ + sed -n '58,74p;75q' $^ >> $@ + +Snippet-List-Multiline-Item.html: Lists-Pretty.html + sed -n '97,100p;101q' $^ > $@ + +Snippet-List-Multiline-Item.tex: Lists-Pretty.tex + echo "$(HDK_BEGIN)" > $@ + sed -n '81,90p;91q' $^ >> $@ + +Snippet-List-Nested-Item.html: Lists-Pretty.html + sed -n '108,127p;128q' $^ > $@ + +Snippet-List-Nested-Item.tex: Lists-Pretty.tex + echo "$(HDK_BEGIN)" > $@ + echo "$(HDK_VERB)" >> $@ + sed -n '97,141p;142q' $^ >> $@ + +Snippet-List-Indentation.html: Lists-Pretty.html + sed -n '135,138p;139q' $^ > $@ + +Snippet-List-Indentation.tex: Lists-Pretty.tex + echo "$(HDK_BEGIN)" > $@ + sed -n '148,155p;156q' $^ >> $@ + +Snippet-List-Definition.html: Lists-Pretty.html + sed -n '146,156p;157q' $^ > $@ + +Snippet-List-Definition.tex: Lists-Pretty.tex + echo "$(HDK_BEGIN)" > $@ + echo "$(HDK_TT)" >> $@ + sed -n '162,170p;171q' $^ >> $@ ===================================== utils/haddock/doc/snippets/Snippet-List-Bulleted.html ===================================== @@ -0,0 +1,5 @@ +<p>This is a bulleted list:</p> +<ul> +<li>first item</li> +<li>second item</li> +</ul> ===================================== utils/haddock/doc/snippets/Snippet-List-Bulleted.tex ===================================== @@ -0,0 +1,10 @@ +\newcommand{\haddockbegindoc}{\hfill\\[1ex]} + {\haddockbegindoc + This is a bulleted list:\par + \vbox{ + \begin{itemize} + \item + first item\par + \item + second item\par + \end{itemize}}} ===================================== utils/haddock/doc/snippets/Snippet-List-Definition.html ===================================== @@ -0,0 +1,11 @@ +<p>This is a definition list:</p> +<dl> +<dt><code>foo</code></dt> +<dd> +The description of <code>foo</code>. +</dd> +<dt><code>bar</code></dt> +<dd> +The description of <code>bar</code>. +</dd> +</dl> ===================================== utils/haddock/doc/snippets/Snippet-List-Definition.tex ===================================== @@ -0,0 +1,11 @@ +\newcommand{\haddockbegindoc}{\hfill\\[1ex]} +\newcommand{\haddocktt}[1]{{\small \texttt{#1}}} + {\haddockbegindoc + This is a definition list:\par + \vbox{ + \begin{description} + \item[\haddocktt{foo}]\hfill \par + The description of \haddocktt{foo}. + \item[\haddocktt{bar}]\hfill \par + The description of \haddocktt{bar}. + \end{description}}} ===================================== utils/haddock/doc/snippets/Snippet-List-Enumerated.html ===================================== @@ -0,0 +1,5 @@ +<p>This is an, (n) n., enumerated list:</p> +<ol> +<li>first item</li> +<li>second item</li> +</ol> ===================================== utils/haddock/doc/snippets/Snippet-List-Enumerated.tex ===================================== @@ -0,0 +1,10 @@ +\newcommand{\haddockbegindoc}{\hfill\\[1ex]} + {\haddockbegindoc + This is an, (n) n., enumerated list:\par + \vbox{ + \begin{enumerate} + \item + first item\par + \item + second item\par + \end{enumerate}}} ===================================== utils/haddock/doc/snippets/Snippet-List-Indentation.html ===================================== @@ -0,0 +1,4 @@ +<ul> +<li>foo</li> +<li>bar</li> +</ul> ===================================== utils/haddock/doc/snippets/Snippet-List-Indentation.tex ===================================== @@ -0,0 +1,9 @@ +\newcommand{\haddockbegindoc}{\hfill\\[1ex]} + {\haddockbegindoc + \vbox{ + \begin{itemize} + \item + foo\par + \item + bar\par + \end{itemize}}} ===================================== utils/haddock/doc/snippets/Snippet-List-Multiline-Item.html ===================================== @@ -0,0 +1,4 @@ +<ul> +<li>first item and more content for the first item</li> +<li>second item and more content for the second item</li> +</ul> ===================================== utils/haddock/doc/snippets/Snippet-List-Multiline-Item.tex ===================================== @@ -0,0 +1,11 @@ +\newcommand{\haddockbegindoc}{\hfill\\[1ex]} + {\haddockbegindoc + \vbox{ + \begin{itemize} + \item + first item + and more content for the first item\par + \item + second item + and more content for the second item\par + \end{itemize}}} ===================================== utils/haddock/doc/snippets/Snippet-List-Nested-Item.html ===================================== @@ -0,0 +1,20 @@ +<ul> +<li><p>Beginning of list This belongs to the list above!</p> +<pre><code>nested +bird +tracks</code></pre> +<ul> +<li><p>Next list More of the indented list.</p> +<ul> +<li><p>Deeper</p> +<pre><code>even code blocks work</code></pre> +<ul> +<li><p>Deeper</p> +<ol> +<li>Even deeper!</li> +<li>No newline separation even in indented lists.</li> +</ol></li> +</ul></li> +</ul></li> +</ul></li> +</ul> ===================================== utils/haddock/doc/snippets/Snippet-List-Nested-Item.tex ===================================== @@ -0,0 +1,47 @@ +\newcommand{\haddockbegindoc}{\hfill\\[1ex]} +\newcommand{\haddockverb}{\small} + {\haddockbegindoc + \vbox{ + \begin{itemize} + \item + Beginning of list + This belongs to the list above!\par + \begin{quote} + {\haddockverb + \begin{verbatim} +nested +bird +tracks + \end{verbatim}} + \end{quote} + \vbox{ + \begin{itemize} + \item + Next list + More of the indented list.\par + \vbox{ + \begin{itemize} + \item + Deeper\par + \begin{quote} + {\haddockverb + \begin{verbatim} +even code blocks work + \end{verbatim}} + \end{quote} + \vbox{ + \begin{itemize} + \item + Deeper\par + \vbox{ + \begin{enumerate} + \item + Even deeper!\par + \item + No newline separation even in + indented lists.\par + \end{enumerate}} + \end{itemize}} + \end{itemize}} + \end{itemize}} + \end{itemize}}} ===================================== utils/haddock/doc/snippets/Snippet-List-Not-Newline.html ===================================== @@ -0,0 +1,10 @@ +<p>This is an enumerated list, with items not separated by newlines:</p> +<ol> +<li>first item</li> +<li>second item</li> +</ol> +<p>This is a bulleted list, with items not separated by newlines:</p> +<ul> +<li>first item</li> +<li>second item</li> +</ul> ===================================== utils/haddock/doc/snippets/Snippet-List-Not-Newline.tex ===================================== @@ -0,0 +1,18 @@ +\newcommand{\haddockbegindoc}{\hfill\\[1ex]} + {\haddockbegindoc + This is an enumerated list, with items not separated by newlines:\par + \vbox{ + \begin{enumerate} + \item + first item\par + \item + second item\par + \end{enumerate}} + This is a bulleted list, with items not separated by newlines:\par + \vbox{ + \begin{itemize} + \item + first item\par + \item + second item\par + \end{itemize}}} ===================================== utils/haddock/doc/snippets/Snippet-List-Not-Separated.html ===================================== @@ -0,0 +1,2 @@ +<p><strong>Missing blank lines</strong> before a list: * first item * +second item</p> ===================================== utils/haddock/doc/snippets/Snippet-List-Not-Separated.tex ===================================== @@ -0,0 +1,5 @@ +\newcommand{\haddockbegindoc}{\hfill\\[1ex]} + {\haddockbegindoc + \textbf{Missing blank lines} before a list: + * first item + * second item\par} View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/compare/10b4d3641f6fe7a7443bd621d62d135... -- View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/compare/10b4d3641f6fe7a7443bd621d62d135... You're receiving this email because of your account on gitlab.haskell.org.