Merge pull request #15004 from roberth/docs

Add Nix32 encoding documentation

Author: edolstra

doc/manual/source/SUMMARY.md.in

@@ -136,6 +136,7 @@
   - [Store Path Specification](protocols/store-path.md)
   - [Nix Archive (NAR) Format](protocols/nix-archive/index.md)
   - [Derivation "ATerm" file format](protocols/derivation-aterm.md)
+  - [Nix32 Encoding](protocols/nix32.md)
 - [C API](c-api.md)
 - [Glossary](glossary.md)
 - [Development](development/index.md)

doc/manual/source/language/advanced-attributes.md

@@ -338,7 +338,7 @@ Here is more information on the `output*` attributes, and what values they may b
     This will specify the output hash of the single output of a [fixed-output derivation].
 
     The `outputHash` attribute must be a string containing the hash in either hexadecimal or "nix32" encoding, or following the format for integrity metadata as defined by [SRI](https://www.w3.org/TR/SRI/).
-    The "nix32" encoding is an adaptation of base-32 encoding.
+    The ["nix32" encoding](@docroot@/protocols/nix32.md) is Nix's variant of base-32 encoding.
 
     > **Note**
     >

doc/manual/source/protocols/json/schema/store-path-v1.yaml

@@ -24,7 +24,7 @@ description: |
 
   The format follows this pattern: `${digest}-${name}`
 
-  - **hash**: Digest rendered in a custom variant of [Base32](https://en.wikipedia.org/wiki/Base32) (20 arbitrary bytes become 32 ASCII characters)
+  - **hash**: Digest rendered in [Nix32](@docroot@/protocols/nix32.md), a variant of base-32 (20 hash bytes become 32 ASCII characters)
   - **name**: The package name and optional version/suffix information
 
 type: string

doc/manual/source/protocols/nix32.md

@@ -0,0 +1,19 @@
+# Nix32 Encoding
+
+Nix32 is Nix's variant of base-32 encoding, used for [store path digests](@docroot@/protocols/store-path.md), hash output via [`nix hash`](@docroot@/command-ref/new-cli/nix3-hash.md), and the [`outputHash`](@docroot@/language/advanced-attributes.md#adv-attr-outputHash) derivation attribute.
+
+## Alphabet
+
+The Nix32 alphabet consists of these 32 characters:
+
+```
+0 1 2 3 4 5 6 7 8 9 a b c d f g h i j k l m n p q r s v w x y z
+```
+
+The letters `e`, `o`, `u`, and `t` are omitted.
+
+## Byte Order
+
+Nix32 encoding processes the hash bytes from the end (last byte first), while base-16 encoding processes from the beginning (first byte first).
+
+Consequently, the string sort order is determined primarily by the first bytes for base-16, and by the last bytes for Nix32.

doc/manual/source/protocols/store-path.md

@@ -20,12 +20,11 @@ where
 
 - `store-dir` = the [store directory](@docroot@/store/store-path.md#store-directory)
 
-- `digest` = base-32 representation of the compressed to 160 bits [SHA-256] hash of `fingerprint`
+- `digest` = base-32 representation of the compressed to 160 bits [SHA-256] hash of `fingerprint`.
 
-For the definition of the hash compression algorithm, please refer to the section 5.1 of
-the [Nix thesis](https://edolstra.github.io/pubs/phd-thesis.pdf), which also defines the
-specifics of base-32 encoding. Note that base-32 encoding processes the hash bytestring from
-the end, while base-16 processes in from the beginning.
+  Nix uses a custom base-32 encoding called [Nix32](@docroot@/protocols/nix32.md).
+
+  For the definition of the hash compression algorithm, please refer to section 5.1 of the [Nix thesis](https://edolstra.github.io/pubs/phd-thesis.pdf).
 
 ## Fingerprint
 

doc/manual/source/store/store-path.md

@@ -31,7 +31,7 @@ A store path is rendered to a file system path as the concatenation of
 
 - [Store directory](#store-directory) (typically `/nix/store`)
 - Path separator (`/`)
-- Digest rendered in a custom variant of [Base32](https://en.wikipedia.org/wiki/Base32) (20 arbitrary bytes become 32 ASCII characters)
+- Digest rendered in [Nix32](@docroot@/protocols/nix32.md), a variant of base-32 (20 hash bytes become 32 ASCII characters)
 - Hyphen (`-`)
 - Name