Unify flag descriptions to generate both docs and code

[simonmar]

We want to specify all of GHC's flags in one place, and from there

• Generate the flag reference section of the documentation
• Generate the code to parse the command-line
• Allow flags to be deprecated, generating a warning
• Have an option to list all the flags that GHC supports (see #1226) for use in command-line completion
• Generate the man page
• Completion in GHCi

This ticket replaces part of #1226.

[claus]

it would also be useful to have

• default settings
• categories (ghci/profiling/..)

that would make it easier to generate platform- and version-specific tests (cf ghci024), and to highlight ghci-related flags in ghci, from the same central knowledge base.

[ajd]

Has anyone considered using System.Console.GetOpt? for this? From my understanding, it would allow automatic generation of a --help message for the options. I think  help2man could generate the man page from that as well.

[claus]

something has gone wrong here, with all the ticket splitting and closing. it seems that recent ghcs support neither --print-docdir nor anything resembling --full-flag-help.

since i tend to work with multiple self-compiled ghcs more than with installer versions, i'm still looking mainly for something commandline based, exactly what the original #1226 tried to address.

at this stage, since my patch for #1226 was rejected, i'd be happy with a minimal solution, with ghc --full-flag-help

- calling man <path-to-version-specific-ghc.1> where available (including cygwin)

- do its own man-to-text conversion where man is not available; or reply with the path to the version-specific flag reference html page (then i could write a wrapper to start a browser with this)

(commandline output preferred, of course..)

btw, what happened to --print-docdir?

[simonmar]

FYI:

commit 6f50d204c87144cacfee4d86463b2167e34fe6d4
Author: Ian Lynagh <igloo@earth.li>
Date:   Tue Nov 27 20:56:05 2007 +0100

    Remove the --print-docdir flag
    
    It wasn't doing the right thing for bindists. Let's rethink...

[claus]

ah, so it is the general "how do i find the other parts of myself" issue, once again?

how about this approach: have ghc/ghci, libdir, docdir, and whatever else is needed, registered as special "system" packages (or as fields of a single system package) with ghc-pkg during installation (or post-"install" for tarballs).

then the only thing one needs to know is how to find ghc-pkg or its database, which ghc, ghci, and ghc-pkg seem to be able to do already. and ghc-pkg could be queried for all other tool and library locations. after something like

ghc-pkg register --system docdir <path>,

ghc-pkg --system docdir

would yield the last registered location of the docs, if any. and similarly for finding libdir, etc. the registration/update would be done by installers, package managers, or users (for tarballs/bootstraps).

does that sound plausible?

[duncan]

I think we're getting off-topic. As I understand it, this ticket is about generating all the flags related features (code and docs) from one description not about ghc knowing where someone installed the user guide.

If that is on topic then I'd add that I don't actually see what problem ghc --print-docdir is solving. Afaik, no other program has such a thing.

I'd also like to add a plug for command line flag name completion. We've added that feature in cabal-install and it's enormously helpful. It saves typing but most importantly saves having to remember a lot of flag names. With a little support in ghc itself the scripts for bash or other standard shells become pretty trivial. Eg the cabal program has a --list-options flag which prints each flag, one per line.

[claus]

This ticket is the only surviving replacement of #1226, so it must be on topic. And the point was that something had gone missing unresolved from that ticket, including the motivation for the changes that seems to elude you (such as easy programatic access to the docs matching a particular version of ghc).

But I'm not unwilling to help: if the patch for #1226 had been accepted, every GHC installation would come with a flagref.txt file extracted from flags.xml serving as the basis for --full-flag-help, but also easily useable to extract just the flag names.

Meanwhile, you don't have to wait for the grand unification in this ticket to succeed, you could use a subset of the xsl file used in that patch to extract the flag names from flags.xml (at least to a first approximation, there are a handful of special cases that may need further tweaking, like -monly-[432]-regs):

<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform" >

<xsl:output method="text" omit-xml-declaration="yes" />
<xsl:template match="/">

<xsl:for-each select="//sect2">
  <xsl:for-each select=".//row">
    <xsl:choose>
  <xsl:when test="entry[1]='Flag'">
  </xsl:when>
  <xsl:otherwise>
  <xsl:value-of select="normalize-space(entry[1])"/>
  <xsl:text>
</xsl:text>
  </xsl:otherwise>
  </xsl:choose>
  </xsl:for-each>
</xsl:for-each>

</xsl:template>
</xsl:stylesheet>

and then you can run this (after merging back into a single line or script)

$ sed 's/\(<?xml version[^>]*>\)/
        \0\n<!DOCTYPE sect1 \[<!ENTITY ndash  "-"> <!ENTITY ldquo  "\`"> <!ENTITY rdquo  "'\''">\]>/' 
      ghc/docs/users_guide/flags.xml  
  | xsltproc flaglist.xsl -

to get

-?
-help
-n
-v
-vn
-V
--supported-languages
--info
--version
--numeric-version
--print-libdir
-ferror-spans
-Hsize
-Rghc-timing
..

btw 1: it would be useful to make sure that <option> is *only* used for options in the users guide, and then compare the list of options extracted from the users guide to the list of options extracted from flags.xml (or whatever unified source this ticket leads to). that would reduce the number of outdated flag-references in the users guide.

btw 2: is there a bash completion file for haskell tools somewhere?

[morabbin]

Bump; how does HEAD fare in this respect?