Add flags --full-flag-help and --print-docdir

[igloo]

In the thread starting  http://www.haskell.org/pipermail/glasgow-haskell-users/2007-March/012141.html two new flags are proposed:

A --full-flag-help flag, which prints essentially the ghc manpage.

A --print-docdir flag:

$ ghc --print-docdir
c:/ghc/ghc-6.6/doc/html

where there are local docs,

$ ghc --print-docdir
http://www.haskell.org/ghc/docs/6.6/html/

otherwise (note version specific URL).

[igloo]

There's now a --print-docdir flag that prints where the docs are on the assumption that they exist. That's probably all we'll do for 6.8.1.

[claus]

--print-docdir doesn't seem to work properly on win/xp:

C:\fptools\ghc>compiler\stage2\ghc-inplace --print-docdir
/usr/local/doc/ghc

[guest]

just so that this doesn't get lost: there's a simple xslt file to extract text for a --full-flag-help option here

 http://www.haskell.org/pipermail/cvs-ghc/2007-September/038560.html

it is simpler than the one for man pages, using sed to define the missing ENTITY references, and it brings each flag onto a single line, making it ideal for grep.

now, for a first implementation of --full-flag-help, just generate the text file when creating a release/snapshot, install in ghc --print-docdir, and make the flag print the file (for bonus points, build in the pattern filter for those who don't have grep/awk at hand, so that --full-flag-help "interactive mode:" gives the ghci flags, and "language:instances" gives the language flags related to instances).

[guest]

Replying to guest:

just so that this doesn't get lost: there's a simple xslt file to extract text for a --full-flag-help option here  http://www.haskell.org/pipermail/cvs-ghc/2007-September/038560.html

a patch implementing flag reference command line help with simple search, close to what was suggested in comment:5, was sent to cvs-ghc:

 http://www.haskell.org/pipermail/cvs-ghc/2007-October/039184.html

here is the patch description:

add flag --flags (FIX #1226)

 Ticket #1226 calls for a '--full-flag-help' flag, presenting the
 users guide's flag reference or man page in text format. Since a
 man page isn't much good on windows, and a full listing of flags
 isn't all that helpful, either, i've implemented a slight refinement
 of these suggestions:

 ghc --flags [<section>:]<flag>
   lists flags containing substring <flag> in
   sections containing substring <section>

 examples:

 ghc --flags :
   lists the full flag reference
 ghc --flags @
   lists section headers only (because @ doesn't occur in flags)
 ghc --flags Prof:
   lists flags in the 'Profiling options' section
 ghc --flags ghci
   lists flags mentioning ghci in all sections

claus

[simonmar]

I was tempted to turn the man page into .txt and spit that out in response to ghc --full-help or whatever. Then you have grep and more to inspect the output. Isn't that much simpler?

No extra tools are required, the .txt would come with the Windows distribution. Turning the man page into .txt is a simple matter of nroff -mandoc -c -Tascii ghc.1 (if I recall correctly).

[guest]

Replying to simonmar:

I was tempted to turn the man page into .txt and spit that out in response to ghc --full-help or whatever. Then you have grep and more to inspect the output. Isn't that much simpler?

a .txt version of ghc.1 might be useful as response to ghc --help (merging usage and man page), or even as a separate --full-help. but it doesn't help much with finding flags:

• grep is find on windows, but the man page isn't really suited for either, due to each flag spanning several lines
• more on windows doesn't seem to support search
• finding sections is more a job for awk's /begin/,/end/ than for grep, and is awkward even on unix, more so on windows (without awk)

you'll find that the flagref.txt is both simpler to generate than the man page and simpler in format (one line per flag, making it suitable for grep/find, and for simple substring matching in Main.hs). and since the substring matching is built-in, usage requires neither grep, nor find, nor more, nor awk. what could be simpler than that? and how would you do things like the following three queries with your man-page to .txt suggestion, with only windows tools?

$ /cygdrive/c/fptools/ghc/compiler/stage2/ghc-inplace --flags :@
Flag reference
Help and verbosity options
Which phases to run
Alternative modes of operation
Redirecting output
Keeping intermediate files
Temporary files
Finding imports
Interface file options
Recompilation checking
Interactive-mode options
Packages
Language options
Warnings
Optimisation levels
Individual optimisations
Profiling options
Program coverage options
Haskell pre-processor options
C pre-processor options
C compiler options
Code generation options
Linking options
Replacing phases
Forcing options to particular phases
Platform-specific options
External core file options
Compiler debugging options
Misc compiler options

$ /cygdrive/c/fptools/ghc/compiler/stage2/ghc-inplace --flags Interactive:
Interactive-mode options

  Flag | Description | Static/Dynamic | Reverse
  -ignore-dot-ghci | Disable reading of .ghci files | static | -
  -read-dot-ghci | Enable reading of .ghci files | static | -
  -fbreak-on-exception | Break on any exception thrown | dynamic | -fno-break-on-exception
  -fbreak-on-error | Break on uncaught exceptions and errors | dynamic | -fno-break-on-error
  -fprint-evld-with-show | Enable usage of Show instances in :print | dynamic | -fno-print-evld-with-show
  -fno-print-bind-result | Turn off printing of binding results in GHCi | dynamic | -

$ /cygdrive/c/fptools/ghc/compiler/stage2/ghc-inplace --flags :type
Flag reference
Help and verbosity options
Which phases to run
Alternative modes of operation
Redirecting output
Keeping intermediate files
Temporary files
Finding imports
Interface file options
Recompilation checking
Interactive-mode options
Packages
Language options
  -XGADTs | Enable generalised algebraic data types. | dynamic | -XNoGADTs
  -XTypeFamilies | Enable type families. | dynamic | -XNoTypeFamilies
  -XScopedTypeVariables | Enable lexically-scoped type variables. Implied by -fglasgow-exts. | dynamic | -XNoScopedTypeVariables
  -XPatternSignatures | Enable pattern type signatures. | dynamic | -XNoPatternSignatures
  -XUnliftedFFITypes | Enable unlifted FFI types. | dynamic | -XNoUnliftedFFITypes
  -XLiberalTypeSynonyms | Enable liberalised type synonyms. | dynamic | -XNoLiberalTypeSynonyms
  -XNoRank2Types | Enable rank-2 types. | dynamic | -XNoRank2Types
  -XRankNTypes | Enable rank-N types. | dynamic | -XNoRankNTypes
  -XTypeOperators | Enable type operators. | dynamic | -XNoTypeOperators
  -XGeneralizedNewtypeDeriving | Enable newtype deriving. | dynamic | -XNoGeneralizedNewtypeDeriving

  -XTypeSynonymInstances | Enable type synonyms. | dynamic | -XNoTypeSynonymInstances
  -XMultiParamTypeClasses | Enable multi parameter type classes. | dynamic | -XNoMultiParamTypeClasses
Warnings
  -fwarn-deprecations | warn about uses of functions & types that are deprecated | dynamic | -fno-warn-deprecations
  -fwarn-type-defaults | warn when defaulting happens | dynamic | -fno-warn-type-defaults
Optimisation levels
Individual optimisations
Profiling options
Program coverage options
Haskell pre-processor options
C pre-processor options
C compiler options
Code generation options
Linking options
Replacing phases
Forcing options to particular phases
Platform-specific options
External core file options
Compiler debugging options
  -ddump-tc | Dump typechecker output | dynamic | -
  -ddump-types | Dump type signatures | dynamic | -
  -ddump-tc-trace | Trace typechecker | dynamic | -
Misc compiler options

claus

[simonmar]

I object quite strongly to the idea that it is our job to compensate for the lack of good text manipulation tools on Windows. We should not bloat GHC with functionality that can easily be provided by other tools. Anyone using the command line on Windows will pretty quickly run into its limitations and install Cygwin or something else.

In any case, a more Windows-y thing to do would be to pop up a web browser on the flag index page. Then if you're using Firefox you can use /string to search. The easiest thing we could do is to add a link to the start menu group for GHC pointing directly to the flag index.

[guest]

"ghc --print-docdir" prints "/usr/local/share/doc/ghc`" regardless of the actual installation prefix for ghc-6.8.1. (Christian.Maeder@…)

[duncan]

A small easily machine parsable format for flags would be really useful for bash command completion support for ghc.

So for that we don't want descriptions, just the names of all supported flags, one per line or something like that. Something easy to work with in bash code.

[simonmar]

This ticket has been replaced by #1880 and #1881.