Fix some more broken inter-module docs links

[aplaice]

Description

There are some broken docs links on hackage. These are mostly due to using a single quote, rather than a double quote for module links. (A single quote is for function links etc., while a double one is for modules etc.)

Some others are due to typos in the original docstrings or due to renames of the modules.

These were detected by generating the docs locally (with cabal haddock, starting a local mini-server (python3 -m http.server) and then recursively wgetting to find missing links.

(When manually fixing these occurrences I also usually checked that the links were broken on hackage, not just locally.)

I haven't fixed many of the detected broken links because:

1. Many of them are to the main xmonad module or to Graphics.X11 (and haddock unfortunately doesn't seem to easily support inter-module links).

2. Some are due to double-quoting normal words (e.g. arg1, icon, file) and I was too lazy to correct them, by escaping the quotes. (IMO they're far lower priority as they're simply links that shouldn't be there, rather than misdirected links.)

3. I probably missed some broken intra-xmonad-contrib links by misclassifying them as category 1 and 2.

Checklist

• [x] I've read CONTRIBUTING.md

• [x] I've considered how to best test these changes (property, unit, manually, ...) and concluded: I regenerated the docs and reran the recursive wget to check that there were fewer broken links. Also, the markup changes are pretty straightforward when one's focused on them (otherwise the double/single quote distinction is indeed confusing :)).

• [ ] I updated the CHANGES.md file (No changes to the API, so IMO no need.)

---

I'm not sure if I should squash all the changes or not and if not, if I should modify the commit messages.

---

BTW thanks very much for maintaining and continuing to develop this amazing piece of software!

[TheMC47]

Thank you! 🎉 Awesome work! I'll check the details later

[liskin]

These were detected by generating the docs locally (with cabal haddock, starting a local mini-server (python3 -m http.server) and then recursively wgetting to find missing links.

(When manually fixing these occurrences I also usually checked that the links were broken on hackage, not just locally.)

Note that we also have https://xmonad.github.io/xmonad-docs/, which is updated nightly, so once this is merged you can run your wget magic against that and see what's left. Inter-package links do work in there as we use stack to build the docs including all deps.

[aplaice]

Thanks for the reviews!

Mh, is this true? I think the respective modules just have to be in score for this to work. For example, submap from X.A.Submap can link to Data.Map from containers with seemingly no issues (absolutely not saying you should go back and fix these as well, of course!).

Oh, you're right! I'm an idiot... (I'm not quite sure what I was thinking — I was aware that links to the base libraries worked, and also that I wasn't building the X11/xmonad-core docs, so there wouldn't have been anywhere to link to.)

I'm not still quite sure why hackage doesn't have the links from xmonad-contrib to X11 or XMonad core, since it does have the dependency tree. However, give that xmonad-docs (whose existence I had forgotten about) does indeed have inter-module links, I won't try to investigate. :)

Note that we also have https://xmonad.github.io/xmonad-docs/, which is updated nightly, so once this is merged you can run your wget magic against that and see what's left. Inter-package links do work in there as we use stack to build the docs including all deps.

Thanks for pointing me to xmonad-docs! That makes sense. (I can also regenerate the interlinked stack-built docs locally, though.)

---

I think it would be better to squash them

Done. However, if having a single commit is desirable, then maybe it might make sense to keep this open until I fix the remaining broken links, now that I can distinguish between inter-package links that are broken because hackage generally has issues with inter-package links (but aren't broken in xmonad-docs) and those that are also broken on xmonad-docs.

[liskin]

I'm not still quite sure why hackage doesn't have the links from xmonad-contrib to X11 or XMonad core, since it does have the dependency tree. However, give that xmonad-docs (whose existence I had forgotten about) does indeed have inter-module links, I won't try to investigate. :)

The docs in Hackage are built and uploaded by us because historically Hackage builds of X11 and anything that depended on it failed (missing deps). It's possible we're doing this wrong. :-(

[aplaice]

The docs in Hackage are built and uploaded by us because historically Hackage builds of X11 and anything that depended on it failed (missing deps). It's possible we're doing this wrong. :-(

I'm probably far, far less of an expert on this than you are. I'm basing my claims on the fact that, on say, the hackage docs for XMonad.Doc.Developing:

https://hackage.haskell.org/package/xmonad-contrib-0.17.1/docs/XMonad-Doc-Developing.html

the links that should be going to XMonad core or X11 (e.g. windowset and Window respectively), are (brokenly) linking to xmonad-contrib, while the same links on the same docs on xmonad-docs work:

https://xmonad.github.io/xmonad-docs/xmonad-contrib-0.17.1.9/XMonad-Doc-Developing.html

(I also haven't found any working inter-module links (from xmonad-contrib to xmonad or X11), on hackage.)

There aren't too many links from xmonad-contrib to xmonad and X11, though, so it's probably not worth worrying too much about! (I don't have stats at the moment, but once the fixing of all links on xmonad-docs is finished, this will be easy to tell.)

[liskin]

https://github.com/xmonad/xmonad-contrib/suites/8890375548/artifacts/406584209 contains an example of the docs tarball that we upload to hackage. Links to mtl are absolute and contain the package name/version, but links to X11 and xmonad are relative as if those modules were part of xmonad-contrib. Definitely something's off there, but I won't be able to investigate it today unfortunately. :-(

But it's definitely a good thing that you pointed it out! While trying to see what's going on I discovered that https://github.com/xmonad/xmonad-contrib/pull/765 and https://github.com/xmonad/xmonad/pull/425 broke the docs tarball generation entirely, and that definitely needs to be fixed before the next release.

[liskin]

Actually, while fixing the broken tarball I did take a brief look at the links issue, and found this:

https://github.com/xmonad/xmonad-contrib/actions/runs/3357208287/jobs/5562859714#step:22:32

Warning: The documentation for the following packages are not installed. No links will be generated to these packages: X11-1.10.3, X11-xft-0.3.4, data-default-class-0.1.2.0, random-1.2.1.1, setlocale-1.0.0.10, splitmix-0.1.0.4, utf8-string-1.0.2, xmonad-0.17.1.9

Not that I have any idea what to do about it. Might as well try to stop uploading docs to Hackage and see if they have the deps and can generate a better version of it… :-)

[aplaice]

I've fixed the remaining fixable links.

I've kept the new changes in two new commits, for easier reviewing.

In addition to the issues described above, the causes of the broken links were:

1. Use of <foo> in the docs is rendered as just foo with a link to /foo.

   (I had previously ignored this, but decided that the combination of the mis-rendering (especially confusing when is an XML tag) and the broken link is annoying.)

2. Similarly for "Foo" if it starts with a capital letter (and hence could be a module).

3. Markup inside @ code blocks is still applied.

   e.g. @M-<arrow-keys>@ is rendered as M-arrow-keys (with a spurious hyperlink from arrow-keys to /arrow-keys), which is confusing.

In some cases I also surrounded the <foo> with @, especially in the case of key definitions, for consistency. (I didn't do it everywhere, because it looks ugly in the source.)

MoreManageHelpers has never been in xmonad-contrib. Based on google searches AFAICT it did exist somewhere on the internet[0], but it seems to be gone. ManageHelpers seems to fill the expected role, though.

[0] (I found a link to http://hpaste.org/83047 but hpaste is down.)

In the case of the module description for X.H.ManageDebug I couldn't get the link to ManageHook to work in any way (with single/double quotes, with/without plural etc.), so I just removed the quotes.

---

The second commit contains potentially problematic changes that can be either squashed or dropped.

The problem is that here readability in the source and in the rendered docs are in tension.

For X.P.FuzzyMatch, reading the rendered docs with broken links to FastSPR etc. (and with no double quotes) is mildly annoying and possibly confusing at first sight:

https://xmonad.github.io/xmonad-docs/xmonad-contrib-0.17.1.9/XMonad-Prompt-FuzzyMatch.html

However, when the quotes are escaped, the source version looks slightly monstrous.

For X.U.Parser, the string that's supposed to be parsed will look wrong in either the rendered or the source version (depending on whether we escape the <> or not). Given that the identity of the string that's supposed to be parsed is important, this can be confusing. (The next line has an example, so hopefully it shouldn't be too confusing.)

https://xmonad.github.io/xmonad-docs/xmonad-contrib/XMonad-Util-Parser.html#g:1

---

Remaining broken links (probably not fixable):

1. Several links from XMonad core to XMonad contrib module

   Haddock thinks these modules are within XMonad core, when they aren't.

   e.g. XMonad core tries to link to XMonad.Util.ExtensibleState.

   I'm not sure if this is even solvable with Haddock ("The modules should not be mutually recursive, as Haddock don’t like swimming in circles." :).

   However, AFAICT it's stated next to these links that the modules are in xmonad-contrib, so the user should be able to manually find them.

2. Several in XMonad.Config.Prime.

   These are because the docs are transcluding the docs of the "rest of the world", which contain a couple of syntax errors (which we can't fix, because they're in GHC.Enum etc.).

3. Links to record fields (e.g. to 'XMonad.Core.XConfig.terminal' (the terminal field of the XConfig datatype), which Haddock interprets as the terminal function of the XMonad.Core.XConfig module). Haddock is capable of linking directly to fields from within function type signatures, but I haven't been able to convince it to do so from literate comments.

[liskin]

• Several in XMonad.Config.Prime. These are because the docs are transcluding the docs of the "rest of the world", which contain a couple of syntax errors (which we can't fix, because they're in GHC.Enum etc.).

These should be solvable by adding {-# OPTIONS_HADDOCK not-home #-} (see https://haskell-haddock.readthedocs.io/en/latest/markup.html#module-attributes) to X.C.Prime, but last time I tried it didn't work. We could try building the docs with newer GHC/haddock, or report it as an issue. (Somewhat low priority so it's not at the top of my todo list.)

[slotThe]

The second commit contains potentially problematic changes that can be either squashed or dropped.

Tbh, I think that these are totally fine. Yes the source is slightly more unreadable, but users will read the Haddocks more often than not, so that's what we should optimise for

[geekosaur]

I vaguely recall that MoreManageHelpers was mine, but I upstreamed the useful stuff at some point.

[aplaice]

Tbh, I think that these are totally fine.

I've squashed everything now. Unless I've missed something, this should be it!

[slotThe]

Yup, seems to be it, thank you!