| Commit message (Collapse) | Author | Age | Files | Lines |
|---|
| |
|
|
|
| |
This is breaking the build on some platforms. It's unclear exactly why but I
don't have time to investigate at the moment.
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
I.e. instead of
.. ghc-flag:: -XUnboxedTuples
:shortdesc: Enable the use of unboxed tuple syntax.
:type: dynamic
:reverse: -XNoUnboxedTuples
:category:
one simply writes
.. extension:: UnboxedTuples
:shortdesc: Enable the use of unboxed tuple syntax.
This allows language extensions to be referenced as
If :extension:`UnboxedTuples` is enabled, then...
This directive still creates the entries for the `-XUnboxedTuples` flag,
so in particular,
Set :ghc-flag:`-XUnboxedTuples` if you have to.
still works, and lists of flags in general (e.g. for the manpage)
include these.
I also removed lots of links from the shortdesc of the extensions, when
this link simply points to the section where the extension is defined.
I removed the list of `-X` flags from the flag reference table, but added a
table of extension under “10.1. Language options”
Lots of text in the manual now refers to “extension `Foo`” rather than
“flag `-XFoo`”.
I consider `-XFoo` a historic artifact that stems from when language
extensions were really just flags. These days, the use of `-XFoo` is
(IMHO) deprecated: You should be using `LANGUAGE Foo`, or maybe the
appropriate field in a `.cabal` file. See 9278994 which did this change
to error messages already.
Differential Revision: https://phabricator.haskell.org/D4112
|
| | |
|
|
|
This removes all dependencies the users guide had on `mkUserGuidePart`.
The generation of the flag reference table and the various pieces of the
man page is now entirely contained within the Spinx extension
`flags.py`. You can see the man page generation on the orphan page
https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/ghc.html
The extension works by collecting all of the meta-data attached to the
`ghc-flag` directives and then formatting and displaying it at
`flag-print` directives. There is a single printing directive that can
be customized with two options, what format to display (table, list, or
block of flags) and an optional category to limit the output to
(verbosity, warnings, codegen, etc.).
New display formats can be added by creating a function
`generate_flag_xxx` (where `xxx` is a description of the format) which
takes a list of flags and a category and returns a new `xxx`. Then just
add a reference in the dispatch table `handlers`. That display can now
be run by passing `:type: xxx` to the `flag-print` directive.
`flags.py` contains two maps of settings that can be adjusted. The first
is a canonical list of flag categories, and the second sets default
categories for files.
The only functionality that Sphinx could not replace was the
`what_glasgow_exts_does.gen.rst` file. `mkUserGuidePart` actually just
reads the list of flags from `compiler/main/DynFlags.hs` which Sphinx
cannot do. As the flag is deprecated, I added the list as a static file
which can be updated manually.
Additionally, this patch updates every single documented flag with the
data from `mkUserGuidePart` to generate the reference table.
Fixes #11654 and, incidentally, #12155.
Reviewers: austin, bgamari
Subscribers: rwbarton, thomie
GHC Trac Issues: #11654, #12155
Differential Revision: https://phabricator.haskell.org/D3839
|
