[GHC] #13980: Broken ghc-flag links in the users guide

[GHC]

#13980: Broken ghc-flag links in the users guide
-------------------------------------+-------------------------------------
           Reporter:  patrickdoc     |             Owner:  (none)
               Type:  bug            |            Status:  new
           Priority:  normal         |         Milestone:
          Component:  Documentation  |           Version:  8.0.1
           Keywords:                 |  Operating System:  Unknown/Multiple
       Architecture:                 |   Type of failure:  None/Unknown
  Unknown/Multiple                   |
          Test Case:                 |        Blocked By:
           Blocking:                 |   Related Tickets:
Differential Rev(s):                 |         Wiki Page:
-------------------------------------+-------------------------------------
 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.

-- 
Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/13980>
GHC <http://www.haskell.org/ghc/>
The Glasgow Haskell Compiler