From fc0f32e0f5c2b9839d92ae22dbe344e703e0d691 Mon Sep 17 00:00:00 2001
From: Corbin <cds@corbinsimpson.com>
Date: Mon, 30 Nov 2020 10:35:21 -0800
Subject: doc/builders/packages/xorg: Acknowledge the retired katamari.

I tested the shell snippets shown here; they work. Note that, because
they're intended for copy-and-paste, I did *not* make them into
ShellSessions with prompts. But that's something I can do if desired.
---
 doc/builders/packages/xorg.section.md | 49 +++++++++++++++--------------------
 1 file changed, 21 insertions(+), 28 deletions(-)

(limited to 'doc/builders/packages')

diff --git a/doc/builders/packages/xorg.section.md b/doc/builders/packages/xorg.section.md
index c8a4c121981..4e49450f43e 100644
--- a/doc/builders/packages/xorg.section.md
+++ b/doc/builders/packages/xorg.section.md
@@ -1,41 +1,34 @@
 # X.org {#sec-xorg}
 
-The Nix expressions for the X.org packages reside in
-`pkgs/servers/x11/xorg/default.nix`. This file is automatically generated from
-lists of tarballs in an X.org release. As such it should not be modified
-directly; rather, you should modify the lists, the generator script or the
-file `pkgs/servers/x11/xorg/overrides.nix`, in which you can override or add
-to the derivations produced by the generator.
+The Nix expressions for the X.org packages reside in `pkgs/servers/x11/xorg/default.nix`. This file is automatically generated from lists of tarballs in an X.org release. As such it should not be modified directly; rather, you should modify the lists, the generator script or the file `pkgs/servers/x11/xorg/overrides.nix`, in which you can override or add to the derivations produced by the generator.
 
-The generator is invoked as follows:
+## Katamari Tarballs
+
+X.org upstream releases used to include [katamari](https://en.wiktionary.org/wiki/%E3%81%8B%E3%81%9F%E3%81%BE%E3%82%8A) releases, which included a holistic recommended version for each tarball, up until 7.7. To create a list of tarballs in a katamari release:
 
 ```sh
-cd pkgs/servers/x11/xorg
-cat tarballs-7.4.list extra.list old.list | perl ./generate-expr-from-tarballs.pl
+export release="X11R7.7"
+export url="mirror://xorg/X11R7.4/src/everything/"
+cat $(PRINT_PATH=1 nix-prefetch-url $url | tail -n 1) \
+  | perl -e 'while (<>) { if (/(href|HREF)="([^"]*.bz2)"/) { print "$ENV{'url'}$2\n"; }; }' \
+  | sort > "tarballs-$release.list"
 ```
 
-For each of the tarballs in the `.list` files, the script downloads it,
-unpacks it, and searches its `configure.ac` and `*.pc.in` files for
-dependencies. This information is used to generate `default.nix`. The
-generator caches downloaded tarballs between runs. Pay close attention to the
-`NOT FOUND: $NAME` messages at the end of the run, since they may indicate
-missing dependencies. (Some might be optional dependencies, however.)
+## Individual Tarballs
+
+The upstream release process for [X11R7.8](https://x.org/wiki/Releases/7.8/) does not include a planned katamari. Instead, each component of X.org is released as its own tarball. We maintain `pkgs/servers/x11/xorg/tarballs.list` as a list of tarballs for each individual package. This list includes X.org core libraries and protocol descriptions, extra newer X11 interface libraries, like `xorg.libxcb`, and classic utilities which are largely unused but still available if needed, like `xorg.imake`.
 
-A file like `tarballs-7.4.list` contains all tarballs in a X.org release. It
-can be generated like this:
+## Generating Nix Expressions
+
+The generator is invoked as follows:
 
 ```sh
-export i="mirror://xorg/X11R7.4/src/everything/"
-cat $(PRINT_PATH=1 nix-prefetch-url $i | tail -n 1) \
-  | perl -e 'while (&lt;>) { if (/(href|HREF)="([^"]*.bz2)"/) { print "$ENV{'i'}$2\n"; }; }' \
-  | sort > tarballs-7.4.list
+cd pkgs/servers/x11/xorg
+<tarballs.list perl ./generate-expr-from-tarballs.pl
 ```
 
-`extra.list` contains libraries that aren’t part of X.org proper, but are
-closely related to it, such as `libxcb`. `old.list` contains some packages
-that were removed from X.org, but are still needed by some people or by other
-packages (such as `imake`).
+For each of the tarballs in the `.list` files, the script downloads it, unpacks it, and searches its `configure.ac` and `*.pc.in` files for dependencies. This information is used to generate `default.nix`. The generator caches downloaded tarballs between runs. Pay close attention to the `NOT FOUND: $NAME` messages at the end of the run, since they may indicate missing dependencies. (Some might be optional dependencies, however.)
+
+## Overriding the Generator
 
-If the expression for a package requires derivation attributes that the
-generator cannot figure out automatically (say, `patches` or a `postInstall`
-hook), you should modify `pkgs/servers/x11/xorg/overrides.nix`.
+If the expression for a package requires derivation attributes that the generator cannot figure out automatically (say, `patches` or a `postInstall` hook), you should modify `pkgs/servers/x11/xorg/overrides.nix`.
-- 
cgit 1.4.1