Render short option with arg. #9043

philderbeast · 2023-06-19T01:56:01Z

Any changes that could be relevant to users have been recorded in the changelog.
The documentation has been updated, if necessary (but not set up commands - runhaskell).

I'm not sure a changelog entry is needed but code snippets of the command --help output may need to be updated in the docs.

<  -v, --verbose[=n]              Control verbosity (n is 0--3, default
>  -v[n], --verbose[=n]           Control verbosity (n is 0--3, default
<  -w, --with-compiler=PATH       give the path to a particular compiler
>  -wPATH, --with-compiler=PATH   give the path to a particular compiler
<  -O, --enable-optimization[=n]  Build with optimization (n is 0--2, default is
>  -O[n], --enable-optimization[=n]
>                                 Build with optimization (n is 0--2, default is
<  -f, --flags=FLAGS              Force values for the given flags in Cabal
>  -fFLAGS, --flags=FLAGS         Force values for the given flags in Cabal
<  -c, --constraint=CONSTRAINT    Specify constraints on a package (version,
>  -cCONSTRAINT, --constraint=CONSTRAINT
>                                 Specify constraints on a package (version,
<  -j, --jobs[=NUM]               Run NUM jobs simultaneously (or '$ncpus' if no
>  -j[N], --jobs[=NUM]            Run NUM jobs simultaneously (or '$ncpus' if no

philderbeast · 2023-06-19T01:57:16Z

I stopped short making changes like this:

<  -v, --verbose[=n]              Control verbosity (n is 0--3, default
>  -v[L], --verbose[=LEVEL]       Control verbosity (LEVEL is 0--3, default

ulysses4ever · 2023-06-19T02:18:11Z

Looks great, thank you! One question:

 -j[N], --jobs[=NUM]            Run NUM jobs simultaneously (or '$ncpus' if no

It's a bit strange to have N in one place and NUM in other. And then, the text only mentions NUM.

It does need a changelog because it's a user-visible change.

philderbeast · 2023-06-19T09:46:48Z

Thanks @ulysses4ever for the question using N for abbreviating NUM. I'm not doing that anymore.

-jNUM, --jobs[=NUM]

philderbeast · 2023-06-19T10:06:09Z

In going through the docs I'm seeing inconsistencies in the short option handling spaces, some options allow it and some don't (those that have a default value?).

$ cabal run cabal build Cabal-syntax -- -v3
Warning: this is a debug build of cabal-install with assertions enabled.
Searching for curl in path.
Found curl at /usr/bin/curl
Searching for powershell in path.
...

$ cabal run cabal build Cabal-syntax -- -v 3
Resolving dependencies...
Warning: this is a debug build of cabal-install with assertions enabled.
...
Error: cabal: Unknown target '3'.
There is no component '3'.
The project has no package '3'.

$ cabal run cabal build Cabal-syntax -- -wghc-8.2.2
Warning: this is a debug build of cabal-install with assertions enabled.
Resolving dependencies...
Error: cabal: Could not resolve dependencies:
...
[__2] fail (backjumping, conflict set: Cabal, base, time)
After searching the rest of the dependency tree exhaustively, these were the
goals I've had most trouble fulfilling: time, Cabal, base

$ cabal run cabal build Cabal-syntax -- -w ghc-8.2.2
Warning: this is a debug build of cabal-install with assertions enabled.
Resolving dependencies...
Error: cabal: Could not resolve dependencies:
...
[__2] fail (backjumping, conflict set: Cabal, base, time)
After searching the rest of the dependency tree exhaustively, these were the
goals I've had most trouble fulfilling: time, Cabal, base

philderbeast · 2023-06-19T12:47:18Z

It would be nice if the short options could parse the = like the long options do:

<  -v, --verbose[=n]              Control verbosity (n is 0--3, default
>  -vn, --verbose[=n]             Control verbosity (n is 0--3, default
<  -w, --with-compiler=PATH       give the path to a particular compiler
>  -w PATH or -wPATH (but not -w=PATH), --with-compiler=PATH
>                                 give the path to a particular compiler
<  -O, --enable-optimization[=n]  Build with optimization (n is 0--2, default is
>  -On, --enable-optimization[=n]
>                                 Build with optimization (n is 0--2, default is
<  -f, --flags=FLAGS              Force values for the given flags in Cabal
>  -f FLAGS or -fFLAGS (but not -f=FLAGS), --flags=FLAGS
>                                 Force values for the given flags in Cabal
<  -c, --constraint=CONSTRAINT    Specify constraints on a package (version,
>  -c CONSTRAINT or -cCONSTRAINT (but not -c=CONSTRAINT), --constraint=CONSTRAINT
>                                 Specify constraints on a package (version,
<  -j, --jobs[=NUM]               Run NUM jobs simultaneously (or '$ncpus' if no
>  -jNUM (but not -j=NUM), --jobs[=NUM]
>                                 Run NUM jobs simultaneously (or '$ncpus' if no

philderbeast · 2023-06-19T14:11:58Z

As it is now (without the buts):

<  -v, --verbose[=n]              Control verbosity (n is 0--3, default
>  -v[n], --verbose[=n]           Control verbosity (n is 0--3, default
<  -w, --with-compiler=PATH       give the path to a particular compiler
>  -w PATH or -wPATH, --with-compiler=PATH
>                                 give the path to a particular compiler
<  -O, --enable-optimization[=n]  Build with optimization (n is 0--2, default is
>  -O[n], --enable-optimization[=n]
>                                 Build with optimization (n is 0--2, default is
<  -f, --flags=FLAGS              Force values for the given flags in Cabal
>  -f FLAGS or -fFLAGS, --flags=FLAGS
>                                 Force values for the given flags in Cabal
<  -c, --constraint=CONSTRAINT    Specify constraints on a package (version,
>  -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT
>                                 Specify constraints on a package (version,
<  -j, --jobs[=NUM]               Run NUM jobs simultaneously (or '$ncpus' if no
>  -j[NUM], --jobs[=NUM]          Run NUM jobs simultaneously (or '$ncpus' if no

ulysses4ever · 2023-07-05T02:32:00Z

Great job here! How about a changelog?

philderbeast · 2023-07-05T19:48:24Z

There's a lot of places in the *.rst docs where we could make changes (grep -\S+= 197 results in 7 files) but I don't know what is the best option (pun intended). Should we:

Delete the short option from the docs, relying on the command line to show it?
Show the short option "as rendered" in the docs where they are now and add short options that are missing?

Regardless of choosing 1 or 2, we might also add a new section to the docs describing how short options and long options are placed with regard their arguments, space or no space, equals permitted or not?

ulysses4ever · 2023-07-09T01:20:02Z

@philderbeast I'm sorry but I can't quite get 1 and 2 and difference between. An example could help. Also, the question you're posing sounds like something that other projects like cabal have solved before. Could you look what GHC / stack / rustc / cargo do and pick something more popular?

As for a new section -- I'm sure everyone will be happy to have documentation extended.

This shows that there is no space and no equal in the short form, haskell#8785.

Add the (but not -opt=arg) for short flags.

philderbeast · 2023-07-10T01:23:03Z

@ulysses4ever I went through and updated what was there already in the docs keeping it in line with the --help output.

doc/cabal-commands.rst

ulysses4ever · 2023-07-10T01:43:16Z

doc/cabal-project.rst

@@ -1536,7 +1539,7 @@ Advanced global configuration options
 -------------------------------------

 .. cfg-field:: write-ghc-environment-files: always, never, or ghc8.4.4+
-               --write-ghc-environment-files=policy
+               --write-ghc-environment-files=always\|never\|ghc8.4.4+


Not sure why it's not simply --write-ghc-environment-files=POLICY, i.e. why inline the options that are listed just one line above.

Do you want me to update the command output to use POLICY? This is what we have right now:

--write-ghc-environment-files=always|never|ghc8.4.4+ Whether to create a .ghc.environment file after a successful build (v2-build only)

changelog.d/issue-8785

ulysses4ever · 2023-07-10T01:47:13Z

doc/cabal-commands.rst

@@ -377,7 +377,7 @@ folder. By default the latest version of the package is downloaded, you can
 ask for a spefic one by adding version numbers
 (``cabal get random-1.0.0.1``).

-.. option:: -s, --source-repository[=head|this|...]]
+.. option:: -s[[head|this|...]], --source-repository[=[head|this|...]]


Does it have to have double braces in -s[[head|this|...]]? I'd think that one pair is enough.

I grabbed what was rendered as-is from the console.

ulysses4ever · 2023-07-10T01:48:22Z

doc/cabal-commands.rst

-.. option:: --v1-freeze-file
+.. option:: --freeze-file


I'm not sure about this change. I think cabal outdated does work only with v1-things.

This is what we have rendered:

ghci> :main outdated --help Check for outdated dependencies. Usage: <interactive> outdated [FLAGS] [PACKAGES] Checks for outdated dependencies in the package description file or freeze file Flags for outdated: -h, --help Show this help text --project-dir=DIR Set the path of the project directory --project-file=FILE Set the path of the cabal.project file (relative to the project directory when relative) -v[n], --verbose[=n] Control verbosity (n is 0--3, default verbosity level is 1) --freeze-file Act on the freeze file --v2-freeze-file Act on the new-style freeze file (default: cabal.project.freeze) --simple-output Only print names of outdated dependencies, one per line --exit-code Exit with non-zero when there are outdated dependencies -q, --quiet Don't print any output. Implies '--exit-code' and '-v0' --ignore=PKGS Packages to ignore --minor[=PKGS] Ignore major version bumps for these packages

ulysses4ever · 2023-07-10T01:54:01Z

doc/cabal-commands.rst


    Both of these commands do the same thing as the above, but only expose ``base``,
    ``vector``, and the ``vector`` package's transitive dependencies even if the user
    is in a project context.

    ::

-        $ cabal repl --ignore-project --build-depends "vector >= 0.12 && < 0.13"
-        $ cabal repl --project='' --build-depends "vector >= 0.12 && < 0.13"
+        $ cabal repl --ignore-project --build-depends="vector >= 0.12 && < 0.13"


Does it not work with just a space? I thought it does, and I actually use space more often because it's usually easier to reach than =. So, I'm not sure this is that good of a change.

Can we say somewhere that space is admissible in the long form? Also, in -b DEPENDENCIES or -bDEPENDENCIES I'd leave just one and say somewhere that the other is admissible.

The --build-depends does work without the = (with the ) but the --jobs of cabal build all --jobs 1 doesn't so to be on the safe side I used = for long options (and for consistency to match the --help output). Are there any long options that don't work with = (in the "space" where some people might use )?

ulysses4ever · 2023-07-10T01:55:19Z

doc/cabal-commands.rst


-    Set verbosity level (0–3, default is 1).
+    Control verbosity (n is 0--3, default verbosity level is 1).


Does our doc engine support things like --? I'm afraid that you need to manually insert the –.

Seems to render better than expected:

https://cabal--9043.org.readthedocs.build/en/9043/cabal-commands.html#cmdoption-v-n

Perhaps the 0--3 in the console is the mistake (an artifact)? I've never seen that before verbatim in plain text when 0..3 seems the more usual (or even 0-3).

I see that -- is converted to en-dash by smart quotes of sphinx.

doc/cabal-commands.rst

ulysses4ever

Terrific! I left a bunch of comments but they're not critical. We'll need to search for a second reviewer...

* WARNING: unknown option: '--prog-option' * WARNING: unknown option: '--prog-options'

ulysses4ever · 2023-07-12T13:44:43Z

Doing a massive review request from @andreabedini @Mikolaj @Kleidukos @ffaf1 @geekosaur because this has been lingering for a while.

ulysses4ever · 2023-07-14T23:27:51Z

Merge delay has passed. Thanks everyone who took a look at it and OKed it, and of course, to the author!

Since GitHub doesn't support updating other people's branches in forks belonging to organizational accounts, I'll have to merge it manually (#9108 will improve this workflow a bit, hopefully).

Backport. This patch is mostly about documentation, but it touches the code related to cabal flags. Therefore, I think it doesn't qualify for a backport. Just to be on the safe side.

ulysses4ever added the attention: needs-review label Jun 19, 2023

philderbeast force-pushed the render-short-option-with-arg branch from b8cb804 to 55d4a50 Compare June 19, 2023 12:54

ulysses4ever added the blocked: decision-needed label Jul 9, 2023

philderbeast added 10 commits July 9, 2023 17:18

Render short required and optional options with abbreviated ARG.

fd21442

This shows that there is no space and no equal in the short form, haskell#8785.

Like for long options use [_] to show these as optional.

82404ca

Don't abbreviate required arguments and say why.

8f3d867

Satisfy fourmolu.

b937e41

Don't abbreviate the option argument.

e29012a

Vary display of short option if it has a default value.

d1ef7d7

Add the (but not -opt=arg) for short flags.

Add haddocks to fmtShort and fmtLong.

ebbcf74

Change the default value from Maybe String to String.

4b32014

Add a changelog entry.

82e7afb

Update command docs to match command --help

bf70d7e

philderbeast force-pushed the render-short-option-with-arg branch from da46ac0 to 134853d Compare July 10, 2023 01:19

ulysses4ever removed the blocked: decision-needed label Jul 10, 2023

ulysses4ever reviewed Jul 10, 2023

View reviewed changes

doc/cabal-commands.rst Show resolved Hide resolved

ulysses4ever reviewed Jul 10, 2023

View reviewed changes

changelog.d/issue-8785 Show resolved Hide resolved

ulysses4ever reviewed Jul 10, 2023

View reviewed changes

doc/cabal-commands.rst Show resolved Hide resolved

ulysses4ever approved these changes Jul 10, 2023

View reviewed changes

philderbeast added 2 commits July 9, 2023 22:00

Update project docs to match --help

0f428e5

Update set up commands to match --help

5aea5dd

philderbeast force-pushed the render-short-option-with-arg branch from 134853d to 5aea5dd Compare July 10, 2023 02:00

philderbeast added 2 commits July 9, 2023 22:26

Shorten the diff in the change log entry

f01a604

References are case-sensitive

aaa058a

* WARNING: unknown option: '--prog-option' * WARNING: unknown option: '--prog-options'

ulysses4ever requested review from Mikolaj, geekosaur, Kleidukos and ffaf1 July 12, 2023 13:43

ulysses4ever requested a review from andreabedini July 12, 2023 13:44

Kleidukos approved these changes Jul 12, 2023

View reviewed changes

ulysses4ever added the squash+merge me Tell Mergify Bot to squash-merge label Jul 12, 2023

geekosaur approved these changes Jul 12, 2023

View reviewed changes

mergify bot added the merge delay passed Applied (usually by Mergify) when PR approved and received no updates for 2 days label Jul 14, 2023

ulysses4ever merged commit ca5d19f into haskell:master Jul 14, 2023
42 of 44 checks passed

ulysses4ever removed the attention: needs-review label Jul 14, 2023

philderbeast mentioned this pull request Oct 18, 2023

Add back reference from constraints to flags #9264

Merged

1 task

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Render short option with arg. #9043

Render short option with arg. #9043

philderbeast commented Jun 19, 2023 •

edited

Loading

philderbeast commented Jun 19, 2023

ulysses4ever commented Jun 19, 2023

philderbeast commented Jun 19, 2023

philderbeast commented Jun 19, 2023

philderbeast commented Jun 19, 2023 •

edited

Loading

philderbeast commented Jun 19, 2023

ulysses4ever commented Jul 5, 2023

philderbeast commented Jul 5, 2023

ulysses4ever commented Jul 9, 2023

philderbeast commented Jul 10, 2023 •

edited

Loading

ulysses4ever Jul 10, 2023

philderbeast Jul 10, 2023

ulysses4ever Jul 10, 2023

philderbeast Jul 10, 2023

ulysses4ever Jul 10, 2023

philderbeast Jul 10, 2023

ulysses4ever Jul 10, 2023

philderbeast Jul 10, 2023 •

edited

Loading

ulysses4ever Jul 10, 2023

philderbeast Jul 10, 2023

philderbeast Jul 10, 2023

ulysses4ever left a comment

ulysses4ever commented Jul 12, 2023 •

edited

Loading

ulysses4ever commented Jul 14, 2023


		Set verbosity level (0–3, default is 1).
		Control verbosity (n is 0--3, default verbosity level is 1).

Render short option with arg. #9043

Render short option with arg. #9043

Conversation

philderbeast commented Jun 19, 2023 • edited Loading

philderbeast commented Jun 19, 2023

ulysses4ever commented Jun 19, 2023

philderbeast commented Jun 19, 2023

philderbeast commented Jun 19, 2023

philderbeast commented Jun 19, 2023 • edited Loading

philderbeast commented Jun 19, 2023

ulysses4ever commented Jul 5, 2023

philderbeast commented Jul 5, 2023

ulysses4ever commented Jul 9, 2023

philderbeast commented Jul 10, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

philderbeast Jul 10, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ulysses4ever left a comment

Choose a reason for hiding this comment

ulysses4ever commented Jul 12, 2023 • edited Loading

ulysses4ever commented Jul 14, 2023

philderbeast commented Jun 19, 2023 •

edited

Loading

philderbeast commented Jun 19, 2023 •

edited

Loading

philderbeast commented Jul 10, 2023 •

edited

Loading

philderbeast Jul 10, 2023 •

edited

Loading

ulysses4ever commented Jul 12, 2023 •

edited

Loading