Update doc/stdenv/meta.chapter.md

Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>

1 files changed, 17 insertions, 1 deletions

diff --git a/doc/stdenv/meta.chapter.md b/doc/stdenv/meta.chapter.md
index 6f58648cdf5db..1ce44a9065feb 100644
--- a/doc/stdenv/meta.chapter.md
+++ b/doc/stdenv/meta.chapter.md
@@ -185,7 +185,23 @@ meta.hydraPlatforms = [];
 If set to `true`, the package is marked as "broken", meaning that it won’t show up in [search.nixos.org](https://search.nixos.org/packages), and cannot be built or installed unless the environment variable [`NIXPKGS_ALLOW_BROKEN`](#opt-allowBroken) is set.
 Such unconditionally-broken packages should be removed from Nixpkgs eventually unless they are fixed.
 
-The value of this attribute can depend on a package's arguments, including `stdenv`.  This means that `broken` can be used to express constraints such as "does not cross compile" (`meta.broken = !(stdenv.buildPlatform.canExecute stdenv.hostPlatform)`) or "broken if all of a certain set of its dependencies are broken".  This makes `broken` strictly more powerful than `meta.badPlatforms`.  However `meta.availableOn` currently examines only `meta.platforms` and `meta.badPlatforms`, so `meta.broken` does not influence the default values for optional dependencies.
+The value of this attribute can depend on a package's arguments, including `stdenv`. 
+This means that `broken` can be used to express constraints, for example:
+
+- Does not cross compile
+
+  ```nix
+   meta.broken = !(stdenv.buildPlatform.canExecute stdenv.hostPlatform)
+  ```
+
+- Broken if all of a certain set of its dependencies are broken
+
+  ```nix
+  meta.broken = lib.all (map (p: p.meta.broken) [ glibc musl ])
+  ```
+
+This makes `broken` strictly more powerful than `meta.badPlatforms`.
+However `meta.availableOn` currently examines only `meta.platforms` and `meta.badPlatforms`, so `meta.broken` does not influence the default values for optional dependencies.
 
 ## Licenses {#sec-meta-license}