so that meta.description examples shown in the documentation
align with recommendations given in the "Meta attributes" section
in pkgs/README.md.
The changes were made with the following commands:
nix run nixpkgs#silver-searcher -- -l0 'description\s*=\s*"([Aa]n?|[Tt]he)\s' doc \
| xargs -0 nix run nixpkgs#gnused -- -i '' -Ee '/description/s/"([Aa]n?|[Tt]he)\s(.)/"\U\2/'
nix run nixpkgs#silver-searcher -- -l0 'description\s*=\s*".*\."' doc \
| xargs -0 nix run nixpkgs#gnused -- -i '' -Ee '/description/s/\."/"/'
* ocamlPackages.wtf8: use minimalOCamlVersion
* ocamlPackages.ppx_yojson_conv: minimalOCamlVersion
* ocamlPackages.postgresql: use minimalOCamlVersion
* ocamlPackages.opti: use minimalOCamlVersion
* ocamlPackages.opam-repository: use minimalOCamlVersion
* ocamlPackages.opam-format: use minimalOCamlVersion
* ocamlPackages.lwt-dllist: use minimalOCamlVersion
* ocamlPackages.lacaml: use minimalOCamlVersion
* ocamlPackages.gnuplot: use minimalOCamlVersion
* ocamlPackages.fix: use minimalOCamlVersion
* ocamlPackages.eigen: use minimalOCamlVersion
* ocamlPackages.earley: use minimalOCamlVersion
* ocamlPackages.directories: use minimalOCamlVersion
* ocamlPackages.cpuid: use minimalOCamlVersion
* build-support/ocaml: deprecate minimumOCamlVersion
* build-support/ocaml: deprecate minimumOCamlVersion
---------
Co-authored-by: Vincent Laporte <Vincent.Laporte@gmail.com>
Following [Best Practices](https://nix.dev/guides/best-practices#with-scopes),
`with` is a problematic language construction and should be avoided.
Usually it is employed like a "factorization": `[ X.A X.B X.C X.D ]` is written
`with X; [ A B C D ]`.
However, as shown in the link above, the syntatical rules of `with` are not so
intuitive, and this "distributive rule" is very selective, in the sense that
`with X; [ A B C D ]` is not equivalent to `[ X.A X.B X.C X.D ]`.
However, this factorization is still useful to "squeeze" some code, especially
in lists like `meta.maintainers`.
On the other hand, it becomes less justifiable in bigger scopes. This is
especially true in cases like `with lib;` in the top of expression and in sets
like `meta = with lib; { . . . }`.
That being said, this patch removes most of example code in the current
documentation.
The exceptions are, for now
- doc/functions/generators.section.md
- doc/languages-frameworks/coq.section.md
because, well, they are way more complicated, and I couldn't parse them
mentally - yet another reason why `with` should be avoided!
The nixpkgs manual contains references to both sri hash and explicit
sha256 attributes. This is at best confusing to new users. Since the
final destination is exclusive use of sri hashes, see nixos/rfcs#131,
might as well push new users in that direction gently.
Notable exceptions to sri hash support are builtins.fetchTarball,
cataclysm-dda, coq, dockerTools.pullimage, elixir.override, and
fetchCrate. None, other than builtins.fetchTarball, are fundamentally
incompatible, but all currently accept explicit sha256 attributes as
input. Because adding backwards compatibility is out of scope for this
change, they have been left intact, but migration to sri format has been
made for any using old hash formats.
All hashes have been manually tested to be accurate, and updates were
only made for missing upstream artefacts or bugs.
The current example in the manual no longer builds, mainly because
`useDune2 = true` is required, but also because the inputs have changed.
The new examples are copied verbatim from nixpkgs.
* doc: add function argument order convention
Ordering by usage is the de facto ordering given to arguments. It's
logical, and makes finding argument usage easier. Putting lib first is
common in NixOS modules, so it's reasonable to mirror this in nixpkgs
proper. Additionally, it's not a package as such, has zero dependencies,
and can be found used anywhere in a derivation.
* doc: clean up usage of lib
