#12155: Description of flags cut off -------------------------------------+------------------------------------- Reporter: mikail | Owner: Type: task | Status: new Priority: low | Milestone: Component: Documentation | Version: 8.0.1 Resolution: | Keywords: flags Operating System: Unknown/Multiple | Architecture: Type of failure: Documentation | Unknown/Multiple bug | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Changes (by thomie): * cc: bgamari (added) Comment: Thank you for the report. If you feel like trying to fix it yourself, the following two files are where those tables are generated: * utils/mkUserGuidePart/Main.hs * utils/mkUserGuidePart/Table.hs But it could also be a `pdflatex` problem. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/12155#comment:1 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler

#12155: Description of flags cut off -------------------------------------+------------------------------------- Reporter: mikail | Owner: Type: task | Status: new Priority: low | Milestone: Component: Documentation | Version: 8.0.1 Resolution: | Keywords: flags Operating System: Unknown/Multiple | Architecture: Type of failure: Documentation | Unknown/Multiple bug | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Comment (by mikail): Would it be possible to switch to Pandoc. It's multi line table option would do the trick. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/12155#comment:3 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler

#12155: Description of flags cut off -------------------------------------+------------------------------------- Reporter: mikail | Owner: (none) Type: task | Status: patch Priority: low | Milestone: Component: Documentation | Version: 8.0.1 Resolution: | Keywords: flags Operating System: Unknown/Multiple | Architecture: Type of failure: Documentation | Unknown/Multiple bug | Test Case: Blocked By: | Blocking: Related Tickets: #11654 | Differential Rev(s): D3839 Wiki Page: | -------------------------------------+------------------------------------- Changes (by patrickdoc): * status: new => patch * differential: => D3839 * related: => #11654 Comment: This was wrapped into the change from `mkUserGuidePart` to Sphinx based generation. Tables are manually sized in `flags.rst`, but even still it's not perfect. LaTeX can't break flags like `-XGeneralizedNewtypeDeriving`, which means that the sum of the minimum column widths is larger than the width of the line. I believe there aren't any egregious overlaps remaining, but some flags do spill out of their cells. Column widths are set in a percentage format that looks like `|\Y{20}|\Y{40}|\Y{10}|\Y{30}|`, which is reasonably amenable to change. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/12155#comment:5 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler

#12155: Description of flags cut off -------------------------------------+------------------------------------- Reporter: mikail | Owner: (none) Type: task | Status: patch Priority: low | Milestone: Component: Documentation | Version: 8.0.1 Resolution: | Keywords: flags Operating System: Unknown/Multiple | Architecture: Type of failure: Documentation | Unknown/Multiple bug | Test Case: Blocked By: | Blocking: Related Tickets: #11654 | 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/12155#comment:7 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler