Add some predictable way of labeling section headers

[garetxe]

In working in updating #1078 to the latest version of haddock in git HEAD, I noticed that db3725f broke the capability of adding custom anchors for sections.

I do see the reasoning for the change (particularly in light of #1054), but I was wondering if there was any way to restore some equivalent functionality: that is, having a way of generating a predictable label that points to a section in the documentation.

Perhaps one way would be, instead of ignoring anchors in section headers, use the given anchor as the section id, instead of generating some numerical id automatically. I have not attempted to implement this, so I don't know how hard it is, but I could give it a try.

(The old possibility of adding anchors to section headers is used extensively in gi-gtk, for instance. Having the code generator keep track of the numbering of the sections across module boundaries is difficult and very brittle.)

[garetxe]

Perhaps one way would be, instead of ignoring anchors in section headers, use the given anchor as the section id, instead of generating some numerical id automatically. I have not attempted to implement this, so I don't know how hard it is, but I could give it a try.

I just tried this, it turned out to be fairly easy:

diff --git a/haddock-api/src/Haddock/Backends/Xhtml.hs b/haddock-api/src/Haddock/Backends/Xhtml.hs
index e3d4e8ca..4e87d0be 100644
--- a/haddock-api/src/Haddock/Backends/Xhtml.hs
+++ b/haddock-api/src/Haddock/Backends/Xhtml.hs
@@ -672,10 +672,16 @@ numberSectionHeadings = go 1
   where go :: Int -> [ExportItem DocNameI] -> [ExportItem DocNameI]
         go _ [] = []
         go n (ExportGroup lev _ doc : es)
-          = ExportGroup lev (show n) doc : go (n+1) es
+          = case collectAnchors doc of
+              [] -> ExportGroup lev (show n) doc : go (n+1) es
+              (a:_) -> ExportGroup lev a doc : go (n+1) es
         go n (other:es)
           = other : go n es
 
+        collectAnchors :: DocH (Wrap (ModuleName, OccName)) (Wrap DocName) -> [String]
+        collectAnchors (DocAppend a b) = collectAnchors a ++ collectAnchors b
+        collectAnchors (DocAName a) = [a]
+        collectAnchors _ = []
 
 processExport :: Bool -> LinksInfo -> Bool -> Maybe Package -> Qualification
               -> ExportItem DocNameI -> Maybe Html

With this, a section of the form -- * Some title #some:anchor# gets an id g:some:anchor in the generated HTML.

Would you be interested in this approach? I can clean this up and submit a pull request if you think that this is a reasonable thing to do.

[garetxe]

Perhaps one way would be, instead of ignoring anchors in section headers, use the given anchor as the section id, instead of generating some numerical id automatically. I have not attempted to implement this, so I don't know how hard it is, but I could give it a try.

I just tried this, it turned out to be fairly easy:

diff --git a/haddock-api/src/Haddock/Backends/Xhtml.hs b/haddock-api/src/Haddock/Backends/Xhtml.hs
index e3d4e8ca..4e87d0be 100644
--- a/haddock-api/src/Haddock/Backends/Xhtml.hs
+++ b/haddock-api/src/Haddock/Backends/Xhtml.hs
@@ -672,10 +672,16 @@ numberSectionHeadings = go 1
   where go :: Int -> [ExportItem DocNameI] -> [ExportItem DocNameI]
         go _ [] = []
         go n (ExportGroup lev _ doc : es)
-          = ExportGroup lev (show n) doc : go (n+1) es
+          = case collectAnchors doc of
+              [] -> ExportGroup lev (show n) doc : go (n+1) es
+              (a:_) -> ExportGroup lev a doc : go (n+1) es
         go n (other:es)
           = other : go n es
 
+        collectAnchors :: DocH (Wrap (ModuleName, OccName)) (Wrap DocName) -> [String]
+        collectAnchors (DocAppend a b) = collectAnchors a ++ collectAnchors b
+        collectAnchors (DocAName a) = [a]
+        collectAnchors _ = []
 
 processExport :: Bool -> LinksInfo -> Bool -> Maybe Package -> Qualification
               -> ExportItem DocNameI -> Maybe Html

With this, a section of the form -- * Some title #some:anchor# gets an id g:some:anchor in the generated HTML.

Would you be interested in this approach? I can clean this up and submit a pull request if you think that this is a reasonable thing to do.

[harpocrates]

Yeah, I think this is a reasonable compromise. I'd gladly merge a PR for this - I totally understand why it is useful to have some deterministic anchor for headings for the sake of stable links. 👍

[garetxe]

Great, thanks! I just created #1179 with the change. I also added a test, please let me know if there is anything you want me to change.

[garetxe]

Closing now that #1179 has been merged. Thanks!