From 5f07f2ff2b964bec71be34cf6cf1265ce88b7490 Mon Sep 17 00:00:00 2001
From: Alyssa Ross <hi@alyssa.is>
Date: Wed, 5 May 2021 13:56:23 +0000
Subject: [PATCH] doc: builtins: use a definition list
This looks a lot better (and is also more semantically meaningful).
Since this list is generated in a Nix expression, I don't think using
HTML here is going to be the thing that puts people off modifying this
part of the documentation!
---
doc/manual/generate-builtins.nix | 10 ++++++----
doc/manual/local.mk | 1 +
doc/manual/src/expressions/builtins-prefix.md | 9 +++++----
doc/manual/src/expressions/builtins-suffix.md | 1 +
4 files changed, 13 insertions(+), 8 deletions(-)
create mode 100644 doc/manual/src/expressions/builtins-suffix.md
diff --git a/doc/manual/generate-builtins.nix b/doc/manual/generate-builtins.nix
index 416a7fdba..92c7b1a31 100644
--- a/doc/manual/generate-builtins.nix
+++ b/doc/manual/generate-builtins.nix
@@ -6,9 +6,11 @@ builtins:
concatStrings (map
(name:
let builtin = builtins.${name}; in
- " - `builtins.${name}` " + concatStringsSep " " (map (s: "*${s}*") builtin.args)
- + " \n\n"
- + concatStrings (map (s: " ${s}\n") (splitLines builtin.doc)) + "\n\n"
+ "<dt><code>${name} "
+ + concatStringsSep " " (map (s: "<var>${s}</var>") builtin.args)
+ + "</code></dt>"
+ + "<dd>\n\n"
+ + builtin.doc
+ + "\n\n</dd>"
)
(attrNames builtins))
-
diff --git a/doc/manual/local.mk b/doc/manual/local.mk
index 271529b38..e25157af8 100644
--- a/doc/manual/local.mk
+++ b/doc/manual/local.mk
@@ -64,6 +64,7 @@ $(d)/conf-file.json: $(bindir)/nix
$(d)/src/expressions/builtins.md: $(d)/builtins.json $(d)/generate-builtins.nix $(d)/src/expressions/builtins-prefix.md $(bindir)/nix
@cat doc/manual/src/expressions/builtins-prefix.md > $@.tmp
$(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-builtins.nix (builtins.fromJSON (builtins.readFile $<))' >> $@.tmp
+ @cat doc/manual/src/expressions/builtins-suffix.md >> $@.tmp
@mv $@.tmp $@
$(d)/builtins.json: $(bindir)/nix
diff --git a/doc/manual/src/expressions/builtins-prefix.md b/doc/manual/src/expressions/builtins-prefix.md
index c16b2805f..87127de2a 100644
--- a/doc/manual/src/expressions/builtins-prefix.md
+++ b/doc/manual/src/expressions/builtins-prefix.md
@@ -9,7 +9,8 @@ scope. Instead, you can access them through the `builtins` built-in
value, which is a set that contains all built-in functions and values.
For instance, `derivation` is also available as `builtins.derivation`.
- - `derivation` *attrs*; `builtins.derivation` *attrs*\
-
- `derivation` is described in [its own section](derivations.md).
-
+<dl>
+ <dt><code>derivation <var>attrs</var></code>;
+ <code>builtins.derivation <var>attrs</var></code></dt>
+ <dd><p><var>derivation</var> in described in
+ <a href="derivations.md">its own section</a>.</p></dd>
diff --git a/doc/manual/src/expressions/builtins-suffix.md b/doc/manual/src/expressions/builtins-suffix.md
new file mode 100644
index 000000000..a74db2857
--- /dev/null
+++ b/doc/manual/src/expressions/builtins-suffix.md
@@ -0,0 +1 @@
+</dl>
--
GitLab