From df7a718786c83e1eca908864820bb05ab964c451 Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Sun, 21 Dec 2003 21:57:09 +0000 Subject: * Man pages in sections. --- doc/manual/Makefile.am | 5 +- doc/manual/book.xml | 16 +- doc/manual/nix-instantiate-reference.xml | 37 --- doc/manual/nix-instantiate.xml | 37 +++ doc/manual/nix-store-reference.xml | 444 ------------------------------- doc/manual/nix-store.xml | 444 +++++++++++++++++++++++++++++++ 6 files changed, 495 insertions(+), 488 deletions(-) delete mode 100644 doc/manual/nix-instantiate-reference.xml create mode 100644 doc/manual/nix-instantiate.xml delete mode 100644 doc/manual/nix-store-reference.xml create mode 100644 doc/manual/nix-store.xml diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am index 34039ba361..46c79ae3b8 100644 --- a/doc/manual/Makefile.am +++ b/doc/manual/Makefile.am @@ -6,9 +6,8 @@ XSLTPROC = $(ENV) $(xsltproc) $(xmlflags) --catalogs \ --param section.label.includes.component.label 1 \ --param html.stylesheet \'style.css\' -SOURCES = book.xml introduction.xml installation.xml \ - overview.xml \ - nix-store-reference.xml nix-instantiate-reference.xml \ +SOURCES = book.xml introduction.xml installation.xml overview.xml \ + common-options.xml nix-store.xml nix-instantiate.xml \ troubleshooting.xml bugs.xml \ style.css diff --git a/doc/manual/book.xml b/doc/manual/book.xml index 7248e5e18b..e8896b073f 100644 --- a/doc/manual/book.xml +++ b/doc/manual/book.xml @@ -6,8 +6,9 @@ - - + + + ]> @@ -32,8 +33,15 @@ Command Reference - &nix-store-reference; - &nix-instantiate-reference; + &common-options; + + nix-store + &nix-store; + + + nix-instantiate + &nix-instantiate; + &troubleshooting; diff --git a/doc/manual/nix-instantiate-reference.xml b/doc/manual/nix-instantiate-reference.xml deleted file mode 100644 index 2e2749e434..0000000000 --- a/doc/manual/nix-instantiate-reference.xml +++ /dev/null @@ -1,37 +0,0 @@ - - - nix-instantiate - generate Nix expressions from a high-level description - - - - - fix - - - - - files - - - - - Description - - - The command fix generates Nix expressions from - expressions is Fix's own high-level language. While Nix expressions are - very primitive and not intended to be written directly, Fix expressions - are quite easy to write. - - - - - - - - diff --git a/doc/manual/nix-instantiate.xml b/doc/manual/nix-instantiate.xml new file mode 100644 index 0000000000..2e2749e434 --- /dev/null +++ b/doc/manual/nix-instantiate.xml @@ -0,0 +1,37 @@ + + + nix-instantiate + generate Nix expressions from a high-level description + + + + + fix + + + + + files + + + + + Description + + + The command fix generates Nix expressions from + expressions is Fix's own high-level language. While Nix expressions are + very primitive and not intended to be written directly, Fix expressions + are quite easy to write. + + + + + + + + diff --git a/doc/manual/nix-store-reference.xml b/doc/manual/nix-store-reference.xml deleted file mode 100644 index 686fe4c156..0000000000 --- a/doc/manual/nix-store-reference.xml +++ /dev/null @@ -1,444 +0,0 @@ - - - nix-store - manipulate or query the Nix store - - - - - nix-store - - - - - - - - - - - - - operation - options - arguments - - - - - Description - - - The command nix provides access to the Nix store. This - is the (set of) path(s) where Nix expressions and the file system objects - built by them are stored. - - - - nix has many subcommands called - operations. These are individually documented - below. Exactly one operation must always be provided. - - - - - - Common Options - - - In this section the options that are common to all Nix operations are - listed. These options are allowed for every subcommand (although they - may not always have an effect). - - - - - - - - - Indicates that any identifier arguments to the operation are paths - in the store rather than identifiers. - - - - - - - - - Increases the level of verbosity of diagnostic messages printed on - standard error. For each Nix operation, the information printed on - standard output is well-defined and specified below in the - respective sections. Any diagnostic information is printed on - standard error, never on standard output. - - - - This option may be specified repeatedly. Currently, the following - verbosity levels exist: - - - - - 0 - - - Print error messages only. - - - - - 1 - - - Print informational messages. - - - - - 2 - - - Print even more informational messages. - - - - - 3 - - - Print messages that should only be useful for debugging. - - - - - 4 - - - Vomit mode: print vast amounts of debug - information. - - - - - - - - - - - - - Specifies that in case of a build failure, the temporary directory - (usually in /tmp) in which the build takes - place should not be deleted. The path of the build directory is - printed as an informational message. - - - - - - - - - - - - - Operation <option>--install</option> - - - Synopsis - - nix - - - - - ids - - - - - Description - - - The operation realises the Nix expressions - identified by ids in the file system. If - these expressions are derivation expressions, they are first - normalised. That is, their target paths are are built, unless a normal - form is already known. - - - - The identifiers of the normal forms of the given Nix expressions are - printed on standard output. - - - - - - - - - - - Operation <option>--delete</option> - - - Synopsis - - nix - - - - - paths - - - - - Description - - - The operation unconditionally deletes the - paths paths from the Nix store. It is an - error to attempt to delete paths outside of the store. - - - - - This operation should almost never be called directly, since no - attempt is made to verify that no references exist to the paths to - be deleted. Therefore, careless deletion can result in an - inconsistent system. Deletion of paths in the store is done by the - garbage collector (which uses to delete - unreferenced paths). - - - - - - - - - - - - - Operation <option>--query</option> - - - Synopsis - - nix - - - - - - - - - - - - - - - - - - - - - - - args - - - - - Description - - - The operation displays various bits of - information about Nix expressions or paths in the store. The queries - are described in . At most one query - can be specified; the default query is . - - - - - - Queries - - - - - - - - Prints out the target paths of the Nix expressions indicated by - the identifiers args. In the case of - a derivation expression, these are the paths that will be - produced by the builder of the expression. In the case of a - slice expression, these are the root paths (which are generally - the paths that were produced by the builder of the derivation - expression of which the slice is a normal form). - - - - This query has one option: - - - - - - - - - Causes the target paths of the normal - forms of the expressions to be printed, rather - than the target paths of the expressions themselves. - - - - - - - - - - - - - - Prints out the requisite paths of the Nix expressions indicated - by the identifiers args. The - requisite paths of a Nix expression are the paths that need to be - present in the system to be able to realise the expression. That - is, they form the closure of the expression - in the file system (i.e., no path in the set of requisite paths - points to anything outside the set of requisite paths). - - - - The notion of requisite paths is very useful when one wants to - distribute Nix expressions. Since they form a closure, they are - the only paths one needs to distribute to another system to be - able to realise the expression on the other system. - - - - This query is generally used to implement various kinds of - distribution. A source distribution is - obtained by distributing the requisite paths of a derivation - expression. A binary distribution is - obtained by distributing the requisite paths of a slice - expression (i.e., the normal form of a derivation expression; you - can directly specify the identifier of the slice expression, or - use and specify the identifier of a - derivation expression). A cache - distribution is obtained by distributing the - requisite paths of a derivation expression and specifying the - option . This will include - not just the paths of a source and binary distribution, but also - all expressions and paths of subterms of the source. This is - useful if one wants to realise on the target system a Nix - expression that is similar but not quite the same as the one - being distributed, since any common subterms will be reused. - - - - This query has a number of options: - - - - - - - - - Causes the requisite paths of the normal - forms of the expressions to be printed, rather - than the requisite paths of the expressions themselves. - - - - - - - - - Excludes the paths of Nix expressions. This causes the - closure property to be lost, that is, the resulting set of - paths is not enough to ensure realisibility. - - - - - - - - - Also include the requisites of successors (normal forms). - Only the requisites of known - successors are included, i.e., the normal forms of - derivation expressions that have never been normalised will - not be included. - - - - Note that not just the successor of a derivation expression - will be included, but also the successors of all input - expressions of that derivation expression. I.e., all - normal forms of subterms involved in the normalisation of - the top-level term are included. - - - - - - - - - - - - - - For each identifier in args, prints - all expansions of that identifier, that is, all paths whose - current content matches the identifier. - - - - - - - - - Prints a graph of the closure of the expressions identified by - args in the format of the - dot tool of AT&T's GraphViz package. - - - - - - - - - - - - - - - diff --git a/doc/manual/nix-store.xml b/doc/manual/nix-store.xml new file mode 100644 index 0000000000..686fe4c156 --- /dev/null +++ b/doc/manual/nix-store.xml @@ -0,0 +1,444 @@ + + + nix-store + manipulate or query the Nix store + + + + + nix-store + + + + + + + + + + + + + operation + options + arguments + + + + + Description + + + The command nix provides access to the Nix store. This + is the (set of) path(s) where Nix expressions and the file system objects + built by them are stored. + + + + nix has many subcommands called + operations. These are individually documented + below. Exactly one operation must always be provided. + + + + + + Common Options + + + In this section the options that are common to all Nix operations are + listed. These options are allowed for every subcommand (although they + may not always have an effect). + + + + + + + + + Indicates that any identifier arguments to the operation are paths + in the store rather than identifiers. + + + + + + + + + Increases the level of verbosity of diagnostic messages printed on + standard error. For each Nix operation, the information printed on + standard output is well-defined and specified below in the + respective sections. Any diagnostic information is printed on + standard error, never on standard output. + + + + This option may be specified repeatedly. Currently, the following + verbosity levels exist: + + + + + 0 + + + Print error messages only. + + + + + 1 + + + Print informational messages. + + + + + 2 + + + Print even more informational messages. + + + + + 3 + + + Print messages that should only be useful for debugging. + + + + + 4 + + + Vomit mode: print vast amounts of debug + information. + + + + + + + + + + + + + Specifies that in case of a build failure, the temporary directory + (usually in /tmp) in which the build takes + place should not be deleted. The path of the build directory is + printed as an informational message. + + + + + + + + + + + + + Operation <option>--install</option> + + + Synopsis + + nix + + + + + ids + + + + + Description + + + The operation realises the Nix expressions + identified by ids in the file system. If + these expressions are derivation expressions, they are first + normalised. That is, their target paths are are built, unless a normal + form is already known. + + + + The identifiers of the normal forms of the given Nix expressions are + printed on standard output. + + + + + + + + + + + Operation <option>--delete</option> + + + Synopsis + + nix + + + + + paths + + + + + Description + + + The operation unconditionally deletes the + paths paths from the Nix store. It is an + error to attempt to delete paths outside of the store. + + + + + This operation should almost never be called directly, since no + attempt is made to verify that no references exist to the paths to + be deleted. Therefore, careless deletion can result in an + inconsistent system. Deletion of paths in the store is done by the + garbage collector (which uses to delete + unreferenced paths). + + + + + + + + + + + + + Operation <option>--query</option> + + + Synopsis + + nix + + + + + + + + + + + + + + + + + + + + + + + args + + + + + Description + + + The operation displays various bits of + information about Nix expressions or paths in the store. The queries + are described in . At most one query + can be specified; the default query is . + + + + + + Queries + + + + + + + + Prints out the target paths of the Nix expressions indicated by + the identifiers args. In the case of + a derivation expression, these are the paths that will be + produced by the builder of the expression. In the case of a + slice expression, these are the root paths (which are generally + the paths that were produced by the builder of the derivation + expression of which the slice is a normal form). + + + + This query has one option: + + + + + + + + + Causes the target paths of the normal + forms of the expressions to be printed, rather + than the target paths of the expressions themselves. + + + + + + + + + + + + + + Prints out the requisite paths of the Nix expressions indicated + by the identifiers args. The + requisite paths of a Nix expression are the paths that need to be + present in the system to be able to realise the expression. That + is, they form the closure of the expression + in the file system (i.e., no path in the set of requisite paths + points to anything outside the set of requisite paths). + + + + The notion of requisite paths is very useful when one wants to + distribute Nix expressions. Since they form a closure, they are + the only paths one needs to distribute to another system to be + able to realise the expression on the other system. + + + + This query is generally used to implement various kinds of + distribution. A source distribution is + obtained by distributing the requisite paths of a derivation + expression. A binary distribution is + obtained by distributing the requisite paths of a slice + expression (i.e., the normal form of a derivation expression; you + can directly specify the identifier of the slice expression, or + use and specify the identifier of a + derivation expression). A cache + distribution is obtained by distributing the + requisite paths of a derivation expression and specifying the + option . This will include + not just the paths of a source and binary distribution, but also + all expressions and paths of subterms of the source. This is + useful if one wants to realise on the target system a Nix + expression that is similar but not quite the same as the one + being distributed, since any common subterms will be reused. + + + + This query has a number of options: + + + + + + + + + Causes the requisite paths of the normal + forms of the expressions to be printed, rather + than the requisite paths of the expressions themselves. + + + + + + + + + Excludes the paths of Nix expressions. This causes the + closure property to be lost, that is, the resulting set of + paths is not enough to ensure realisibility. + + + + + + + + + Also include the requisites of successors (normal forms). + Only the requisites of known + successors are included, i.e., the normal forms of + derivation expressions that have never been normalised will + not be included. + + + + Note that not just the successor of a derivation expression + will be included, but also the successors of all input + expressions of that derivation expression. I.e., all + normal forms of subterms involved in the normalisation of + the top-level term are included. + + + + + + + + + + + + + + For each identifier in args, prints + all expansions of that identifier, that is, all paths whose + current content matches the identifier. + + + + + + + + + Prints a graph of the closure of the expressions identified by + args in the format of the + dot tool of AT&T's GraphViz package. + + + + + + + + + + + + + + + -- cgit 1.4.1