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/\."/"/'
`meta.sourceProvenance` has its own level 2 heading at the bottom of the file,
but unlike the other meta-attributes it doesn't have a level 3 heading under the
"Standard meta-attributes" section. Readers looking at the list of subheadings
directly under the "Standard meta-attributes" section header may not realize
that `meta.sourceProvenance` exists unless they scroll down to the bottom of the
page.
This commit adds a level 3 heading for sourceProvenance under "Standard
meta-attributes".
* doc: add stdenv passthru chapter
Broad strokes:
- create the chapter
- move existing stdenv passthru coverage into it
- move out-of-place coverage of passthru.tests from the stdenv meta chapter into it
- (try to) apply 1-sentence-per-line to text I've touched
- add legacy anchors for everything moved
- update existing links to the new anchors
- add tentative motivating text
- make nixpkgs-internal links relative/branchless
razor: if it is only ever needed by contributors, which is likely if links
refer to the latest revision of the source code, then it's for
the contributor guide
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
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!
https://www.pcre.org/
The `pcre` library is "now at end of life, and is no longer being
maintained," according to the upstream maintainers. Accordingly, we
should replace uses of `pcre` with its actively maintained successor,
`pcre2`, wherever possible .
Update instructions for manual build phases execution via `nix-shell` to
cover all phases. There is no easy way of getting those commands, so it
makes a sense to have them all properly documented.
