Open
Description
I've been pulled up for being slack with proper name capitalization by pull request reviewers. I had a quick look at the docs and we could be more consistent with how we spell and markup certain common things to disambiguate what we mean, especially since cabal and Cabal are different things.
I'm not sure what is the correct capitalization of package and project. Is it a "Cabal package" and a "Cabal project"?
cabal file
I don't think there is such a thing. Lower case cabal refers to cabal-install:exe:cabal. This executable works with packages and projects. So here are some better options;
.cabalfile- Cabal package description file
- Cabal package description,
.cabalfile
$ grep "\.cabal file" **/*.rst
doc/cabal-commands.rst: Generate a short .cabal file, without extra empty fields or
doc/cabal-commands.rst:paste them into your .cabal file.
doc/cabal-project-description-file.rst:appropriate .cabal file in the version control repository, and allows
doc/how-to-package-haskell-code.rst:Editing the .cabal file
cabal file format
Shouldn't this be "Cabal package description, .cabal file, format" or ".cabal file format"?
$ grep -i "cabal file format" **/*.rst
doc/buildinfo-fields-reference.rst:Field syntax is described as they are in the latest cabal file format version.
doc/buildinfo-fields-reference.rst:Many fields in cabal file format are lists. There are three variations:
doc/cabal-interface-stability.rst:Cabal file format
package file
While I casually refer to .cabal as a package, a .tar.gz is a package file too but containing the whole package and not just its description.
Could we be more explicit, not saying "package file" without qualification? The two qualifications would be "package archive file" and "package description file".
$ grep "package file" **/*.rst
doc/cabal-commands.rst:Run ``cabal check`` in the folder where your ``.cabal`` package file is.
doc/config.rst:It's possible to use a directory of `.tar.gz` package files as a local package
doc/how-to-package-haskell-code.rst:all the package files in one directory, but most packages use one or more
cabal, the executable
When we refer to "cabal", the executable, perhaps mark it up as "cabal" instead?
$ grep "cabal command" **/*.rst
doc/cabal-commands.rst:A cabal command target can take any of the following forms:
cabal followed by non-command text
Some of these search hits, I've already mentioned.
$ git grep --perl-regexp -n 'cabal\s(?!install|build|configure|outdated|run|gen-bounds|get|fetch|update|list-bin|clean|haddock-project|haddock|init|path|test|repl|bench|sdist|upload|check|report|exec|list|info|freeze|help|user-config|unpack)\w' **/*.rst
doc/buildinfo-fields-reference.rst:9:Field syntax is described as they are in the latest cabal file format version.
doc/buildinfo-fields-reference.rst:97:Many fields in cabal file format are lists. There are three variations:
doc/cabal-commands.rst:20: user-config Display and update the user's global cabal configuration.
doc/cabal-commands.rst:30: init Create a new cabal package.
doc/cabal-commands.rst:44: haddock-project Generate Haddocks HTML documentation for the cabal project.
doc/cabal-commands.rst:178: "cabal-lib-version": "<cabal lib version>",
doc/cabal-commands.rst:202: "cabal-file": "<cabal file location>"
doc/cabal-commands.rst:218:A cabal command target can take any of the following forms:
doc/cabal-commands.rst:260:cabal preferences. It is very useful when you are e.g. first configuring
doc/cabal-commands.rst:424: Generate a short .cabal file, without extra empty fields or
doc/cabal-commands.rst:596:paste them into your .cabal file.
doc/cabal-commands.rst:774:When building a script, the executable is cached under the cabal directory.
doc/cabal-commands.rst:1049:The configuration information for the script is cached under the cabal directory
doc/cabal-commands.rst:1097:a cabal flag, so if you need to pass flags to the executable you
doc/cabal-commands.rst:1122:Where there cabal metadata block is mandatory and contains fields from a
doc/cabal-commands.rst:1137:The executable is cached under the cabal directory, and can be pre-built with
doc/cabal-commands.rst:1194: Taking the cabal project as an example that has a ``Cabal-tests`` package
doc/cabal-commands.rst:1337:- ``misplaced-c-opt``: C-like options in wrong cabal field.
doc/cabal-package-description-file.rst:1:Package Description — <package>.cabal File
doc/cabal-package-description-file.rst:1144: following a double dash, all options cabal would pass to ghc for a
doc/cabal-package-description-file.rst:1563: encoded via such ``^>=``-assertions is used by the cabal solver to
doc/cabal-project-description-file.rst:43:As of ``cabal-install`` version 3.8, cabal supports conditional logic and
doc/cabal-project-description-file.rst:81:Using conditionals will force cabal to find a ghc to derive
doc/cabal-project-description-file.rst:212:specifying packages in a remote version control system that cabal should
doc/cabal-project-description-file.rst:241:appropriate .cabal file in the version control repository, and allows
doc/cabal-project-description-file.rst:252: Look in one or more subdirectories of the repository for cabal files, rather than the root.
doc/cabal-project-description-file.rst:299: This option instructs cabal to control parallelism by creating a new system semaphore,
doc/cabal-project-description-file.rst:395: So the initial set of packages which is used by cabal is just the packages
doc/cabal-project-description-file.rst:713: putting cabal in "offline" mode:
doc/cabal-project-description-file.rst:1294: levels that cabal currently supports are:
doc/cabal-project-description-file.rst:1811: :synopsis: Allow cabal to install or upgrade any package.
doc/file-format-changelog.rst:10:changes that occurred in each version of the cabal specification
doc/file-format-changelog.rst:37: following a double dash, all options cabal would pass to ghc for a
doc/how-to-build-like-nix.rst:8:after the ``cabal v2-*`` family of commands that control it. However, those
doc/how-to-package-haskell-code.rst:72:and executable; or: test suite) cabal asks us a number of questions starting with
doc/how-to-package-haskell-code.rst:73:which version of the cabal specification to use, our package's name
doc/how-to-package-haskell-code.rst:126:Editing the .cabal file
doc/setup-commands.rst:692: levels that cabal currently supports are: