#11654: User Guide: Generate command line options table from ghc-flags directives -------------------------------------+------------------------------------- Reporter: bgamari | Owner: (none) Type: task | Status: new Priority: normal | Milestone: 8.4.1 Component: Documentation | Version: 7.10.3 Resolution: | Keywords: Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Changes (by bgamari): * milestone: 8.2.1 => 8.4.1 Comment: This won't happen for 8.2. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/11654#comment:2 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler

#11654: User Guide: Generate command line options table from ghc-flags directives -------------------------------------+------------------------------------- Reporter: bgamari | Owner: patrickdoc Type: task | Status: new Priority: normal | Milestone: 8.4.1 Component: Documentation | Version: 7.10.3 Resolution: | Keywords: Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Comment (by patrickdoc): I have a proof of concept for this. It's looking like the best plan is to wrap the table info into the declaration of a flag, something like: {{{ .. ghc-flag:: -v :shortdesc: verbose mode (equivalent to -v3) :type: dynamic :reverse: (none for this flag) Longer decription here... }}} Which would render as: **-v** Longer description here and then the table could look like, | **-v** | verbose mode (equivalent to -v3) | dynamic | | --- The main tasks remaining are figuring out the formatting of the table, determining what variables actually need to be passed around, and moving all the info into the flag declarations from the `mkUserGuidePart` files. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/11654#comment:4 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler

#11654: User Guide: Generate command line options table from ghc-flags directives -------------------------------------+------------------------------------- Reporter: bgamari | Owner: patrickdoc Type: task | Status: new Priority: normal | Milestone: 8.4.1 Component: Documentation | Version: 7.10.3 Resolution: | Keywords: Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Comment (by patrickdoc): Things are mostly working now, but a question has arisen. How do we want to categorize the flags? We could just have them grouped by source file (inflexible but simple). Alternatively, we could add an additional option to the flag declaration that chooses the category (flexible but requires specifying where every single flag should go). I could even make it an optional override deal where it is put under source file by default, but you can choose another if you want. I believe the current system is mostly source file based, but not entirely. I'm hesistant to add a 4th field to the declaration, so I thought I would ask if this is something worth supporting or not. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/11654#comment:6 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler

#11654: User Guide: Generate command line options table from ghc-flags directives -------------------------------------+------------------------------------- Reporter: bgamari | Owner: patrickdoc Type: task | Status: patch Priority: normal | Milestone: 8.4.1 Component: Documentation | Version: 7.10.3 Resolution: | Keywords: Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): D3839 Wiki Page: | -------------------------------------+------------------------------------- Changes (by patrickdoc): * status: new => patch * differential: => D3839 -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/11654#comment:8 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler

#11654: User Guide: Generate command line options table from ghc-flags directives -------------------------------------+------------------------------------- Reporter: bgamari | Owner: patrickdoc Type: task | Status: patch Priority: normal | Milestone: 8.4.1 Component: Documentation | Version: 7.10.3 Resolution: | Keywords: Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Phab:D3839 Wiki Page: | -------------------------------------+------------------------------------- Comment (by Ben Gamari ): In [changeset:"cf8ab1ced6f15dad03dd7bcc454ef759cf4d3b3d/ghc" cf8ab1ce/ghc]: {{{ #!CommitTicketReference repository="ghc" revision="cf8ab1ced6f15dad03dd7bcc454ef759cf4d3b3d" users_guide: Convert mkUserGuidePart generation to a Sphinx extension 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 }}} -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/11654#comment:10 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler

#11654: User Guide: Generate command line options table from ghc-flags directives -------------------------------------+------------------------------------- Reporter: bgamari | Owner: patrickdoc Type: task | Status: closed Priority: normal | Milestone: 8.4.1 Component: Documentation | Version: 7.10.3 Resolution: fixed | Keywords: Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Phab:D3839 Wiki Page: | -------------------------------------+------------------------------------- Comment (by patrickdoc): What happens to the `mkUserGuidePart` code now? I seem to have left a bit of orphaned content laying around the build system and code comments. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/11654#comment:12 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler

#11654: User Guide: Generate command line options table from ghc-flags directives -------------------------------------+------------------------------------- Reporter: bgamari | Owner: (none) Type: task | Status: new Priority: normal | Milestone: 8.4.1 Component: Documentation | Version: 7.10.3 Resolution: | Keywords: Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Phab:D3839 Wiki Page: | -------------------------------------+------------------------------------- Changes (by bgamari): * status: closed => new * owner: patrickdoc => (none) * resolution: fixed => -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/11654#comment:14 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler

#11654: User Guide: Generate command line options table from ghc-flags directives -------------------------------------+------------------------------------- Reporter: bgamari | Owner: (none) Type: task | Status: closed Priority: normal | Milestone: 8.4.1 Component: Documentation | Version: 7.10.3 Resolution: fixed | Keywords: Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Phab:D3839, Wiki Page: | Phab:D3886 -------------------------------------+------------------------------------- Changes (by bgamari): * status: patch => closed * resolution: => fixed Comment: Phab:D3886 has been merged. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/11654#comment:16 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler