New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Consolidate enable/disable help together to get a more concise help output #1613

Closed
harendra-kumar opened this Issue Jan 6, 2016 · 2 comments

Comments

Projects
None yet
3 participants
@harendra-kumar
Collaborator

harendra-kumar commented Jan 6, 2016

There is a huge amount of output to go through in the stack help. It is hard to navigate unless you are intimately familiar with it. Someone new to stack might find it intimidating. Here is a sample output:

stack - The Haskell Tool Stack

Usage: stack [--help] [--version] [--numeric-version] [--docker*] [--nix*]
             ([--verbosity VERBOSITY] | [-v|--verbose]) [--work-dir WORK-DIR]
             ([--system-ghc] | [--no-system-ghc]) ([--install-ghc] |
             [--no-install-ghc]) [--arch ARCH] [--os OS] [--ghc-variant VARIANT]
             [-j|--jobs JOBS] [--extra-include-dirs DIR] [--extra-lib-dirs DIR]
             ([--skip-ghc-check] | [--no-skip-ghc-check]) ([--skip-msys] |
             [--no-skip-msys]) [--local-bin-path DIR] ([--modify-code-page] |
             [--no-modify-code-page]) [--resolver RESOLVER]
             [--compiler COMPILER] ([--terminal] | [--no-terminal])
             [--stack-yaml STACK-YAML] COMMAND|FILE

Available options:
  --help                   Show this help text
  --version                Show version
  --numeric-version        Show only version number
  --docker*                Run 'stack --docker-help' for details
  --nix*                   Run 'stack --nix-help' for details
  --verbosity VERBOSITY    Verbosity: silent, error, warn, info, debug
  -v,--verbose             Enable verbose mode: verbosity level "debug"
  --work-dir WORK-DIR      Override work directory (default: .stack-work)
  --system-ghc             Enable using the system installed GHC (on the PATH)
                           if available and a matching version
  --no-system-ghc          Disable using the system installed GHC (on the PATH)
                           if available and a matching version
  --install-ghc            Enable downloading and installing GHC if necessary
                           (can be done manually with stack setup)
  --no-install-ghc         Disable downloading and installing GHC if necessary
                           (can be done manually with stack setup)
  --arch ARCH              System architecture, e.g. i386, x86_64
  --os OS                  Operating system, e.g. linux, windows
  --ghc-variant VARIANT    Specialized GHC variant, e.g. integersimple (implies
                           --no-system-ghc)
  -j,--jobs JOBS           Number of concurrent jobs to run
  --extra-include-dirs DIR Extra directories to check for C header files
  --extra-lib-dirs DIR     Extra directories to check for libraries
  --skip-ghc-check         Enable skipping the GHC version and architecture
                           check
  --no-skip-ghc-check      Disable skipping the GHC version and architecture
                           check
  --skip-msys              Enable skipping the local MSYS installation (Windows
                           only)
  --no-skip-msys           Disable skipping the local MSYS installation (Windows
                           only)
  --local-bin-path DIR     Install binaries to DIR
  --modify-code-page       Enable setting the codepage to support UTF-8 (Windows
                           only)
  --no-modify-code-page    Disable setting the codepage to support UTF-8
                           (Windows only)
  --resolver RESOLVER      Override resolver in project file
  --compiler COMPILER      Use the specified compiler
  --terminal               Enable overriding terminal detection in the case of
                           running in a false terminal
  --no-terminal            Disable overriding terminal detection in the case of
                           running in a false terminal
  --stack-yaml STACK-YAML  Override project stack.yaml file (overrides any
                           STACK_YAML environment variable)

We can do better by making it more concise.

  1. One way would be to somehow avoid having separate entries for the --no versions of help. That will significantly reduce the amount of data and perhaps make it easier to navigate.

This will reduce the 29 items of options help to 22:

$ stack | grep "^ *\-\-" |wc -l
29
$ stack | grep "^ *\-\-" | grep -v '\-\-no'|wc -l
22

Not sure if this will require changes to optparse.

  1. We should also strive to reduce the options description text so that it fits in single line. That will reduce the total lines as well as improve the presentation.

See also #1333 for a related issue to reduce the amount of help output.

@borsboom

This comment has been minimized.

Contributor

borsboom commented Jan 6, 2016

I did some work in this direction a while ago to try to only have to show the non-default option but hit a snag: we currently have to parse the command-line before reading the config file, but we don't know the defaults until the config file has been read. It may be possible to find a way around that and get this working (related: #893).

Another approach could be to make these options look like:

--[no-]skip-ghc-check      Enable/disable skipping the GHC version and architecture

I think we'd have to make the real --skip-ghc-check and --no-skip-ghc-check hidden and internal (to hide from from the usage/help), and then have a fake --[no-]skip-ghc-check option to show in the help. I don't think that would be too hard to implement in the enableDisable... combinators in stack's Options.Applicate.Builder.Extra.

A pull request would be welcome.

@borsboom borsboom added this to the P2: Should milestone Jan 6, 2016

gambogi added a commit to gambogi/stack that referenced this issue Jan 15, 2016

Unified Enable/disable help messaging
Per issue commercialhaskell#1613, enable/disable flags now occupy 1 line in help output.

Summary:
- Simplified `enableDisableNoDefault` logic as hiding is no longer
  specified manually.
- Helper function `enableDisableNoDefault'` no longer seemed necessary
  after simplification, removed it.
- Fixed issues caused by removing the show/hide argument
- Created "dummy" extra flag with appropriate help message

Issue:
dummy argmuent actually acts as a real flag, which seems bad.
`<*` was causing the hidden actual flags to be dropped by
opt-parse. Ideally this would cause the standard unknown command
behavior.
@mgsloan

This comment has been minimized.

Collaborator

mgsloan commented Jan 15, 2016

Implemented by @gambogi , thanks!

@mgsloan mgsloan closed this Jan 15, 2016

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment