diff options
| -rw-r--r-- | doc/coding-conventions.xml | 278 | ||||
| -rw-r--r-- | doc/language-support.xml | 2 | ||||
| -rw-r--r-- | maintainers/docs/classification.txt | 116 |
3 files changed, 277 insertions, 119 deletions
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 <filename>allPackages.nix</filename> or <filename>AllPackages.nix</filename>.</para> -</section> +<para>Each package should be stored in its own directory somewhere in +the <filename>pkgs/</filename> tree, i.e. in +<filename>pkgs/<replaceable>category</replaceable>/<replaceable>subcategory</replaceable>/<replaceable>...</replaceable>/<replaceable>pkgname</replaceable></filename>. +Below are some rules for picking the right category for a package. +Many packages fall under several categories; what matters is the +<emphasis>primary</emphasis> purpose of a package. For example, the +<literal>libxml2</literal> package builds both a library and some +tools; but it’s a library foremost, so it goes under +<filename>pkgs/development/libraries</filename>.</para> + +<para>When in doubt, consider refactoring the +<filename>pkgs/</filename> tree, e.g. creating new categories or +splitting up an existing category.</para> + +<variablelist> + <varlistentry> + <term>If it’s used to support <emphasis>software development</emphasis>:</term> + <listitem> + <variablelist> + <varlistentry> + <term>If it’s a <emphasis>library</emphasis> used by other packages:</term> + <listitem> + <para><filename>development/libraries</filename> (e.g. <filename>libxml2</filename>)</para> + </listitem> + </varlistentry> + <varlistentry> + <term>If it’s a <emphasis>compiler</emphasis>:</term> + <listitem> + <para><filename>development/compilers</filename> (e.g. <filename>gcc</filename>)</para> + </listitem> + </varlistentry> + <varlistentry> + <term>If it’s an <emphasis>interpreter</emphasis>:</term> + <listitem> + <para><filename>development/interpreters</filename> (e.g. <filename>guile</filename>)</para> + </listitem> + </varlistentry> + <varlistentry> + <term>If it’s a (set of) development <emphasis>tool(s)</emphasis>:</term> + <listitem> + <variablelist> + <varlistentry> + <term>If it’s a <emphasis>parser generator</emphasis> (including lexers):</term> + <listitem> + <para><filename>development/tools/parsing</filename> (e.g. <filename>bison</filename>, <filename>flex</filename>)</para> + </listitem> + </varlistentry> + <varlistentry> + <term>If it’s a <emphasis>build manager</emphasis>:</term> + <listitem> + <para><filename>development/tools/build-managers</filename> (e.g. <filename>gnumake</filename>)</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Else:</term> + <listitem> + <para><filename>development/tools/misc</filename> (e.g. <filename>binutils</filename>)</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term>Else:</term> + <listitem> + <para><filename>development/misc</filename></para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term>If it’s a (set of) <emphasis>tool(s)</emphasis>:</term> + <listitem> + <para>(A tool is a relatively small program, especially one intented + to be used non-interactively.)</para> + <variablelist> + <varlistentry> + <term>If it’s for <emphasis>networking</emphasis>:</term> + <listitem> + <para><filename>tools/networking</filename> (e.g. <filename>wget</filename>)</para> + </listitem> + </varlistentry> + <varlistentry> + <term>If it’s for <emphasis>text processing</emphasis>:</term> + <listitem> + <para><filename>tools/text</filename> (e.g. <filename>diffutils</filename>)</para> + </listitem> + </varlistentry> + <varlistentry> + <term>If it’s a <emphasis>system utility</emphasis>, i.e., + something related or essential to the operation of a + system:</term> + <listitem> + <para><filename>tools/system</filename> (e.g. <filename>cron</filename>)</para> + </listitem> + </varlistentry> + <varlistentry> + <term>If it’s an <emphasis>archiver</emphasis> (which may + include a compression function):</term> + <listitem> + <para><filename>tools/archivers</filename> (e.g. <filename>zip</filename>, <filename>tar</filename>)</para> + </listitem> + </varlistentry> + <varlistentry> + <term>If it’s a <emphasis>compression</emphasis> program:</term> + <listitem> + <para><filename>tools/compression</filename> (e.g. <filename>gzip</filename>, <filename>bzip2</filename>)</para> + </listitem> + </varlistentry> + <varlistentry> + <term>If it’s a <emphasis>security</emphasis>-related program:</term> + <listitem> + <para><filename>tools/security</filename> (e.g. <filename>nmap</filename>, <filename>gnupg</filename>)</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Else:</term> + <listitem> + <para><filename>tools/misc</filename></para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term>If it’s a <emphasis>shell</emphasis>:</term> + <listitem> + <para><filename>shells</filename> (e.g. <filename>bash</filename>)</para> + </listitem> + </varlistentry> + <varlistentry> + <term>If it’s a <emphasis>server</emphasis>:</term> + <listitem> + <variablelist> + <varlistentry> + <term>If it’s a web server:</term> + <listitem> + <para><filename>servers/http</filename> (e.g. <filename>apache-httpd</filename>)</para> + </listitem> + </varlistentry> + <varlistentry> + <term>If it’s an implementation of the X Windowing System:</term> + <listitem> + <para><filename>servers/x11</filename> (e.g. <filename>xorg</filename> — this includes the client libraries and programs)</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Else:</term> + <listitem> + <para><filename>servers/misc</filename></para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term>If it’s a <emphasis>desktop environment</emphasis> + (including <emphasis>window managers</emphasis>):</term> + <listitem> + <para><filename>desktops</filename> (e.g. <filename>kde</filename>, <filename>gnome</filename>, <filename>enlightenment</filename>)</para> + </listitem> + </varlistentry> + <varlistentry> + <term>If it’s an <emphasis>application</emphasis>:</term> + <listitem> + <para>A (typically large) program with a distinct user + interface, primarily used interactively.</para> + <variablelist> + <varlistentry> + <term>If it’s a <emphasis>version management system</emphasis>:</term> + <listitem> + <para><filename>applications/version-management</filename> (e.g. <filename>subversion</filename>)</para> + </listitem> + </varlistentry> + <varlistentry> + <term>If it’s for <emphasis>video playback / editing</emphasis>:</term> + <listitem> + <para><filename>applications/video</filename> (e.g. <filename>vlc</filename>)</para> + </listitem> + </varlistentry> + <varlistentry> + <term>If it’s for <emphasis>graphics viewing / editing</emphasis>:</term> + <listitem> + <para><filename>applications/graphics</filename> (e.g. <filename>gimp</filename>)</para> + </listitem> + </varlistentry> + <varlistentry> + <term>If it’s for <emphasis>networking</emphasis>:</term> + <listitem> + <variablelist> + <varlistentry> + <term>If it’s a <emphasis>mailreader</emphasis>:</term> + <listitem> + <para><filename>applications/networking/mailreaders</filename> (e.g. <filename>thunderbird</filename>)</para> + </listitem> + </varlistentry> + <varlistentry> + <term>If it’s a <emphasis>newsreader</emphasis>:</term> + <listitem> + <para><filename>applications/networking/newsreaders</filename> (e.g. <filename>pan</filename>)</para> + </listitem> + </varlistentry> + <varlistentry> + <term>If it’s a <emphasis>web browser</emphasis>:</term> + <listitem> + <para><filename>applications/networking/browsers</filename> (e.g. <filename>firefox</filename>)</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Else:</term> + <listitem> + <para><filename>applications/networking/misc</filename></para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term>Else:</term> + <listitem> + <para><filename>applications/misc</filename></para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term>If it’s <emphasis>data</emphasis> (i.e., does not have a + straight-forward executable semantics):</term> + <listitem> + <variablelist> + <varlistentry> + <term>If it’s a <emphasis>font</emphasis>:</term> + <listitem> + <para><filename>data/fonts</filename></para> + </listitem> + </varlistentry> + <varlistentry> + <term>If it’s related to <emphasis>SGML/XML processing</emphasis>:</term> + <listitem> + <variablelist> + <varlistentry> + <term>If it’s an <emphasis>XML DTD</emphasis>:</term> + <listitem> + <para><filename>data/sgml+xml/schemas/xml-dtd</filename> (e.g. <filename>docbook</filename>)</para> + </listitem> + </varlistentry> + <varlistentry> + <term>If it’s an <emphasis>XSLT stylesheet</emphasis>:</term> + <listitem> + <para>(Okay, these are executable...)</para> + <para><filename>data/sgml+xml/stylesheets/xslt</filename> (e.g. <filename>docbook-xsl</filename>)</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term>If it’s a <emphasis>game</emphasis>:</term> + <listitem> + <para><filename>games</filename></para> + </listitem> + </varlistentry> + <varlistentry> + <term>Else:</term> + <listitem> + <para><filename>misc</filename></para> + </listitem> + </varlistentry> +</variablelist> +</section> -</chapter>
\ No newline at end of file +</chapter> 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 @@ <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" - xml:id="chap-meta"> + xml:id="chap-language-support"> <title>Support for specific programming languages</title> 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 |