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

changed milestone to %6.8 branch

changed weight to 5

added Tfeature request Trac import driver labels

changed weight to 7

Trac metadata

Trac field	Value
Priority	normal → high

mentioned in issue #1572

assigned to @trac-igloo

changed weight to 5

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.

Trac metadata

Trac field	Value
Priority	high → normal

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

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

Trac metadata

Trac field	Value
CC	→ claus.reinke@talk21.com

mentioned in commit 14d3b9c9

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).

Replying to [ticket:1226#comment:18373 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 ticket:1226#comment:18373, 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

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).

Replying to [ticket:1226#comment:18843 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

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.

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

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.

mentioned in issue #1880 (closed)

mentioned in issue #1881 (closed)

closed

This ticket has been replaced by #1880 (closed) and #1881 (closed).

Trac metadata

Trac field	Value
Resolution	Unresolved → ResolvedDuplicate

changed milestone to %6.8.2

Trac metadata

Trac field	Value
Architecture	Unknown → Unknown/Multiple

Trac metadata

Trac field	Value
Operating system	Unknown → Unknown/Multiple

added Pnormal label

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

Child items 0

Activity

Trac field	Value
Version	6.6
Type	FeatureRequest
TypeOfFailure	OtherFailure
Priority	normal
Resolution	Unresolved
Component	Driver
Test case
Differential revisions
BlockedBy
Related
Blocking
CC
Operating system	Unknown
Architecture	Unknown