diff --git a/doc/package-notes.xml b/doc/package-notes.xml
index 6291abbe9bd8..9ace151e512b 100644
--- a/doc/package-notes.xml
+++ b/doc/package-notes.xml
@@ -165,12 +165,60 @@ splashutils_15 = ...;</programlisting>
 <!--============================================================-->
 
 <section>
-  <title>X.org</title>
-  <para>* Expression is auto-generated</para>
-  <para>* How to update</para>
+
+<title>X.org</title>
+
+<para>The Nix expressions for the X.org packages reside in
+<filename>pkgs/servers/x11/xorg/default.nix</filename>.  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 or the generator script.</para>
+
+<para>The generator is invoked as follows:
+
+<screen>
+$ cd pkgs/servers/x11/xorg
+$ cat tarballs-7.4.list extra.list old.list \
+  | perl ./generate-expr-from-tarballs.pl
+</screen>
+
+For each of the tarballs in the <filename>.list</filename> files, the
+script downloads it, unpacks it, and searches its
+<filename>configure.ac</filename> and <filename>*.pc.in</filename>
+files for dependencies.  This information is used to generate
+<filename>default.nix</filename>.  The generator caches downloaded
+tarballs between runs.  Pay close attention to the <literal>NOT FOUND:
+<replaceable>name</replaceable></literal> messages at the end of the
+run, since they may indicate missing dependencies.  (Some might be
+optional dependencies, however.)</para>
+
+<para>A file like <filename>tarballs-7.4.list</filename> contains all
+tarballs in a X.org release.  It can be generated like this:
+
+<screen>
+$ 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
+</screen>
+
+<filename>extra.list</filename> contains libraries that aren’t part of
+X.org proper, but are closely related to it, such as
+<literal>libxcb</literal>.  <filename>old.list</filename> contains
+some packages that were removed from X.org, but are still needed by
+some people or by other packages (such as
+<varname>imake</varname>).</para>
+
+<para>If the expression for a package requires derivation attributes
+that the generator cannot figure out automatically (say,
+<varname>patches</varname> or a <varname>postInstall</varname> hook),
+you should modify the generator script
+(<varname>generate-expr-from-tarballs.pl</varname>).</para>
+
 </section>
 
 
+
 <!--============================================================-->
 
 <section>