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!
* Updates meta.chapter.md with a reference link to the usage of the package description field instead of referring to nix-env
---------
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
pandoc recognizes `::: note` admonitions, nixos-render-docs only
recognizes `::: {.note}`. surprisingly pandoc also emits the correct
docbook tags for `[](#xref)`s, so we can use that too.
* doc/stdenv/meta.chapter.md: document meta.badPlatforms
We don't have any documentation for the `meta.badPlatforms` attribute.
This commit adds documentation for it.
There has been a longstanding ambiguity between `broken` and
`badPlatforms`, which seem to serve overlapping purposes.
This commit adds to the documentation two examples of constraints
which cannot be expressed by `platforms` and `badPlatforms`.
This commit also mentions `NIXPKGS_ALLOW_BROKEN=1` for overriding
`broken`.
without stable ids on headings we cannot generate stable links to these
headings. nrd complains about this, but the current docbook workflow
does not.
a few generated ids remain, mostly in examples and footnotes. most of
the examples are generated by nixdoc (which has since gained MD export
functions, and the MD export does generate IDs).
Promote the `maintainers = with maintainers; [ ]` syntax as that is most common
in nixpkgs, and remove the `nix-env` example which doesn't work like that anymore.
A tricky thing about FreeBSD is that there is no stable ABI across
versions. That means that putting in the version as part of the config
string is paramount.
We have a parsed represenation that separates name versus version to
accomplish this. We include FreeBSD versions 12 and 13 to demonstrate
how it works.
This commit clarifies that the meaning of the `meta.sourceProvenance`
field is independent of and unaffected by the value of the
`meta.license` field. This is based on the intent of the RFC author
as expressed here:
https://github.com/NixOS/nixpkgs/pull/161098#issuecomment-1081270201
This clarification is added for two reasons:
1. If in the future there should be some disagreement about what
`sourceProvenance` to assign to a package, this may help resolve
the disagreement. Any interpretation of `sourceProvenance` which
is influenced by the `meta.license` is clearly an incorrect
interpretation.
2. If it should turn out that it is impossible to disentangle
`sourceProvenance` from `meta.license`, this would indicate the
need for changes to the `sourceProvenance` scheme. That change
might be as simple as replacing the sentence added by this commit
with some other sentence explaining how the two fields influence
each other.
This commit implements the recommendation made in the paragraph of
this comments which begins with "Please say this explicitly...":
https://github.com/NixOS/nixpkgs/pull/161098#issuecomment-1081309089
We are still using Pandoc’s Markdown parser, which differs from CommonMark spec slightly.
Notably:
- Line breaks in lists behave differently.
- Admonitions do not support the simpler syntax https://github.com/jgm/commonmark-hs/issues/75
- The auto_identifiers uses a different algorithm – I made the previous ones explicit.
- Languages (classes) of code blocks cannot contain whitespace so we have to use “pycon” alias instead of Python “console” as GitHub’s linguist
While at it, I also fixed the following issues:
- ShellSesssion was used
- Removed some pointless docbook tags.
