#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