Broken ghc-flag links in the users guide
I'm working on cleaning up the users guide, and I have come across an issue with referencing ghc-flags. Essentially, it has to with flags that take arguments. You can see a couple examples if you go to the flag reference here: https://downloads.haskell.org/\~ghc/latest/docs/html/users_guide/flags.html\#redirecting-output
The top flags all have valid links, but the code to generate them is doing it slightly wrong. Let's consider
-o ⟨filename⟩ for instance. There needs to be a specific reference name for this flag. This name serves a couple purposes. First, it forms the end of the url (i.e. .../separate_compilation.html#ghc-flag--o). Second, the form of cross-references to it (i.e.
There are two options:
Option 1 (The current system):
We exclude the arguments from the reference name of the flag. So
is a valid reference that gets rendered as __-o__. The main issue with this system is loss of information. If someone wanted to include the flags in the link, they would have to do `:ghc-flag:`-o ⟨filename⟩ <-o>, which would render as -o ⟨filename⟩ but link to the same place as -o. This also leads to
possibly different choices for the argument name. In fact, the definition has
⟨file⟩ but the reference
We include the arguments in the reference name. So to make the reference, one would have to match the
which would be rendered as __-o ⟨file⟩__, and `:ghc-flag:`-o ⟨filename⟩ would not be a valid reference. This solves the loss of information issue from option 1, but does require the person documenting to check for the exact argument wording.
I would argue for the second option as it is more consistent, but either is workable. Also note that the current parser automatically converts < (less than) into ⟨, so dealing with special characters is very easy. And these issues also apply to flags that use '='. I thought it best to ask before I converted everything to one way of dealing with these.