This might be a nice way to use our reach to remind users to donate to
FLOSS projects that they use and love.
Signed-off-by: Ethan Carter Edwards <ethan@ethancedwards.com>
The previous claims are unsourced, since they are not supported by the
source given for CPEs.
Quoting from the 5.3.3.5 section of the NISTIR 7695 document:
> Values for this attribute SHOULD be vendor-specific alphanumeric
> strings characterizing the particular update, service pack, or
> point release of the product.
So, first, they should be ***vendor-specific***, and dare I say,
vendor-specified. But let's not trip on the carpet's flower pattern, and
instead look at evidence from data.
Using the data from `official-cpe-dictionary_v2.3.xml`, gently massaged
into a form that can be queried, we can list all known CPE expressions
for glibc.
There is only one known entry using the `update` field. It's:
```
cpe:2.3:a:gnu:glibc:2.0.5🅱️*:*:*:*:*:*
```
As such, the current example is plainly and demonstrably wrong.
```
SELECT * FROM cpe
WHERE cpe_update != ''
AND cpe_vendor = 'gnu'
AND cpe_product = 'glibc'
ORDER BY cpe_vendor, cpe_product, cpe_version
id |title |cpe_part|cpe_vendor|cpe_product|cpe_version|cpe_update|cpe_edition|cpe_language|cpe_sw_edition|cpe_target_sw|cpe_target_hw|cpe_other|
------+-----------------+--------+----------+-----------+-----------+----------+-----------+------------+--------------+-------------+-------------+---------+
460867|GNU glibc 2.0.5 B|a |gnu |glibc |2.0.5 |b | | | | | | |
```
Let's see good examples of `cpe_product` in contrast:
```
SELECT * FROM cpe
WHERE cpe_update != ''
AND cpe_vendor = 'gnu'
AND cpe_product = 'bash'
ORDER BY cpe_vendor, cpe_product, cpe_version DESC
LIMIT 10
id |title |cpe_part|cpe_vendor|cpe_product|cpe_version|cpe_update|cpe_edition|cpe_language|cpe_sw_edition|cpe_target_sw|cpe_target_hw|cpe_other|
------+--------------------------------------------------------------+--------+----------+-----------+-----------+----------+-----------+------------+--------------+-------------+-------------+---------+
460088|GNU Bourne-Again SHell bash (GNU Bash) 4.3.30 Beta 1 |a |gnu |bash |4.3.30 |beta1 | | | | | | |
460086|GNU Bourne-Again SHell bash (GNU Bash) 4.2.53 Beta 1 |a |gnu |bash |4.2.53 |beta1 | | | | | | |
460081|GNU Bourne-Again SHell bash (GNU Bash) 3.2.57 Beta 1 |a |gnu |bash |3.2.57 |beta1 | | | | | | |
460140|GNU Bourne-Again SHell bash (GNU Bash) 5.2 |a |gnu |bash |5.2 |- | | | | | | |
460141|GNU Bourne-Again SHell bash (GNU Bash) 5.2 Alpha |a |gnu |bash |5.2 |alpha | | | | | | |
460142|GNU Bourne-Again SHell bash (GNU Bash) 5.2 Beta |a |gnu |bash |5.2 |beta | | | | | | |
460143|GNU Bourne-Again SHell bash (GNU Bash) 5.2 Release Candidate 1|a |gnu |bash |5.2 |rc1 | | | | | | |
460144|GNU Bourne-Again SHell bash (GNU Bash) 5.2 Release Candidate 2|a |gnu |bash |5.2 |rc2 | | | | | | |
460145|GNU Bourne-Again SHell bash (GNU Bash) 5.2 Release Candidate 3|a |gnu |bash |5.2 |rc3 | | | | | | |
460146|GNU Bourne-Again SHell bash (GNU Bash) 5.2 Release Candidate 4|a |gnu |bash |5.2 |rc4 | | | | | | |
```
The field could have been simply removed from the list, as it is not
used, but it should be present in that form at least for *some
undefined* length of time to present as a correction for anyone using
the `edition` field mistakenly.
My claim comes from the literal source listed in the next paragraph
(NISTIR 7695), the first few words of `5.3.3.6` are:
> The edition attribute is considered deprecated
Thus we consider it deprecated.
Furthermore the section documents that it should be using the value
`ANY`. It could be considered debatable as `NA` should be used “when
there is no legal or meaningful value for that attribute, or when
that attribute is not used as part of the description”... But the spec
states that `ANY` should be used, so we state `ANY` should be used.
The original wording missed the *not meaningful* nuance, and adding an
`or` clause within the sentence would have made it hard to understand.
Instead, it is now split into a list, and ordered in the same order as
found in `5.3.1` in NISTIR 7695.
The logical name used by the specification (ANY/NA) was also added.
Add `identifiers` attr to `meta` attribute with following attrs:
* `cpe` with the full CPE string when available
* `possibleCPEs` with the list of potential CPEs when not all
information is provided
* `cpeParts` with the destructured CPE string, allowing to override it
whenever needed
* `v1` attribute set with `cpe` and `cpeParts` from above and a
guarantee of a backwards-compatible interface
Related issue: https://github.com/NixOS/nixpkgs/issues/354012
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!
* 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.
