From 72428e38d904a1db746f37c8727ab7b0fbb457bc Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Wed, 2 Dec 2020 23:05:28 +0100 Subject: Generate separate manpages for each nix subcommand --- .gitignore | 3 +- doc/manual/generate-manpage.nix | 50 +++++++++++++------ doc/manual/local.mk | 28 ++++++++--- doc/manual/src/SUMMARY.md | 105 ---------------------------------------- doc/manual/src/SUMMARY.md.in | 105 ++++++++++++++++++++++++++++++++++++++++ 5 files changed, 162 insertions(+), 129 deletions(-) delete mode 100644 doc/manual/src/SUMMARY.md create mode 100644 doc/manual/src/SUMMARY.md.in diff --git a/.gitignore b/.gitignore index c51582cf0..37aada307 100644 --- a/.gitignore +++ b/.gitignore @@ -18,7 +18,8 @@ perl/Makefile.config /doc/manual/nix.json /doc/manual/conf-file.json /doc/manual/builtins.json -/doc/manual/src/command-ref/nix.md +/doc/manual/src/SUMMARY.md +/doc/manual/src/command-ref/new-cli /doc/manual/src/command-ref/conf-file.md /doc/manual/src/expressions/builtins.md diff --git a/doc/manual/generate-manpage.nix b/doc/manual/generate-manpage.nix index db266750a..2801e96fa 100644 --- a/doc/manual/generate-manpage.nix +++ b/doc/manual/generate-manpage.nix @@ -1,34 +1,40 @@ +command: + with builtins; with import ./utils.nix; let showCommand = - { command, section, def }: - "${section} Name\n\n" + { command, def, filename }: + "# Name\n\n" + "`${command}` - ${def.description}\n\n" - + "${section} Synopsis\n\n" + + "# Synopsis\n\n" + showSynopsis { inherit command; args = def.args; } + + (if def.commands or {} != {} + then + "where *subcommand* is one of the following:\n\n" + # FIXME: group by category + + concatStrings (map (name: + "* [`${command} ${name}`](./${appendName filename name}.md) - ${def.commands.${name}.description}\n") + (attrNames def.commands)) + + "\n" + else "") + (if def ? doc - then "${section} Description\n\n" + def.doc + "\n\n" + then "# Description\n\n" + def.doc + "\n\n" else "") + (let s = showFlags def.flags; in if s != "" - then "${section} Flags\n\n${s}" + then "# Flags\n\n${s}" else "") + (if def.examples or [] != [] then - "${section} Examples\n\n" + "# Examples\n\n" + concatStrings (map ({ description, command }: "${description}\n\n```console\n${command}\n```\n\n") def.examples) - else "") - + (if def.commands or [] != [] - then concatStrings ( - map (name: - "# Subcommand `${command} ${name}`\n\n" - + showCommand { command = command + " " + name; section = "##"; def = def.commands.${name}; }) - (attrNames def.commands)) else ""); + appendName = filename: name: (if filename == "nix" then "nix3" else filename) + "-" + name; + showFlags = flags: concatStrings (map (longName: @@ -48,8 +54,20 @@ let "`${command}` [*flags*...] ${concatStringsSep " " (map (arg: "*${arg.label}*" + (if arg ? arity then "" else "...")) args)}\n\n"; -in + processCommand = { command, def, filename }: + [ { name = filename + ".md"; value = showCommand { inherit command def filename; }; inherit command; } ] + ++ concatMap + (name: processCommand { + filename = appendName filename name; + command = command + " " + name; + def = def.commands.${name}; + }) + (attrNames def.commands or {}); -command: +in -showCommand { command = "nix"; section = "#"; def = command; } +let + manpages = processCommand { filename = "nix"; command = "nix"; def = command; }; + summary = concatStrings (map (manpage: " - [${manpage.command}](command-ref/new-cli/${manpage.name})\n") manpages); +in +(listToAttrs manpages) // { "SUMMARY.md" = summary; } diff --git a/doc/manual/local.mk b/doc/manual/local.mk index bb8b3b60a..b40fa4ed2 100644 --- a/doc/manual/local.mk +++ b/doc/manual/local.mk @@ -4,7 +4,7 @@ MANUAL_SRCS := $(call rwildcard, $(d)/src, *.md) # Generate man pages. man-pages := $(foreach n, \ - nix-env.1 nix-build.1 nix-shell.1 nix-store.1 nix-instantiate.1 nix.1 \ + nix-env.1 nix-build.1 nix-shell.1 nix-store.1 nix-instantiate.1 \ nix-collect-garbage.1 \ nix-prefetch-url.1 nix-channel.1 \ nix-hash.1 nix-copy-closure.1 \ @@ -22,7 +22,7 @@ dummy-env = env -i \ NIX_SSL_CERT_FILE=/dummy/no-ca-bundle.crt \ NIX_STATE_DIR=/dummy -nix-eval = $(dummy-env) $(bindir)/nix eval --experimental-features nix-command -I nix/corepkgs=corepkgs --store dummy:// --impure --raw --expr +nix-eval = $(dummy-env) $(bindir)/nix eval --experimental-features nix-command -I nix/corepkgs=corepkgs --store dummy:// --impure --raw $(d)/%.1: $(d)/src/command-ref/%.md @printf "Title: %s\n\n" "$$(basename $@ .1)" > $^.tmp @@ -42,13 +42,17 @@ $(d)/nix.conf.5: $(d)/src/command-ref/conf-file.md $(trace-gen) lowdown -sT man $^.tmp -o $@ @rm $^.tmp -$(d)/src/command-ref/nix.md: $(d)/nix.json $(d)/generate-manpage.nix $(bindir)/nix - $(trace-gen) $(nix-eval) 'import doc/manual/generate-manpage.nix (builtins.fromJSON (builtins.readFile $<))' > $@.tmp +$(d)/src/SUMMARY.md: $(d)/src/SUMMARY.md.in $(d)/src/command-ref/new-cli + $(trace-gen) cat doc/manual/src/SUMMARY.md.in | while IFS= read line; do if [[ $$line = @manpages@ ]]; then cat doc/manual/src/command-ref/new-cli/SUMMARY.md; else echo "$$line"; fi; done > $@.tmp @mv $@.tmp $@ +$(d)/src/command-ref/new-cli: $(d)/nix.json $(d)/generate-manpage.nix $(bindir)/nix + @rm -rf $@ + $(trace-gen) $(nix-eval) --write-to $@ --expr 'import doc/manual/generate-manpage.nix (builtins.fromJSON (builtins.readFile $<))' + $(d)/src/command-ref/conf-file.md: $(d)/conf-file.json $(d)/generate-options.nix $(d)/src/command-ref/conf-file-prefix.md $(bindir)/nix @cat doc/manual/src/command-ref/conf-file-prefix.md > $@.tmp - $(trace-gen) $(nix-eval) 'import doc/manual/generate-options.nix (builtins.fromJSON (builtins.readFile $<))' >> $@.tmp + $(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-options.nix (builtins.fromJSON (builtins.readFile $<))' >> $@.tmp @mv $@.tmp $@ $(d)/nix.json: $(bindir)/nix @@ -61,7 +65,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) 'import doc/manual/generate-builtins.nix (builtins.fromJSON (builtins.readFile $<))' >> $@.tmp + $(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-builtins.nix (builtins.fromJSON (builtins.readFile $<))' >> $@.tmp @mv $@.tmp $@ $(d)/builtins.json: $(bindir)/nix @@ -71,7 +75,17 @@ $(d)/builtins.json: $(bindir)/nix # Generate the HTML manual. install: $(docdir)/manual/index.html -$(docdir)/manual/index.html: $(MANUAL_SRCS) $(d)/book.toml $(d)/custom.css $(d)/src/command-ref/nix.md $(d)/src/command-ref/conf-file.md $(d)/src/expressions/builtins.md +# Generate 'nix' manpages. +install: $(d)/src/command-ref/new-cli + for i in doc/manual/src/command-ref/new-cli/*.md; do \ + name=$$(basename $$i .md); \ + if [[ $$name = SUMMARY ]]; then continue; fi; \ + printf "Title: %s\n\n" "$$name" > $$i.tmp; \ + cat $$i >> $$i.tmp; \ + lowdown -sT man $$i.tmp -o $(mandir)/man1/$$name.1; \ + done + +$(docdir)/manual/index.html: $(MANUAL_SRCS) $(d)/book.toml $(d)/custom.css $(d)/src/SUMMARY.md $(d)/src/command-ref/new-cli $(d)/src/command-ref/conf-file.md $(d)/src/expressions/builtins.md $(trace-gen) mdbook build doc/manual -d $(docdir)/manual @cp doc/manual/highlight.pack.js $(docdir)/manual/highlight.js diff --git a/doc/manual/src/SUMMARY.md b/doc/manual/src/SUMMARY.md deleted file mode 100644 index 8281f683f..000000000 --- a/doc/manual/src/SUMMARY.md +++ /dev/null @@ -1,105 +0,0 @@ -# Table of Contents - -- [Introduction](introduction.md) -- [Quick Start](quick-start.md) -- [Installation](installation/installation.md) - - [Supported Platforms](installation/supported-platforms.md) - - [Installing a Binary Distribution](installation/installing-binary.md) - - [Installing Nix from Source](installation/installing-source.md) - - [Prerequisites](installation/prerequisites-source.md) - - [Obtaining a Source Distribution](installation/obtaining-source.md) - - [Building Nix from Source](installation/building-source.md) - - [Security](installation/nix-security.md) - - [Single-User Mode](installation/single-user.md) - - [Multi-User Mode](installation/multi-user.md) - - [Environment Variables](installation/env-variables.md) - - [Upgrading Nix](installation/upgrading.md) -- [Package Management](package-management/package-management.md) - - [Basic Package Management](package-management/basic-package-mgmt.md) - - [Profiles](package-management/profiles.md) - - [Garbage Collection](package-management/garbage-collection.md) - - [Garbage Collector Roots](package-management/garbage-collector-roots.md) - - [Channels](package-management/channels.md) - - [Sharing Packages Between Machines](package-management/sharing-packages.md) - - [Serving a Nix store via HTTP](package-management/binary-cache-substituter.md) - - [Copying Closures via SSH](package-management/copy-closure.md) - - [Serving a Nix store via SSH](package-management/ssh-substituter.md) - - [Serving a Nix store via S3](package-management/s3-substituter.md) -- [Writing Nix Expressions](expressions/writing-nix-expressions.md) - - [A Simple Nix Expression](expressions/simple-expression.md) - - [Expression Syntax](expressions/expression-syntax.md) - - [Build Script](expressions/build-script.md) - - [Arguments and Variables](expressions/arguments-variables.md) - - [Building and Testing](expressions/simple-building-testing.md) - - [Generic Builder Syntax](expressions/generic-builder.md) - - [Writing Nix Expressions](expressions/expression-language.md) - - [Values](expressions/language-values.md) - - [Language Constructs](expressions/language-constructs.md) - - [Operators](expressions/language-operators.md) - - [Derivations](expressions/derivations.md) - - [Advanced Attributes](expressions/advanced-attributes.md) - - [Built-in Constants](expressions/builtin-constants.md) - - [Built-in Functions](expressions/builtins.md) -- [Advanced Topics](advanced-topics/advanced-topics.md) - - [Remote Builds](advanced-topics/distributed-builds.md) - - [Tuning Cores and Jobs](advanced-topics/cores-vs-jobs.md) - - [Verifying Build Reproducibility](advanced-topics/diff-hook.md) - - [Using the `post-build-hook`](advanced-topics/post-build-hook.md) -- [Command Reference](command-ref/command-ref.md) - - [Common Options](command-ref/opt-common.md) - - [Common Environment Variables](command-ref/env-common.md) - - [Main Commands](command-ref/main-commands.md) - - [nix-env](command-ref/nix-env.md) - - [nix-build](command-ref/nix-build.md) - - [nix-shell](command-ref/nix-shell.md) - - [nix-store](command-ref/nix-store.md) - - [Utilities](command-ref/utilities.md) - - [nix-channel](command-ref/nix-channel.md) - - [nix-collect-garbage](command-ref/nix-collect-garbage.md) - - [nix-copy-closure](command-ref/nix-copy-closure.md) - - [nix-daemon](command-ref/nix-daemon.md) - - [nix-hash](command-ref/nix-hash.md) - - [nix-instantiate](command-ref/nix-instantiate.md) - - [nix-prefetch-url](command-ref/nix-prefetch-url.md) - - [Experimental Commands](command-ref/experimental-commands.md) - - [nix](command-ref/nix.md) - - [Files](command-ref/files.md) - - [nix.conf](command-ref/conf-file.md) -- [Glossary](glossary.md) -- [Hacking](hacking.md) -- [Release Notes](release-notes/release-notes.md) - - [Release 2.3 (2019-09-04)](release-notes/rl-2.3.md) - - [Release 2.2 (2019-01-11)](release-notes/rl-2.2.md) - - [Release 2.1 (2018-09-02)](release-notes/rl-2.1.md) - - [Release 2.0 (2018-02-22)](release-notes/rl-2.0.md) - - [Release 1.11.10 (2017-06-12)](release-notes/rl-1.11.10.md) - - [Release 1.11 (2016-01-19)](release-notes/rl-1.11.md) - - [Release 1.10 (2015-09-03)](release-notes/rl-1.10.md) - - [Release 1.9 (2015-06-12)](release-notes/rl-1.9.md) - - [Release 1.8 (2014-12-14)](release-notes/rl-1.8.md) - - [Release 1.7 (2014-04-11)](release-notes/rl-1.7.md) - - [Release 1.6.1 (2013-10-28)](release-notes/rl-1.6.1.md) - - [Release 1.6 (2013-09-10)](release-notes/rl-1.6.md) - - [Release 1.5.2 (2013-05-13)](release-notes/rl-1.5.2.md) - - [Release 1.5 (2013-02-27)](release-notes/rl-1.5.md) - - [Release 1.4 (2013-02-26)](release-notes/rl-1.4.md) - - [Release 1.3 (2013-01-04)](release-notes/rl-1.3.md) - - [Release 1.2 (2012-12-06)](release-notes/rl-1.2.md) - - [Release 1.1 (2012-07-18)](release-notes/rl-1.1.md) - - [Release 1.0 (2012-05-11)](release-notes/rl-1.0.md) - - [Release 0.16 (2010-08-17)](release-notes/rl-0.16.md) - - [Release 0.15 (2010-03-17)](release-notes/rl-0.15.md) - - [Release 0.14 (2010-02-04)](release-notes/rl-0.14.md) - - [Release 0.13 (2009-11-05)](release-notes/rl-0.13.md) - - [Release 0.12 (2008-11-20)](release-notes/rl-0.12.md) - - [Release 0.11 (2007-12-31)](release-notes/rl-0.11.md) - - [Release 0.10.1 (2006-10-11)](release-notes/rl-0.10.1.md) - - [Release 0.10 (2006-10-06)](release-notes/rl-0.10.md) - - [Release 0.9.2 (2005-09-21)](release-notes/rl-0.9.2.md) - - [Release 0.9.1 (2005-09-20)](release-notes/rl-0.9.1.md) - - [Release 0.9 (2005-09-16)](release-notes/rl-0.9.md) - - [Release 0.8.1 (2005-04-13)](release-notes/rl-0.8.1.md) - - [Release 0.8 (2005-04-11)](release-notes/rl-0.8.md) - - [Release 0.7 (2005-01-12)](release-notes/rl-0.7.md) - - [Release 0.6 (2004-11-14)](release-notes/rl-0.6.md) - - [Release 0.5 and earlier](release-notes/rl-0.5.md) diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in new file mode 100644 index 000000000..b5ae34cfa --- /dev/null +++ b/doc/manual/src/SUMMARY.md.in @@ -0,0 +1,105 @@ +# Table of Contents + +- [Introduction](introduction.md) +- [Quick Start](quick-start.md) +- [Installation](installation/installation.md) + - [Supported Platforms](installation/supported-platforms.md) + - [Installing a Binary Distribution](installation/installing-binary.md) + - [Installing Nix from Source](installation/installing-source.md) + - [Prerequisites](installation/prerequisites-source.md) + - [Obtaining a Source Distribution](installation/obtaining-source.md) + - [Building Nix from Source](installation/building-source.md) + - [Security](installation/nix-security.md) + - [Single-User Mode](installation/single-user.md) + - [Multi-User Mode](installation/multi-user.md) + - [Environment Variables](installation/env-variables.md) + - [Upgrading Nix](installation/upgrading.md) +- [Package Management](package-management/package-management.md) + - [Basic Package Management](package-management/basic-package-mgmt.md) + - [Profiles](package-management/profiles.md) + - [Garbage Collection](package-management/garbage-collection.md) + - [Garbage Collector Roots](package-management/garbage-collector-roots.md) + - [Channels](package-management/channels.md) + - [Sharing Packages Between Machines](package-management/sharing-packages.md) + - [Serving a Nix store via HTTP](package-management/binary-cache-substituter.md) + - [Copying Closures via SSH](package-management/copy-closure.md) + - [Serving a Nix store via SSH](package-management/ssh-substituter.md) + - [Serving a Nix store via S3](package-management/s3-substituter.md) +- [Writing Nix Expressions](expressions/writing-nix-expressions.md) + - [A Simple Nix Expression](expressions/simple-expression.md) + - [Expression Syntax](expressions/expression-syntax.md) + - [Build Script](expressions/build-script.md) + - [Arguments and Variables](expressions/arguments-variables.md) + - [Building and Testing](expressions/simple-building-testing.md) + - [Generic Builder Syntax](expressions/generic-builder.md) + - [Writing Nix Expressions](expressions/expression-language.md) + - [Values](expressions/language-values.md) + - [Language Constructs](expressions/language-constructs.md) + - [Operators](expressions/language-operators.md) + - [Derivations](expressions/derivations.md) + - [Advanced Attributes](expressions/advanced-attributes.md) + - [Built-in Constants](expressions/builtin-constants.md) + - [Built-in Functions](expressions/builtins.md) +- [Advanced Topics](advanced-topics/advanced-topics.md) + - [Remote Builds](advanced-topics/distributed-builds.md) + - [Tuning Cores and Jobs](advanced-topics/cores-vs-jobs.md) + - [Verifying Build Reproducibility](advanced-topics/diff-hook.md) + - [Using the `post-build-hook`](advanced-topics/post-build-hook.md) +- [Command Reference](command-ref/command-ref.md) + - [Common Options](command-ref/opt-common.md) + - [Common Environment Variables](command-ref/env-common.md) + - [Main Commands](command-ref/main-commands.md) + - [nix-env](command-ref/nix-env.md) + - [nix-build](command-ref/nix-build.md) + - [nix-shell](command-ref/nix-shell.md) + - [nix-store](command-ref/nix-store.md) + - [Utilities](command-ref/utilities.md) + - [nix-channel](command-ref/nix-channel.md) + - [nix-collect-garbage](command-ref/nix-collect-garbage.md) + - [nix-copy-closure](command-ref/nix-copy-closure.md) + - [nix-daemon](command-ref/nix-daemon.md) + - [nix-hash](command-ref/nix-hash.md) + - [nix-instantiate](command-ref/nix-instantiate.md) + - [nix-prefetch-url](command-ref/nix-prefetch-url.md) + - [Experimental Commands](command-ref/experimental-commands.md) +@manpages@ + - [Files](command-ref/files.md) + - [nix.conf](command-ref/conf-file.md) +- [Glossary](glossary.md) +- [Hacking](hacking.md) +- [Release Notes](release-notes/release-notes.md) + - [Release 2.3 (2019-09-04)](release-notes/rl-2.3.md) + - [Release 2.2 (2019-01-11)](release-notes/rl-2.2.md) + - [Release 2.1 (2018-09-02)](release-notes/rl-2.1.md) + - [Release 2.0 (2018-02-22)](release-notes/rl-2.0.md) + - [Release 1.11.10 (2017-06-12)](release-notes/rl-1.11.10.md) + - [Release 1.11 (2016-01-19)](release-notes/rl-1.11.md) + - [Release 1.10 (2015-09-03)](release-notes/rl-1.10.md) + - [Release 1.9 (2015-06-12)](release-notes/rl-1.9.md) + - [Release 1.8 (2014-12-14)](release-notes/rl-1.8.md) + - [Release 1.7 (2014-04-11)](release-notes/rl-1.7.md) + - [Release 1.6.1 (2013-10-28)](release-notes/rl-1.6.1.md) + - [Release 1.6 (2013-09-10)](release-notes/rl-1.6.md) + - [Release 1.5.2 (2013-05-13)](release-notes/rl-1.5.2.md) + - [Release 1.5 (2013-02-27)](release-notes/rl-1.5.md) + - [Release 1.4 (2013-02-26)](release-notes/rl-1.4.md) + - [Release 1.3 (2013-01-04)](release-notes/rl-1.3.md) + - [Release 1.2 (2012-12-06)](release-notes/rl-1.2.md) + - [Release 1.1 (2012-07-18)](release-notes/rl-1.1.md) + - [Release 1.0 (2012-05-11)](release-notes/rl-1.0.md) + - [Release 0.16 (2010-08-17)](release-notes/rl-0.16.md) + - [Release 0.15 (2010-03-17)](release-notes/rl-0.15.md) + - [Release 0.14 (2010-02-04)](release-notes/rl-0.14.md) + - [Release 0.13 (2009-11-05)](release-notes/rl-0.13.md) + - [Release 0.12 (2008-11-20)](release-notes/rl-0.12.md) + - [Release 0.11 (2007-12-31)](release-notes/rl-0.11.md) + - [Release 0.10.1 (2006-10-11)](release-notes/rl-0.10.1.md) + - [Release 0.10 (2006-10-06)](release-notes/rl-0.10.md) + - [Release 0.9.2 (2005-09-21)](release-notes/rl-0.9.2.md) + - [Release 0.9.1 (2005-09-20)](release-notes/rl-0.9.1.md) + - [Release 0.9 (2005-09-16)](release-notes/rl-0.9.md) + - [Release 0.8.1 (2005-04-13)](release-notes/rl-0.8.1.md) + - [Release 0.8 (2005-04-11)](release-notes/rl-0.8.md) + - [Release 0.7 (2005-01-12)](release-notes/rl-0.7.md) + - [Release 0.6 (2004-11-14)](release-notes/rl-0.6.md) + - [Release 0.5 and earlier](release-notes/rl-0.5.md) -- cgit v1.2.3