Document effect of order for file-header pragmas
Summary
File header pragmas take effect in a given order (top-down I believe). This is important to document, since sometimes later options can override the effect of earlier options, e.g. later language extensions can turn off earlier ones; later GHC options can turn off warning flags that were turned on earlier, etc.
Moreover, there is an ordering with command-line flags. I think that the file-header pragmas come after command line flags.
The User's Guide section on pragmas is quite helpful but doesn't explain the ordering.
Proposed improvements or changes
I think the "true answer" is something like:
All file-header pragmas are converted into GHC command line flags in the order that they appear in the file, and these flags are appended to the list of flags that GHC uses to compile the module.
This is a bit operational, perhaps this phrasing is equivalent:
Options set by file-header pragmas are applied in the order that they appear in the file, and after any command-line flags which GHC has been given for the module.
Related tickets
#18006 doesn't like that there is an ordering at all. I just would like it to be documented!