Documenting GHC: blogs, wiki pages, Notes, Haddocks, etc

[Viktor Dukhovni]

> On 14 Sep 2021, at 8:29 am, Hécate <hecate at glitchbra.in> wrote:
> 
> I may have missed an episode or two here but what prevents us from writing Notes as Named Chunks¹, write them where Haddock expects you to put documentation, and refer to them from the relevant spot in the code?
> Viktor (in CC) has done a wonderful work at producing nice layouts for Haddocks in base, and we could learn a couple of lessons from his MRs.

Thanks for the callout.  My contribution to the documentation has thus far been
limited to just Data.Foldable and Data.Traversable, though I was hoping that
the approach might catch on if others find it a step in the right direction.

Specific content aside, in terms of haddock techniques, the main thing I
did was to append a more expansive prose overview of a library module below
the function synopses.  This did not require anything fancy, just `$section`
references from the module header.

However I also needed to occasionally create hyperlinks within the overview,
and here I ran into a limitation.  Haddock renders a hyperlink to a particular
anchor section of a module as:

	<a href="....">Module.Name</a>

with no syntax to customise the user-friendly text.  This means that one
is forced into some linguistic contortions to create natural sentences
with the desired hyperlinks.

This is particularly tricky when the hyperlink will appear not only in
the prose of a module's overview, but also in the synopsis of a function
or a class that may be re-exported by another module (e.g. the Prelude).

It would ideally be possible to render the hyperlink differently in its
"home" module than in a re-exporting module.

Otherwise, I found anchors and hyperlinks to be largely usable...

-- 
	Viktor.