diff options
Diffstat (limited to 'doc/manual')
| -rw-r--r-- | doc/manual/generate-builtin-constants.nix | 8 | ||||
| -rw-r--r-- | doc/manual/generate-builtins.nix | 9 | ||||
| -rw-r--r-- | doc/manual/generate-manpage.nix | 161 | ||||
| -rw-r--r-- | doc/manual/generate-xp-features-shortlist.nix | 10 | ||||
| -rw-r--r-- | doc/manual/generate-xp-features.nix | 6 | ||||
| -rw-r--r-- | doc/manual/utils.nix | 135 |
6 files changed, 215 insertions, 114 deletions
diff --git a/doc/manual/generate-builtin-constants.nix b/doc/manual/generate-builtin-constants.nix index 8af80a02c..23ec2cb55 100644 --- a/doc/manual/generate-builtin-constants.nix +++ b/doc/manual/generate-builtin-constants.nix @@ -5,7 +5,13 @@ in builtinsInfo: let - showBuiltin = name: { doc, type, impure-only }: + showBuiltin = + name: + { + doc, + type, + impure-only, + }: let type' = optionalString (type != null) " (${type})"; diff --git a/doc/manual/generate-builtins.nix b/doc/manual/generate-builtins.nix index 813a287f5..60cba266b 100644 --- a/doc/manual/generate-builtins.nix +++ b/doc/manual/generate-builtins.nix @@ -5,7 +5,14 @@ in builtinsInfo: let - showBuiltin = name: { doc, args, arity, experimental-feature }: + showBuiltin = + name: + { + doc, + args, + arity, + experimental-feature, + }: let experimentalNotice = optionalString (experimental-feature != null) '' This function is only available if the [${experimental-feature}](@docroot@/contributing/experimental-features.md#xp-feature-${experimental-feature}) experimental feature is enabled. diff --git a/doc/manual/generate-manpage.nix b/doc/manual/generate-manpage.nix index 972def69a..cabfdd0d8 100644 --- a/doc/manual/generate-manpage.nix +++ b/doc/manual/generate-manpage.nix @@ -1,8 +1,26 @@ let inherit (builtins) - attrNames attrValues fromJSON listToAttrs mapAttrs - concatStringsSep concatMap length lessThan replaceStrings sort; - inherit (import ./utils.nix) concatStrings optionalString filterAttrs trim squash unique showSettings; + attrNames + attrValues + fromJSON + listToAttrs + mapAttrs + concatStringsSep + concatMap + length + lessThan + replaceStrings + sort + ; + inherit (import ./utils.nix) + concatStrings + optionalString + filterAttrs + trim + squash + unique + showSettings + ; in inlineHTML: commandDump: @@ -11,7 +29,13 @@ let commandInfo = fromJSON commandDump; - showCommand = { command, details, filename, toplevel }: + showCommand = + { + command, + details, + filename, + toplevel, + }: let result = '' @@ -35,26 +59,27 @@ let ${maybeOptions} ''; - showSynopsis = command: args: + showSynopsis = + command: args: let - showArgument = arg: "*${arg.label}*" + optionalString (! arg ? arity) "..."; + showArgument = arg: "*${arg.label}*" + optionalString (!arg ? arity) "..."; arguments = concatStringsSep " " (map showArgument args); - in '' - `${command}` [*option*...] ${arguments} + in + '' + `${command}` [*option*...] ${arguments} ''; - maybeSubcommands = optionalString (details ? commands && details.commands != {}) - '' - where *subcommand* is one of the following: + maybeSubcommands = optionalString (details ? commands && details.commands != { }) '' + where *subcommand* is one of the following: - ${subcommands} - ''; + ${subcommands} + ''; - subcommands = if length categories > 1 - then listCategories - else listSubcommands details.commands; + subcommands = if length categories > 1 then listCategories else listSubcommands details.commands; - categories = sort (x: y: x.id < y.id) (unique (map (cmd: cmd.category) (attrValues details.commands))); + categories = sort (x: y: x.id < y.id) ( + unique (map (cmd: cmd.category) (attrValues details.commands)) + ); listCategories = concatStrings (map showCategory categories); @@ -71,11 +96,11 @@ let ''; # TODO: move this confusing special case out of here when implementing #8496 - maybeStoreDocs = optionalString - (details ? doc) - (replaceStrings ["@stores@"] [storeDocs] details.doc); + maybeStoreDocs = optionalString (details ? doc) ( + replaceStrings [ "@stores@" ] [ storeDocs ] details.doc + ); - maybeOptions = optionalString (details.flags != {}) '' + maybeOptions = optionalString (details.flags != { }) '' # Options ${showOptions details.flags toplevel.flags} @@ -85,51 +110,70 @@ let > See [`man nix.conf`](@docroot@/command-ref/conf-file.md#command-line-flags) for overriding configuration settings with command line flags. ''; - showOptions = options: commonOptions: + showOptions = + options: commonOptions: let allOptions = options // commonOptions; showCategory = cat: '' ${optionalString (cat != "") "**${cat}:**"} ${listOptions (filterAttrs (n: v: v.category == cat) allOptions)} - ''; + ''; listOptions = opts: concatStringsSep "\n" (attrValues (mapAttrs showOption opts)); - showOption = name: option: + showOption = + name: option: let result = trim '' - ${item} ${option.description} ''; - item = if inlineHTML - then ''<span id="opt-${name}">[`--${name}`](#opt-${name})</span> ${shortName} ${labels}'' - else "`--${name}` ${shortName} ${labels}"; - shortName = optionalString - (option ? shortName) - ("/ `-${option.shortName}`"); - labels = optionalString - (option ? labels) - (concatStringsSep " " (map (s: "*${s}*") option.labels)); - in result; + item = + if inlineHTML then + ''<span id="opt-${name}">[`--${name}`](#opt-${name})</span> ${shortName} ${labels}'' + else + "`--${name}` ${shortName} ${labels}"; + shortName = optionalString (option ? shortName) ("/ `-${option.shortName}`"); + labels = optionalString (option ? labels) (concatStringsSep " " (map (s: "*${s}*") option.labels)); + in + result; categories = sort lessThan (unique (map (cmd: cmd.category) (attrValues allOptions))); - in concatStrings (map showCategory categories); - in squash result; + in + concatStrings (map showCategory categories); + in + squash result; appendName = filename: name: (if filename == "nix" then "nix3" else filename) + "-" + name; - processCommand = { command, details, filename, toplevel }: + processCommand = + { + command, + details, + filename, + toplevel, + }: let cmd = { inherit command; name = filename + ".md"; - value = showCommand { inherit command details filename toplevel; }; - }; - subcommand = subCmd: processCommand { - command = command + " " + subCmd; - details = details.commands.${subCmd}; - filename = appendName filename subCmd; - inherit toplevel; + value = showCommand { + inherit + command + details + filename + toplevel + ; + }; }; - in [ cmd ] ++ concatMap subcommand (attrNames details.commands or {}); + subcommand = + subCmd: + processCommand { + command = command + " " + subCmd; + details = details.commands.${subCmd}; + filename = appendName filename subCmd; + inherit toplevel; + }; + in + [ cmd ] ++ concatMap subcommand (attrNames details.commands or { }); manpages = processCommand { command = "nix"; @@ -138,14 +182,21 @@ let toplevel = commandInfo.args; }; - tableOfContents = let - showEntry = page: - " - [${page.command}](command-ref/new-cli/${page.name})"; - in concatStringsSep "\n" (map showEntry manpages) + "\n"; + tableOfContents = + let + showEntry = page: " - [${page.command}](command-ref/new-cli/${page.name})"; + in + concatStringsSep "\n" (map showEntry manpages) + "\n"; storeDocs = let - showStore = name: { settings, doc, experimentalFeature }: + showStore = + name: + { + settings, + doc, + experimentalFeature, + }: let experimentalFeatureNote = optionalString (experimentalFeature != null) '' > **Warning** @@ -161,7 +212,8 @@ let extra-experimental-features = ${experimentalFeature} ``` ''; - in '' + in + '' ## ${name} ${doc} @@ -172,6 +224,7 @@ let ${showSettings { inherit inlineHTML; } settings} ''; - in concatStrings (attrValues (mapAttrs showStore commandInfo.stores)); - -in (listToAttrs manpages) // { "SUMMARY.md" = tableOfContents; } + in + concatStrings (attrValues (mapAttrs showStore commandInfo.stores)); +in +(listToAttrs manpages) // { "SUMMARY.md" = tableOfContents; } diff --git a/doc/manual/generate-xp-features-shortlist.nix b/doc/manual/generate-xp-features-shortlist.nix index 30e211c96..ea8bf8d49 100644 --- a/doc/manual/generate-xp-features-shortlist.nix +++ b/doc/manual/generate-xp-features-shortlist.nix @@ -2,8 +2,8 @@ with builtins; with import ./utils.nix; let - showExperimentalFeature = name: doc: - '' - - [`${name}`](@docroot@/contributing/experimental-features.md#xp-feature-${name}) - ''; -in xps: indent " " (concatStrings (attrValues (mapAttrs showExperimentalFeature xps))) + showExperimentalFeature = name: doc: '' + - [`${name}`](@docroot@/contributing/experimental-features.md#xp-feature-${name}) + ''; +in +xps: indent " " (concatStrings (attrValues (mapAttrs showExperimentalFeature xps))) diff --git a/doc/manual/generate-xp-features.nix b/doc/manual/generate-xp-features.nix index adb94355c..c56ddeea1 100644 --- a/doc/manual/generate-xp-features.nix +++ b/doc/manual/generate-xp-features.nix @@ -2,10 +2,12 @@ with builtins; with import ./utils.nix; let - showExperimentalFeature = name: doc: + showExperimentalFeature = + name: doc: squash '' ## [`${name}`]{#xp-feature-${name}} ${doc} ''; -in xps: (concatStringsSep "\n" (attrValues (mapAttrs showExperimentalFeature xps))) +in +xps: (concatStringsSep "\n" (attrValues (mapAttrs showExperimentalFeature xps))) diff --git a/doc/manual/utils.nix b/doc/manual/utils.nix index 193c1efc0..17e6378eb 100644 --- a/doc/manual/utils.nix +++ b/doc/manual/utils.nix @@ -5,10 +5,15 @@ rec { concatStrings = concatStringsSep ""; - attrsToList = a: - map (name: { inherit name; value = a.${name}; }) (builtins.attrNames a); - - replaceStringsRec = from: to: string: + attrsToList = + a: + map (name: { + inherit name; + value = a.${name}; + }) (builtins.attrNames a); + + replaceStringsRec = + from: to: string: # recursively replace occurrences of `from` with `to` within `string` # example: # replaceStringRec "--" "-" "hello-----world" @@ -16,14 +21,16 @@ rec { let replaced = replaceStrings [ from ] [ to ] string; in - if replaced == string then string else replaceStringsRec from to replaced; + if replaced == string then string else replaceStringsRec from to replaced; squash = replaceStringsRec "\n\n\n" "\n\n"; - trim = string: + trim = + string: # trim trailing spaces and squash non-leading spaces let - trimLine = line: + trimLine = + line: let # separate leading spaces from the rest parts = split "(^ *)" line; @@ -31,76 +38,102 @@ rec { rest = elemAt parts 2; # drop trailing spaces body = head (split " *$" rest); - in spaces + replaceStringsRec " " " " body; - in concatStringsSep "\n" (map trimLine (splitLines string)); + in + spaces + replaceStringsRec " " " " body; + in + concatStringsSep "\n" (map trimLine (splitLines string)); # FIXME: O(n^2) - unique = foldl' (acc: e: if elem e acc then acc else acc ++ [ e ]) []; + unique = foldl' (acc: e: if elem e acc then acc else acc ++ [ e ]) [ ]; nameValuePair = name: value: { inherit name value; }; - filterAttrs = pred: set: - listToAttrs (concatMap (name: let v = set.${name}; in if pred name v then [(nameValuePair name v)] else []) (attrNames set)); + filterAttrs = + pred: set: + listToAttrs ( + concatMap ( + name: + let + v = set.${name}; + in + if pred name v then [ (nameValuePair name v) ] else [ ] + ) (attrNames set) + ); optionalString = cond: string: if cond then string else ""; - showSetting = { inlineHTML }: name: { description, documentDefault, defaultValue, aliases, value, experimentalFeature }: + showSetting = + { inlineHTML }: + name: + { + description, + documentDefault, + defaultValue, + aliases, + value, + experimentalFeature, + }: let result = squash '' - - ${if inlineHTML - then ''<span id="conf-${name}">[`${name}`](#conf-${name})</span>'' - else ''`${name}`''} + - ${ + if inlineHTML then ''<span id="conf-${name}">[`${name}`](#conf-${name})</span>'' else ''`${name}`'' + } - ${indent " " body} - ''; + ${indent " " body} + ''; experimentalFeatureNote = optionalString (experimentalFeature != null) '' - > **Warning** - > This setting is part of an - > [experimental feature](@docroot@/contributing/experimental-features.md). + > **Warning** + > This setting is part of an + > [experimental feature](@docroot@/contributing/experimental-features.md). - To change this setting, you need to make sure the corresponding experimental feature, - [`${experimentalFeature}`](@docroot@/contributing/experimental-features.md#xp-feature-${experimentalFeature}), - is enabled. - For example, include the following in [`nix.conf`](#): + To change this setting, you need to make sure the corresponding experimental feature, + [`${experimentalFeature}`](@docroot@/contributing/experimental-features.md#xp-feature-${experimentalFeature}), + is enabled. + For example, include the following in [`nix.conf`](#): - ``` - extra-experimental-features = ${experimentalFeature} - ${name} = ... - ``` - ''; + ``` + extra-experimental-features = ${experimentalFeature} + ${name} = ... + ``` + ''; # separate body to cleanly handle indentation body = '' - ${description} + ${description} - ${experimentalFeatureNote} + ${experimentalFeatureNote} - **Default:** ${showDefault documentDefault defaultValue} + **Default:** ${showDefault documentDefault defaultValue} - ${showAliases aliases} - ''; + ${showAliases aliases} + ''; - showDefault = documentDefault: defaultValue: + showDefault = + documentDefault: defaultValue: if documentDefault then # a StringMap value type is specified as a string, but # this shows the value type. The empty stringmap is `null` in # JSON, but that converts to `{ }` here. - if defaultValue == "" || defaultValue == [] || isAttrs defaultValue - then "*empty*" - else if isBool defaultValue then - if defaultValue then "`true`" else "`false`" - else "`${toString defaultValue}`" - else "*machine-specific*"; - - showAliases = aliases: - optionalString (aliases != []) - "**Deprecated alias:** ${(concatStringsSep ", " (map (s: "`${s}`") aliases))}"; - - in result; + if defaultValue == "" || defaultValue == [ ] || isAttrs defaultValue then + "*empty*" + else if isBool defaultValue then + if defaultValue then "`true`" else "`false`" + else + "`${toString defaultValue}`" + else + "*machine-specific*"; + + showAliases = + aliases: + optionalString (aliases != [ ]) + "**Deprecated alias:** ${(concatStringsSep ", " (map (s: "`${s}`") aliases))}"; + in + result; - indent = prefix: s: - concatStringsSep "\n" (map (x: if x == "" then x else "${prefix}${x}") (splitLines s)); + indent = + prefix: s: concatStringsSep "\n" (map (x: if x == "" then x else "${prefix}${x}") (splitLines s)); - showSettings = args: settingsInfo: concatStrings (attrValues (mapAttrs (showSetting args) settingsInfo)); + showSettings = + args: settingsInfo: concatStrings (attrValues (mapAttrs (showSetting args) settingsInfo)); } |