users-guide: Standardize and repair all flag references
authorPatrick Dougherty <patrick.doc@ameritech.net>
Sun, 23 Jul 2017 16:55:37 +0000 (12:55 -0400)
committerBen Gamari <ben@smart-cactus.org>
Sun, 23 Jul 2017 19:47:21 +0000 (15:47 -0400)
commit44b090be9a6d0165e2281542a7c713da1799e885
tree51bc316cb5a86810efbbe3ee606b9cdf8a82cd6e
parentd4e97212fdcb6127d750577aa7f2d709fee27d56
users-guide: Standardize and repair all flag references

This patch does three things:

1.) It simplifies the flag parsing code in `conf.py` to properly display
flag definitions created by `.. (ghc|rts)-flag::`. Additionally, all flag
references must include the associated arguments. Documentation has been
added to `editing-guide.rst` to explain this.

2.) It normalizes all flag definitions to a similar format. Notably, all
instances of `<>` have been replaced with `⟨⟩`. All references across the
users guide have been updated to match.

3.) It fixes a couple issues with the flag reference table's generation code,
which did not handle comma separated flags in the same cell and did not
properly reference flags with arguments.

Test Plan:
`SPHINXOPTS = -n` to activate "nitpicky" mode, which reports all broken
references. All remaining errors are references to flags without any
documentation.

Reviewers: austin, bgamari

Reviewed By: bgamari

Subscribers: rwbarton, thomie

GHC Trac Issues: #13980

Differential Revision: https://phabricator.haskell.org/D3778
36 files changed:
docs/users_guide/8.2.1-notes.rst
docs/users_guide/conf.py
docs/users_guide/debug-info.rst
docs/users_guide/debugging.rst
docs/users_guide/editing-guide.rst
docs/users_guide/extending_ghc.rst
docs/users_guide/ffi-chap.rst
docs/users_guide/ghci.rst
docs/users_guide/glasgow_exts.rst
docs/users_guide/packages.rst
docs/users_guide/phases.rst
docs/users_guide/profiling.rst
docs/users_guide/runtime_control.rst
docs/users_guide/separate_compilation.rst
docs/users_guide/shared_libs.rst
docs/users_guide/sooner.rst
docs/users_guide/using-concurrent.rst
docs/users_guide/using-optimisation.rst
docs/users_guide/using-warnings.rst
docs/users_guide/using.rst
utils/mkUserGuidePart/Main.hs
utils/mkUserGuidePart/Options/CompilerDebugging.hs
utils/mkUserGuidePart/Options/FindingImports.hs
utils/mkUserGuidePart/Options/Interactive.hs
utils/mkUserGuidePart/Options/Linking.hs
utils/mkUserGuidePart/Options/Misc.hs
utils/mkUserGuidePart/Options/Modes.hs
utils/mkUserGuidePart/Options/Packages.hs
utils/mkUserGuidePart/Options/PhasePrograms.hs
utils/mkUserGuidePart/Options/PhaseSpecific.hs
utils/mkUserGuidePart/Options/Phases.hs
utils/mkUserGuidePart/Options/Plugin.hs
utils/mkUserGuidePart/Options/ProgramCoverage.hs
utils/mkUserGuidePart/Options/RedirectingOutput.hs
utils/mkUserGuidePart/Options/Verbosity.hs
utils/mkUserGuidePart/Options/Warnings.hs