Cloak v2 and v1 help sections.

[philderbeast]

Instead of listing forward-compatible aliases and legacy command aliases by default could we cloak them behind a sub-command or sub-category of help?

> cabal help
Command line interface to the Haskell Cabal infrastructure.

See http://www.haskell.org/cabal/ for more information.

Usage: cabal [GLOBAL FLAGS] [COMMAND [FLAGS]]

Commands:
 [global]
  update            Updates list of known packages.
  install           Install packages.

  help              Help about commands.
  info              Display detailed information about a particular package.
  list              List packages matching a search string.
  fetch             Downloads packages for later installation.
  user-config       Display and update the user's global cabal configuration.

 [package]
  get               Download/Extract a package's source code (repository).
  init              Create a new .cabal package file.

  configure         Add extra project configuration
  build             Compile targets within the project.
  clean             Clean the package store and remove temporary files.

  run               Run an executable.
  repl              Open an interactive session for the given component.
  test              Run test-suites
  bench             Run benchmarks

  check             Check the package for common mistakes.
  sdist             Generate a source distribution file (.tar.gz).
  upload            Uploads source packages or documentation to Hackage.
  report            Upload build reports to a remote server.

  freeze            Freeze dependencies.
  gen-bounds        Generate dependency bounds.
  outdated          Check for outdated dependencies
  haddock           Build Haddock documentation
  hscolour          Generate HsColour colourised code, in HTML format.
  exec              Give a command access to the store.
  list-bin          list path to a single executable.

  v2-help           Help on forwards-compatible command aliases.
  v1-help           Help on legacy command aliases.

> cabal v2-help

 [new-style projects (forwards-compatible aliases)]
  v2-build          Compile targets within the project.
  v2-configure      Add extra project configuration
  v2-repl           Open an interactive session for the given component.
  v2-run            Run an executable.
  v2-test           Run test-suites
  v2-bench          Run benchmarks
  v2-freeze         Freeze dependencies.
  v2-haddock        Build Haddock documentation
  v2-exec           Give a command access to the store.
  v2-update         Updates list of known packages.
  v2-install        Install packages.
  v2-clean          Clean the package store and remove temporary files.
  v2-sdist          Generate a source distribution file (.tar.gz).

> cabal v1-help

 [legacy command aliases]
  v1-build          Compile all/specific components.
  v1-configure      Prepare to build the package.
  v1-repl           Open an interpreter session for the given component.
  v1-run            Builds and runs an executable.
  v1-test           Run all/specific tests in the test suite.
  v1-bench          Run all/specific benchmarks.
  v1-freeze         Freeze dependencies.
  v1-haddock        Generate Haddock HTML documentation.


  v1-install        Install packages.
  v1-clean          Clean up after a build.


  v1-copy           Copy the files of all/specific components to install locations.
  v1-register       Register this package with the compiler.
  v1-reconfigure    Reconfigure the package if necessary.

Some relevant issues relating to v2- prefixing are: #6213 and #7797. Also there is pull request #6703.

[Mikolaj]

Yeah, it's not a bad idea, but let's wait what comes out of this year's revival of #6703.

[philderbeast]

As a beginner cabal didn't work for me and now that I use it a lot I'm only using commands build, repl, clean and test regularly during development. I use other commands too but less regularly. Grouping commands by my usage frequency:

> cabal help
Command line interface to the Haskell Cabal infrastructure.

See http://www.haskell.org/cabal/ for more information.

Usage: cabal [GLOBAL FLAGS] [COMMAND [FLAGS]]

Commands:
 [all the time]
  build             Compile targets within the project.
  clean             Clean the package store and remove temporary files.
  repl              Open an interactive session for the given component.
  test              Run test-suites

 [occassional]
  update            Updates list of known packages.
  install           Install packages.
  sdist             Generate a source distribution file (.tar.gz).
  haddock           Build Haddock documentation

 [rare]
  help              Help about commands.
  get               Download/Extract a package's source code (repository).
  run               Run an executable.
  check             Check the package for common mistakes.
  freeze            Freeze dependencies.

 [never]
  info              Display detailed information about a particular package.
  list              List packages matching a search string.
  fetch             Downloads packages for later installation.
  user-config       Display and update the user's global cabal configuration.
  init              Create a new .cabal package file.
  configure         Add extra project configuration
  bench             Run benchmarks
  upload            Uploads source packages or documentation to Hackage.
  report            Upload build reports to a remote server.
  gen-bounds        Generate dependency bounds.
  outdated          Check for outdated dependencies
  hscolour          Generate HsColour colourised code, in HTML format.
  exec              Give a command access to the store.
  list-bin          list path to a single executable.
  v2-build          Compile targets within the project.
  v2-configure      Add extra project configuration
  v2-repl           Open an interactive session for the given component.
  v2-run            Run an executable.
  v2-test           Run test-suites
  v2-bench          Run benchmarks
  v2-freeze         Freeze dependencies.
  v2-haddock        Build Haddock documentation
  v2-exec           Give a command access to the store.
  v2-update         Updates list of known packages.
  v2-install        Install packages.
  v2-clean          Clean the package store and remove temporary files.
  v2-sdist          Generate a source distribution file (.tar.gz).
  v1-build          Compile all/specific components.
  v1-configure      Prepare to build the package.
  v1-repl           Open an interpreter session for the given component.
  v1-run            Builds and runs an executable.
  v1-test           Run all/specific tests in the test suite.
  v1-bench          Run all/specific benchmarks.
  v1-freeze         Freeze dependencies.
  v1-haddock        Generate Haddock HTML documentation.
  v1-install        Install packages.
  v1-clean          Clean up after a build.
  v1-copy           Copy the files of all/specific components to install locations.
  v1-register       Register this package with the compiler.
  v1-reconfigure    Reconfigure the package if necessary.

We're showing a list of 50 commands (with acknowledged redundancy and obsolescence) when 4 to 8 commands would top my list by use.

[ulysses4ever]

Would be nice to get back to it, @philderbeast! I'd thread like this:

• strike v2- in the output of (v2-)help
• remove v1-commands from the output of (v2-)help
• introduce v1-help which will show v1- commands (with the prefixes).

---

There's revived interest in more cleanup in this area, see #9086.