Jacco Krijnen pushed to branch wip/jacco/haddock/codeblock-highlighting at Glasgow Haskell Compiler / GHC Commits: 008f91e4 by Jacco Krijnen at 2025-04-17T20:03:27+02:00 documentation - - - - - 1 changed file: - utils/haddock/doc/markup.rst Changes: ===================================== utils/haddock/doc/markup.rst ===================================== @@ -845,24 +845,52 @@ Unicode (or ISO 10646). For example, the references ``λ``, Code Blocks ~~~~~~~~~~~ -Displayed blocks of code are indicated by surrounding a paragraph with -``@...@`` or by preceding each line of a paragraph with ``>`` (we often -call these “bird tracks”). For example: :: +Displayed blocks of code can be indicated in different ways: - -- | This documentation includes two blocks of code: +- by surrounding a paragraph with ``@...@`` +- by preceding each line of a paragraph with ``>`` (we often + call these “bird tracks”) +- by surrounding a paragraph with triple backticks `` ``` `` (also known + as fenced code blocks) and optionally indicating a language. Haddock + will apply syntax highlighting when a language is provided. + +For example: :: + + -- | This documentation includes four blocks of code: -- -- @ -- f x = x + x -- @ -- -- > g x = x * 42 - -There is an important difference between the two forms of code block: in -the bird-track form, the text to the right of the ‘\ ``>``\ ’ is -interpreted literally, whereas the ``@...@`` form interprets markup as -normal inside the code block. In particular, ``/`` is markup for italics, -and so e.g. ``@x / y / z@`` renders as ``x`` followed by italic -``y`` with no slashes, followed by ``z``. + -- + -- ``` + -- fix x = f (fix x) + -- ``` + -- + -- ```haskell + -- data Bool = False | True + -- ``` + + +There is an important difference between the forms of code block: bird +tracks and fenced code blocks interpret text literally, whereas the +``@...@`` form interprets haddock markup as normal inside the code +block. + +For example, ``@x / y / z@`` renders as + ++---------------------+-------------------------------+ +| Haddock | Rendered | ++=====================+===============================+ +| ``@x / y / z@`` | .. raw:: html | +| | | +| | <code>x <i>y</i> z</code> | ++---------------------+-------------------------------+ +| ``> x y z`` | .. raw:: html | +| | | +| | <code>x / y / z</code> | ++---------------------+-------------------------------+ Examples ~~~~~~~~ View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/008f91e4d74c8cc36ab65084cbcc4db1... -- View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/008f91e4d74c8cc36ab65084cbcc4db1... You're receiving this email because of your account on gitlab.haskell.org.