search

haskell / cabal

Official upstream development repository for Cabal and cabal-install
https://haskell.org/cabal
Other
1.63k stars 696 forks source link

Disambiguate docs, `cabal` versus Cabal #9976

Open philderbeast opened 6 months ago

philderbeast commented 6 months ago

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;

$ 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:
philderbeast commented 6 months ago

The command line help could also be included in this review;

$ cabal --help | 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'
9:  user-config            Display and update the user's global cabal configuration.
18:  init                   Create a new cabal package.
33:  haddock-project        Generate Haddocks HTML documentation for the cabal project.
85:   cabal COMMAND --help
116:You can edit the cabal configuration file to set defaults:
mpilgrem commented 6 months ago

For what it is worth, my solution to the problem of achieving consistency with Stack's documentation was (1) to create a glossary (https://docs.haskellstack.org/en/stable/glossary/) and then (2) to apply it consistently to the online, in-app and in-code documentation (in that order of priority). I drew up the first version of the glossary by examining the existing documentation to see how terms were used; the most popular usage had the greatest chance of making it to the glossary, although I also wanted the glossary itself to be coherent.