Init CLI flag documentation improvement

[emilypi]

See @Mikolaj's comment. The existing docs are there for anyone who issues --help, but it's non-obvious to Haskell developers that they may need help, so this creates a natural conflict.

[ulysses4ever]

I think shoving more stuff in the --help isn't very helpful (although isn't harmful either, so I approve). My impression from that issue thread was that the agreement was that it's the interactive mode who should advertislze the other mode in the very beginning.

cc @AndreasPK

[geekosaur]

I'm neutral on this, FWIW, and agree that we should consider splitting functionality at some point as something more useful than just adjusting help text.

I will note that some programs (notably most of Larry Wall's: original patch, rn, etc.) output their manpages for --help. (But not Perl, because it's a full language and there's like 30 of them at this point and were at least 10 at the original public release.) That's probably overkill, though.

[emilypi]

At the very least, the documentation was stale, so this brings it up to par before we branch off or do whatever.

[ulysses4ever]

Emily, I should have said first that I appreciate your effort before jumping into the negative part. I apologize!

I didn't notice any fixes per se: I thought this patch was purely additive. But I see it now: the part about supplying the root of the project was removed. Thanks!

But since you mentioned documentation, I think these days (and especially due to the AI storm) the online docs are much more important than --help. In general, when updating one, I'd expect an update to the other as well... I have checked https://cabal.readthedocs.io/en/stable/cabal-commands.html#cabal-init now and, sure enough, it looks outdated as well because it appears to be implying the noninteractive default.

[emilypi]

I actually don't know how to modify the readthedocs site fwiw - point me at the repo and I'm sure I'll survive. I can add it to the PR. I don't mind criticism btw - we're in subjective territory here

[ulysses4ever]

right here: https://github.com/haskell/cabal/blob/master/doc/cabal-commands.rst#cabal-init

[emilypi]

@ulysses4ever thanks! updated.

[ulysses4ever]

Great! The formatting and whitespace jobs are failing which is the last thing that needs fixing before the merge bot can take it.

[emilypi]

@ulysses4ever should be fixed now. Nice tool btw

[ulysses4ever]

formatting seems unhappy again, I'm sorry! We use fourmolu-0.12.0.0. An older version always bites people...

also, you can apply a merge label when you're happy with it. The squash label is appropriate here perhaps.

[emilypi]

I'm a fan of the new checks!

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-04-26 22:01 UTC · Rule: default
• ✅ Checks started · on draft merge queue: embarking master (9c13a3e) and #11721 together #11766
• 🚫 Left the queue — 2026-04-26 23:42 UTC · at 579280a83e9f1ab6075c7548219f827368f8e647

This pull request spent 1 hour 40 minutes 55 seconds in the queue, including 1 hour 30 minutes 40 seconds running CI.

Waiting for any of:

• check-neutral = Validate post job
• check-skipped = Validate post job
• check-success = Validate post job

All conditions

• any of [🛡 GitHub branch protection]:
  • check-neutral = Validate post job
  • check-skipped = Validate post job
  • check-success = Validate post job
• #approved-reviews-by >= 2 [🛡 GitHub branch protection]
  • Init CLI flag documentation improvement #11721
• #changes-requested-reviews-by = 0 [🛡 GitHub branch protection]
  • Init CLI flag documentation improvement #11721
• #review-threads-unresolved = 0 [🛡 GitHub branch protection]
  • Init CLI flag documentation improvement #11721
• any of [🛡 GitHub branch protection]:
  • check-success = Doctest Cabal
  • check-neutral = Doctest Cabal
  • check-skipped = Doctest Cabal
• any of [🛡 GitHub branch protection]:
  • check-success = Meta checks
  • check-neutral = Meta checks
  • check-skipped = Meta checks
• any of [🛡 GitHub branch protection]:
  • check-success = docs/readthedocs.org:cabal
  • check-neutral = docs/readthedocs.org:cabal
  • check-skipped = docs/readthedocs.org:cabal
• any of [🛡 GitHub branch protection]:
  • check-success = fourmolu
  • check-neutral = fourmolu
  • check-skipped = fourmolu
• any of [🛡 GitHub branch protection]:
  • check-success = hlint
  • check-neutral = hlint
  • check-skipped = hlint
• any of [🛡 GitHub branch protection]:
  • check-success = Bootstrap post job
  • check-neutral = Bootstrap post job
  • check-skipped = Bootstrap post job
• any of [🛡 GitHub branch protection]:
  • check-success = whitespace
  • check-neutral = whitespace
  • check-skipped = whitespace
• any of [🛡 GitHub branch protection]:
  • check-success = Check sdist post job
  • check-neutral = Check sdist post job
  • check-skipped = Check sdist post job
• any of [🛡 GitHub branch protection]:
  • check-success = Changelogs
  • check-neutral = Changelogs
  • check-skipped = Changelogs

Reason

The merge conditions cannot be satisfied due to failing checks

Failing checks:

• ❌ Validate post job

Hint

You may have to fix your CI before adding the pull request to the queue again.
If you update this pull request, to fix the CI, it will automatically be requeued once the queue conditions match again.
If you think this was a flaky issue instead, you can requeue the pull request, without updating it, by posting a @mergifyio queue comment.