diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/manual/local.mk | 57 | ||||
| -rw-r--r-- | doc/manual/meson.build | 290 | ||||
| -rwxr-xr-x | doc/manual/process-includes.sh | 32 | ||||
| -rwxr-xr-x | doc/manual/render-manpage.sh | 22 | ||||
| -rw-r--r-- | doc/manual/rl-next/forbid-nested-debuggers.md | 32 |
5 files changed, 386 insertions, 47 deletions
diff --git a/doc/manual/local.mk b/doc/manual/local.mk index b33a4f777..955357607 100644 --- a/doc/manual/local.mk +++ b/doc/manual/local.mk @@ -39,67 +39,30 @@ dummy-env = env -i \ nix-eval = $(dummy-env) $(doc_nix) eval --experimental-features nix-command -I nix/corepkgs=corepkgs --store dummy:// --impure --raw -# re-implement mdBook's include directive to make it usable for terminal output and for proper @docroot@ substitution -define process-includes - while read -r line; do \ - set -euo pipefail; \ - filename="$$(dirname $(1))/$$(sed 's/{{#include \(.*\)}}/\1/'<<< $$line)"; \ - test -f "$$filename" || ( echo "#include-d file '$$filename' does not exist." >&2; exit 1; ); \ - matchline="$$(sed 's|/|\\/|g' <<< $$line)"; \ - sed -i "/$$matchline/r $$filename" $(2); \ - sed -i "s/$$matchline//" $(2); \ - done < <(grep '{{#include' $(1)) -endef - $(d)/nix-env-%.1: $(d)/src/command-ref/nix-env/%.md - @printf "Title: %s\n\n" "$(subst nix-env-,nix-env --,$$(basename "$@" .1))" > $^.tmp - $(render-subcommand) + $(trace-gen) doc/manual/render-manpage.sh \ + --out-no-smarty "$(subst nix-env-,nix-env --,$$(basename "$@" .1))" 1 $^ $^.tmp $@ $(d)/nix-store-%.1: $(d)/src/command-ref/nix-store/%.md - @printf -- 'Title: %s\n\n' "$(subst nix-store-,nix-store --,$$(basename "$@" .1))" > $^.tmp - $(render-subcommand) - -# FIXME: there surely is some more deduplication to be achieved here with even darker Make magic -define render-subcommand - @cat $^ >> $^.tmp - @$(call process-includes,$^,$^.tmp) - $(trace-gen) lowdown -sT man --nroff-nolinks -M section=1 $^.tmp -o $@ - @# fix up `lowdown`'s automatic escaping of `--` - @# https://github.com/kristapsdz/lowdown/blob/edca6ce6d5336efb147321a43c47a698de41bb7c/entity.c#L202 - @sed -i 's/\e\[u2013\]/--/' $@ - @rm $^.tmp -endef + $(trace-gen) doc/manual/render-manpage.sh \ + --out-no-smarty "$(subst nix-store-,nix-store --,$$(basename "$@" .1))" 1 $^ $^.tmp $@ $(d)/%.1: $(d)/src/command-ref/%.md - @printf "Title: %s\n\n" "$$(basename $@ .1)" > $^.tmp - @cat $^ >> $^.tmp - @$(call process-includes,$^,$^.tmp) - $(trace-gen) lowdown -sT man --nroff-nolinks -M section=1 $^.tmp -o $@ - @rm $^.tmp + $(trace-gen) doc/manual/render-manpage.sh "$$(basename $@ .1)" 1 $^ $^.tmp $@ $(d)/%.8: $(d)/src/command-ref/%.md - @printf "Title: %s\n\n" "$$(basename $@ .8)" > $^.tmp - @cat $^ >> $^.tmp - $(trace-gen) lowdown -sT man --nroff-nolinks -M section=8 $^.tmp -o $@ - @rm $^.tmp + $(trace-gen) doc/manual/render-manpage.sh "$$(basename $@ .8)" 8 $^ $^.tmp $@ $(d)/nix.conf.5: $(d)/src/command-ref/conf-file.md - @printf "Title: %s\n\n" "$$(basename $@ .5)" > $^.tmp - @cat $^ >> $^.tmp - @$(call process-includes,$^,$^.tmp) - $(trace-gen) lowdown -sT man --nroff-nolinks -M section=5 $^.tmp -o $@ - @rm $^.tmp + $(trace-gen) doc/manual/render-manpage.sh "$$(basename $@ .5)" 5 $^ $^.tmp $@ $(d)/nix-profiles.5: $(d)/src/command-ref/files/profiles.md - @printf "Title: %s\n\n" "$$(basename $@ .5)" > $^.tmp - @cat $^ >> $^.tmp - $(trace-gen) lowdown -sT man --nroff-nolinks -M section=5 $^.tmp -o $@ - @rm $^.tmp + $(trace-gen) doc/manual/render-manpage.sh "$$(basename $@ .5)" 5 $^ $^.tmp $@ $(d)/src/SUMMARY.md: $(d)/src/SUMMARY.md.in $(d)/src/SUMMARY-rl-next.md $(d)/src/command-ref/new-cli $(d)/src/contributing/experimental-feature-descriptions.md @cp $< $@ - @$(call process-includes,$@,$@) + @doc/manual/process-includes.sh $@ $@ $(d)/src/command-ref/new-cli: $(d)/nix.json $(d)/utils.nix $(d)/generate-manpage.nix $(doc_nix) @rm -rf $@ $@.tmp @@ -201,7 +164,7 @@ $(docdir)/manual/index.html: $(MANUAL_SRCS) $(d)/book.toml $(d)/anchors.jq $(d)/ tmp="$$(mktemp -d)"; \ cp -r doc/manual "$$tmp"; \ find "$$tmp" -name '*.md' | while read -r file; do \ - $(call process-includes,$$file,$$file); \ + doc/manual/process-includes.sh $$file $$file; \ done; \ find "$$tmp" -name '*.md' | while read -r file; do \ docroot="$$(realpath --relative-to="$$(dirname "$$file")" $$tmp/manual/src)"; \ diff --git a/doc/manual/meson.build b/doc/manual/meson.build new file mode 100644 index 000000000..02b707ff3 --- /dev/null +++ b/doc/manual/meson.build @@ -0,0 +1,290 @@ +nix_env_for_docs = { + 'HOME': '/dummy', + 'NIX_CONF_DIR': '/dummy', + 'NIX_SSL_CERT_FILE': '/dummy/no-ca-bundle.crt', + 'NIX_STATE_DIR': '/dummy', + 'NIX_CONFIG': 'cores = 0', +} + +nix_for_docs = [ nix, '--experimental-features', 'nix-command' ] +nix_eval_for_docs = nix_for_docs + [ + 'eval', + '-I', 'nix/corepkgs=corepkgs', + '--store', 'dummy://', + '--impure', + '--raw', +] + +nix_conf_file_json = custom_target( + command : nix_for_docs + [ 'show-config', '--json' ], + capture : true, + output : 'conf-file.json', + env : nix_env_for_docs, +) + +nix_conf_file_md_body = custom_target( + command : nix_eval_for_docs + [ + '--expr', + '(import @INPUT0@).showSettings { inlineHTML = true; } (builtins.fromJSON (builtins.readFile @INPUT1@))', + ], + capture : true, + input : [ + 'utils.nix', + nix_conf_file_json, + ], + output : 'conf-file.md.body', + env : nix_env_for_docs, +) + +nix_conf_file_md = custom_target( + command : [ 'cat', '@INPUT@' ], + capture : true, + input : [ + 'src/command-ref/conf-file-prefix.md', + nix_conf_file_md_body, + ], + output : 'conf-file.md', +) + +nix_exp_features_json = custom_target( + command : [ nix, '__dump-xp-features' ], + capture : true, + output : 'xp-features.json', +) +nix_exp_feature_shortlist = custom_target( + command : nix_eval_for_docs + [ + '--expr', + 'import @INPUT0@ (builtins.fromJSON (builtins.readFile @INPUT1@))', + ], + input : [ + 'generate-xp-features-shortlist.nix', + nix_exp_features_json, + ], + output : 'experimental-features-shortlist.md', + capture : true, + env : nix_env_for_docs, +) + +nix_nested_manpages = [ + [ 'nix-env', + [ + 'delete-generations', + 'install', + 'list-generations', + 'query', + 'rollback', + 'set-flag', + 'set', + 'switch-generation', + 'switch-profile', + 'uninstall', + 'upgrade', + ], + ], + [ 'nix-store', + [ + 'add-fixed', + 'add', + 'delete', + 'dump-db', + 'dump', + 'export', + 'gc', + 'generate-binary-cache-key', + 'import', + 'load-db', + 'optimise', + 'print-env', + 'query', + 'read-log', + 'realise', + 'repair-path', + 'restore', + 'serve', + 'verify', + 'verify-path', + ], + ], +] + +foreach command : nix_nested_manpages + foreach page : command[1] + custom_target( + command : [ + './render-manpage.sh', + '--out-no-smarty', + command[0] + ' --' + page, + '1', + '@INPUT@', + '@OUTPUT@.tmp', + '@OUTPUT@', + ], + input : 'src/command-ref' / command[0] / (page + '.md'), + output : command[0] + '-' + page + '.1', + install : true, + install_dir : mandir / 'man1', + ) + endforeach +endforeach + +nix3_cli_json = custom_target( + command : [ nix, '__dump-cli' ], + capture : true, + output : 'nix.json', +) +nix3_cli_files = custom_target( + command : nix_eval_for_docs + [ + '--write-to', '@OUTPUT@', + '--expr', + 'import @INPUT1@ true (builtins.readFile @INPUT0@)', + ], + input : [ + nix3_cli_json, + 'generate-manpage.nix', + 'utils.nix', + ], + output : 'new-cli', +) + +nix3_manpages = [ + 'nix3-build', + 'nix3-bundle', + 'nix3-copy', + 'nix3-daemon', + 'nix3-derivation-add', + 'nix3-derivation', + 'nix3-derivation-show', + 'nix3-develop', + 'nix3-doctor', + 'nix3-edit', + 'nix3-eval', + 'nix3-flake-archive', + 'nix3-flake-check', + 'nix3-flake-clone', + 'nix3-flake-info', + 'nix3-flake-init', + 'nix3-flake-lock', + 'nix3-flake', + 'nix3-flake-metadata', + 'nix3-flake-new', + 'nix3-flake-prefetch', + 'nix3-flake-show', + 'nix3-flake-update', + 'nix3-fmt', + 'nix3-hash-file', + 'nix3-hash', + 'nix3-hash-path', + 'nix3-hash-to-base16', + 'nix3-hash-to-base32', + 'nix3-hash-to-base64', + 'nix3-hash-to-sri', + 'nix3-help', + 'nix3-help-stores', + 'nix3-key-convert-secret-to-public', + 'nix3-key-generate-secret', + 'nix3-key', + 'nix3-log', + 'nix3-nar-cat', + 'nix3-nar-dump-path', + 'nix3-nar-ls', + 'nix3-nar', + 'nix3-path-info', + 'nix3-print-dev-env', + 'nix3-profile-diff-closures', + 'nix3-profile-history', + 'nix3-profile-install', + 'nix3-profile-list', + 'nix3-profile', + 'nix3-profile-remove', + 'nix3-profile-rollback', + 'nix3-profile-upgrade', + 'nix3-profile-wipe-history', + 'nix3-realisation-info', + 'nix3-realisation', + 'nix3-registry-add', + 'nix3-registry-list', + 'nix3-registry', + 'nix3-registry-pin', + 'nix3-registry-remove', + 'nix3-repl', + 'nix3-run', + 'nix3-search', + 'nix3-shell', + 'nix3-show-config', + 'nix3-store-add-file', + 'nix3-store-add-path', + 'nix3-store-cat', + 'nix3-store-copy-log', + 'nix3-store-copy-sigs', + 'nix3-store-delete', + 'nix3-store-diff-closures', + 'nix3-store-dump-path', + 'nix3-store-gc', + 'nix3-store-ls', + 'nix3-store-make-content-addressed', + 'nix3-store', + 'nix3-store-optimise', + 'nix3-store-path-from-hash-part', + 'nix3-store-ping', + 'nix3-store-prefetch-file', + 'nix3-store-repair', + 'nix3-store-sign', + 'nix3-store-verify', + 'nix3-upgrade-nix', + 'nix3-why-depends', + 'nix', +] + +foreach page : nix3_manpages + custom_target( + command : [ + './render-manpage.sh', + page, + '1', + '@INPUT0@/' + page + '.md', + '@OUTPUT@.tmp', + '@OUTPUT@', + ], + input : nix3_cli_files, + output : page + '.1', + install : true, + install_dir : mandir / 'man1', + ) +endforeach + +nix_manpages = [ + [ 'nix-env', 1 ], + [ 'nix-store', 1 ], + [ 'nix-build', 1 ], + [ 'nix-shell', 1 ], + [ 'nix-instantiate', 1 ], + [ 'nix-collect-garbage', 1 ], + [ 'nix-prefetch-url', 1 ], + [ 'nix-channel', 1 ], + [ 'nix-hash', 1 ], + [ 'nix-copy-closure', 1 ], + [ 'nix.conf', 5, nix_conf_file_md, nix_exp_feature_shortlist ], + [ 'nix-daemon', 8 ], + [ 'nix-profiles', 5, 'src/command-ref/files/profiles.md', nix_exp_feature_shortlist ], +] + +foreach entry : nix_manpages + custom_target( + command : [ + './render-manpage.sh', + entry[0], + entry[1].to_string(), + '@INPUT0@', + '@OUTPUT@.tmp', + '@OUTPUT@', + meson.current_build_dir(), + ], + input : [ + entry.get(2, 'src/command-ref' / (entry[0] + '.md')), + entry.get(3, []), + ], + output : '@0@.@1@'.format(entry[0], entry[1]), + install : true, + install_dir : mandir / 'man@0@'.format(entry[1]), + ) +endforeach diff --git a/doc/manual/process-includes.sh b/doc/manual/process-includes.sh new file mode 100755 index 000000000..51ac67acb --- /dev/null +++ b/doc/manual/process-includes.sh @@ -0,0 +1,32 @@ +#!/bin/sh + +set -euo pipefail + +infile="$1" +outfile="$2" +shift 2 + +# set a search path for includes. the old makefile-based system splorked +# everything into the source tree and was thus able to not have a search +# path, but the meson system generates intermediate files into dedicated +# directories separate from the source. we still retain the implicit old +# behavior for now as the base search path, once meson is the default we +# can revisit this and remove the implicit search path entry. it's fine. +set -- "$(dirname "$infile")" "$@" + +# re-implement mdBook's include directive to make it usable for terminal output and for proper @docroot@ substitution +(grep '{{#include' "$infile" || true) | while read -r line; do + found=false + include="$(printf "$line" | sed 's/{{#include \(.*\)}}/\1/')" + for path in "$@"; do + filename="$path/$include" + if [ -e "$filename" ]; then + found=true + matchline="$(printf "$line" | sed 's|/|\\/|g')" + sed -i "/$matchline/r $filename" "$outfile" + sed -i "s/$matchline//" "$outfile" + break + fi + done + $found || ( echo "#include-d file '$filename' does not exist." >&2; exit 1; ) +done diff --git a/doc/manual/render-manpage.sh b/doc/manual/render-manpage.sh new file mode 100755 index 000000000..42f13911e --- /dev/null +++ b/doc/manual/render-manpage.sh @@ -0,0 +1,22 @@ +#!/bin/sh + +set -euo pipefail + +lowdown_args= + +if [ "$1" = --out-no-smarty ]; then + lowdown_args=--out-no-smarty + shift +fi + +title="$1" +section="$2" +infile="$3" +tmpfile="$4" +outfile="$5" + +printf "Title: %s\n\n" "$title" > "$tmpfile" +cat "$infile" >> "$tmpfile" +"$(dirname "$0")"/process-includes.sh "$infile" "$tmpfile" +lowdown -sT man --nroff-nolinks $lowdown_args -M section="$section" "$tmpfile" -o "$outfile" +rm "$tmpfile" diff --git a/doc/manual/rl-next/forbid-nested-debuggers.md b/doc/manual/rl-next/forbid-nested-debuggers.md new file mode 100644 index 000000000..a5924b24f --- /dev/null +++ b/doc/manual/rl-next/forbid-nested-debuggers.md @@ -0,0 +1,32 @@ +--- +synopsis: Nested debuggers are no longer supported +prs: 9920 +--- + +Previously, evaluating an expression that throws an error in the debugger would +enter a second, nested debugger: + +``` +nix-repl> builtins.throw "what" +error: what + + +Starting REPL to allow you to inspect the current state of the evaluator. + +Welcome to Nix 2.18.1. Type :? for help. + +nix-repl> +``` + +Now, it just prints the error message like `nix repl`: + +``` +nix-repl> builtins.throw "what" +error: + … while calling the 'throw' builtin + at «string»:1:1: + 1| builtins.throw "what" + | ^ + + error: what +``` |