diff --git a/doc/coding-conventions.xml b/doc/coding-conventions.xml
index 586fcd98f23d..b941e3ca2a6d 100644
--- a/doc/coding-conventions.xml
+++ b/doc/coding-conventions.xml
@@ -215,7 +215,281 @@ dashes between words — not in camel case. For instance, it should be
allPackages.nix or
AllPackages.nix.
+Each package should be stored in its own directory somewhere in
+the pkgs/ tree, i.e. in
+pkgs/category/subcategory/.../pkgname.
+Below are some rules for picking the right category for a package.
+Many packages fall under several categories; what matters is the
+primary purpose of a package. For example, the
+libxml2 package builds both a library and some
+tools; but it’s a library foremost, so it goes under
+pkgs/development/libraries.
+
+When in doubt, consider refactoring the
+pkgs/ tree, e.g. creating new categories or
+splitting up an existing category.
+
+
+
+ If it’s used to support software development:
+
+
+
+ If it’s a library used by other packages:
+
+ development/libraries (e.g. libxml2)
+
+
+
+ If it’s a compiler:
+
+ development/compilers (e.g. gcc)
+
+
+
+ If it’s an interpreter:
+
+ development/interpreters (e.g. guile)
+
+
+
+ If it’s a (set of) development tool(s):
+
+
+
+ If it’s a parser generator (including lexers):
+
+ development/tools/parsing (e.g. bison, flex)
+
+
+
+ If it’s a build manager:
+
+ development/tools/build-managers (e.g. gnumake)
+
+
+
+ Else:
+
+ development/tools/misc (e.g. binutils)
+
+
+
+
+
+
+ Else:
+
+ development/misc
+
+
+
+
+
+
+ If it’s a (set of) tool(s):
+
+ (A tool is a relatively small program, especially one intented
+ to be used non-interactively.)
+
+
+ If it’s for networking:
+
+ tools/networking (e.g. wget)
+
+
+
+ If it’s for text processing:
+
+ tools/text (e.g. diffutils)
+
+
+
+ If it’s a system utility, i.e.,
+ something related or essential to the operation of a
+ system:
+
+ tools/system (e.g. cron)
+
+
+
+ If it’s an archiver (which may
+ include a compression function):
+
+ tools/archivers (e.g. zip, tar)
+
+
+
+ If it’s a compression program:
+
+ tools/compression (e.g. gzip, bzip2)
+
+
+
+ If it’s a security-related program:
+
+ tools/security (e.g. nmap, gnupg)
+
+
+
+ Else:
+
+ tools/misc
+
+
+
+
+
+
+ If it’s a shell:
+
+ shells (e.g. bash)
+
+
+
+ If it’s a server:
+
+
+
+ If it’s a web server:
+
+ servers/http (e.g. apache-httpd)
+
+
+
+ If it’s an implementation of the X Windowing System:
+
+ servers/x11 (e.g. xorg — this includes the client libraries and programs)
+
+
+
+ Else:
+
+ servers/misc
+
+
+
+
+
+
+ If it’s a desktop environment
+ (including window managers):
+
+ desktops (e.g. kde, gnome, enlightenment)
+
+
+
+ If it’s an application:
+
+ A (typically large) program with a distinct user
+ interface, primarily used interactively.
+
+
+ If it’s a version management system:
+
+ applications/version-management (e.g. subversion)
+
+
+
+ If it’s for video playback / editing:
+
+ applications/video (e.g. vlc)
+
+
+
+ If it’s for graphics viewing / editing:
+
+ applications/graphics (e.g. gimp)
+
+
+
+ If it’s for networking:
+
+
+
+ If it’s a mailreader:
+
+ applications/networking/mailreaders (e.g. thunderbird)
+
+
+
+ If it’s a newsreader:
+
+ applications/networking/newsreaders (e.g. pan)
+
+
+
+ If it’s a web browser:
+
+ applications/networking/browsers (e.g. firefox)
+
+
+
+ Else:
+
+ applications/networking/misc
+
+
+
+
+
+
+ Else:
+
+ applications/misc
+
+
+
+
+
+
+ If it’s data (i.e., does not have a
+ straight-forward executable semantics):
+
+
+
+ If it’s a font:
+
+ data/fonts
+
+
+
+ If it’s related to SGML/XML processing:
+
+
+
+ If it’s an XML DTD:
+
+ data/sgml+xml/schemas/xml-dtd (e.g. docbook)
+
+
+
+ If it’s an XSLT stylesheet:
+
+ (Okay, these are executable...)
+ data/sgml+xml/stylesheets/xslt (e.g. docbook-xsl)
+
+
+
+
+
+
+
+
+
+ If it’s a game:
+
+ games
+
+
+
+ Else:
+
+ misc
+
+
+
+
-
-
\ No newline at end of file
+
diff --git a/doc/language-support.xml b/doc/language-support.xml
index 364b002ea16d..806eab62ebe7 100644
--- a/doc/language-support.xml
+++ b/doc/language-support.xml
@@ -1,6 +1,6 @@
+ xml:id="chap-language-support">
Support for specific programming languages
diff --git a/maintainers/docs/classification.txt b/maintainers/docs/classification.txt
deleted file mode 100644
index a4de2ecdb50a..000000000000
--- a/maintainers/docs/classification.txt
+++ /dev/null
@@ -1,116 +0,0 @@
-* Classification scheme for packages
-
-- many packages fall under several categories; what matters is the
- *primary* purpose of a package. For example, the libxml2 package
- builds both a library and some tools; but it's a library foremost,
- so it goes under ./development/libraries.
-
-- when in doubt, refactor.
-
-IF it's used to support SOFTWARE DEVELOPMENT:
-
- IF it's a LIBRARY used by other packages:
- IF it's directly related to GTK:
- ./development/libraries/gtk+
- ELSE
- ./development/libraries
- (e.g., libxml2)
- ELSE IF it's a COMPILER:
- ./development/compilers
- (e.g., gcc)
- ELSE IF it's an INTERPRETER:
- ./development/interpreters
- ELSE IF it's a development TOOL (or set of):
- IF it's a PARSER GENERATOR (incl. lexers):
- ./development/tools/parsing
- (e.g., bison, flex)
- ELSE IF it's a BUILD MANAGER:
- ./development/tools/build-managers
- (e.g., gnumake
- ELSE
- ./development/tools/misc
- (e.g., binutils)
- ELSE
- ./development/misc
-
-ELSE IF it's a TOOL (or set of):
- # a tool is a relatively *small* program, esp. one intented to be
- # used non-interactively
-
- IF it's for NETWORKING:
- ./tools/networking
- (e.g., wget)
- ELSE IF it's for TEXT PROCESSING:
- ./tools/text
- (e.g., diffutils)
- ELSE IF it's a SYSTEM utility, i.e., something related or essential
- to the operation of a system:
- ./tools/system
- (e.g., init)
- ELSE IF it's an ARCHIVER (which may include a compression function):
- ./tools/archivers
- (e.g., zip, tar)
- ELSE IF it's a COMPRESSION program:
- ./tools/compression
- (e.g., gzip, bzip2)
- ELSE IF it's a SECURITY program:
- ./tools/security
- (e.g., nmap, gnupg)
- ELSE
- ./tools/misc
-
-ELSE IF it's a SHELL:
-
- ./shells
-
-ELSE IF it's a SERVER:
-
- IF it's a HTTP server:
- ./servers/http
- (e.g., apache)
- IF it's a X11 server:
- ./servers/x11
- (e.g., xfree86)
- ELSE
- ./servers/misc
-
-ELSE IF it's a DESKTOP ENVIRONMENT (incl. WINDOW MANAGERS):
-
- ./desktops
- (e.g., kde, gnome, fvwm)
-
-ELSE IF it's an APPLICATION:
- # a (typically large) program with a distinct user interface,
- # primarily used interactively
-
- IF it's a VERSION MANAGEMENT system:
- ./applications/version-management
- ELSE IF it's for VIDEO playback/etc:
- ./applications/video
- ELSE IF it's for GRAPHICS viewing/editing/etc:
- ./applications/graphics
- ELSE IF it's for NETWORKING:
- IF it's a MAILREADER:
- ./applications/networking/mailreaders
- IF it's a NEWSREADER:
- ./applications/networking/newsreaders
- ELSE
- ./applications/networking/misc
- ELSE
- ./applications/misc
-
-ELSE IF it's DATA (i.e., does not have a straight-forward executable semantics):
-
- IF it's related to SGML/XML processing:
- IF it's a XML DTD:
- ./data/sgml+xml/schemas/xml-dtd
- ELSE IF it's an XSLT stylesheet (okay, these are executable...):
- ./data/sgml+xml/stylesheets/xslt
-
-ELSE IF it's a GAME:
-
- ./games
-
-ELSE:
-
- ./misc