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. :ghc-flag:
-o``).
There are two options:
Option 1 (The current system):
We exclude the arguments from the reference name of the flag. So :ghc-flag:
-o 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
table has ⟨filename⟩
.
Option 2:
We include the arguments in the reference name. So to make the reference, one would have to match the
definition exactly: :ghc-flag:
-o ⟨file⟩ 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.
Trac metadata
Trac field | Value |
---|---|
Version | 8.0.1 |
Type | Bug |
TypeOfFailure | OtherFailure |
Priority | normal |
Resolution | Unresolved |
Component | Documentation |
Test case | |
Differential revisions | |
BlockedBy | |
Related | |
Blocking | |
CC | |
Operating system | |
Architecture |