[project @ 2001-12-21 15:07:20 by simonmar]

[haskell-directory.git] / doc / libraries.sgml

diff --git a/doc/libraries.sgml b/doc/libraries.sgml
index 2649483..7f4b230 100644 (file)
--- a/doc/libraries.sgml
+++ b/doc/libraries.sgml
@@ -261,6 +261,8 @@
     <para>We first classify each node in the hierarchy according to
     one of the following terms:</para>
 
+    ToDo: unpublished interfaces.
+
     <variablelist>
       <varlistentry>
        <term>Allocated</term>
@@ -278,10 +280,14 @@
          <para>The <literal>User</literal> hierarchy is reserved for
          users: a user may always use the portion of the hierarchy
          which is formed from his/her email address as follows:
-         replace the <literal>@</literal> by a <literal>.</literal>,
-         reverse the order of the components, capitalise the first
-         letter of each component, and prepend
-         <literal>User.</literal>.  For example,
+         replace any <quote><literal>.</literal></quote>s in the
+         username (before the <literal>@</literal>) with
+         <quote><literal>_</literal></quote>, replace the
+         <quote><literal>@</literal></quote> by a
+         <quote><literal>.</literal></quote>, reverse the order of
+         the components, capitalise the first letter of each
+         component, and prepend
+         <quote><literal>User.</literal></quote>.  For example,
          <literal>simonmar@microsoft.com</literal> becomes
          <literal>User.Com.Microsoft.Simonmar</literal>.</para>
        </listitem>
@@ -360,6 +366,25 @@
         are never grouped by standards compliance, portability,
         stability, or any other property.</para>
       </blockquote>
+
+      <para>There are some other considerations when choosing where to
+      place libraries.  Where possible, choose a layout that finds a
+      good compromise between depth of nesting and logical grouping of
+      functionality; for example, although the <literal>Text</literal>
+      hierarchy could logically be placed as a child of
+      <literal>FileFormat</literal>, we choose not to because
+      <literal>Text</literal> is ubiquitous and we don't want to have
+      to type the extra component all the time.</para>
+
+      <para>Also consider consistency: if a particular sub-hierarchy
+      provides similar functionality to another sub-hierarchy in the
+      tree, then preferably the structure of the two subtrees should
+      also be similar.  For example: under
+      <literal>Language.Haskell</literal> we have children
+      <literal>Syntax</literal>, <literal>Lexer</literal>,
+      <literal>Parser</literal> etc., so under
+      <literal>Language.C</literal> we should have a similar
+      structure.</para>
     </sect2>
 
     <sect2 id="module-naming-convention">
@@ -631,10 +656,15 @@ import Text.HTML.Internals -- The non-abstract library
     <literal>Foreign</literal>, <emphasis>ToDo: what
     else?</emphasis>.</para>
 
+    <para>There is one further requirement: only licenses approved by
+    the Open Source Initiative may be used with the core libraries.
+    See <ulink url="http://www.opensource.org//">The Open Source
+    Initiative</ulink> for a list of approved licensees.</para>
+
     <para><emphasis>ToDo: include a prototype BSD license
     here</emphasis>.</para>
   </sect1>
-    
+
   <sect1 id="versioning">
     <title>Versioning</title>
     <para></para>
@@ -987,7 +1017,7 @@ import Text.HTML.Internals -- The non-abstract library
 -- Stability   :  experimental | provisional | stable
 -- Portability :  portable | non-portable (<replaceable>reason(s)</replaceable>)
 --
--- $Id: libraries.sgml,v 1.5 2001/08/30 13:36:00 simonmar Exp $
+-- $Id: libraries.sgml,v 1.6 2001/12/21 15:07:26 simonmar Exp $
 --
 -- <replaceable>Description</replaceable>
 -----------------------------------------------------------------------------
@@ -997,7 +1027,7 @@ import Text.HTML.Internals -- The non-abstract library
 
       <variablelist>
        <varlistentry>
-         <term><literal>$Id: libraries.sgml,v 1.5 2001/08/30 13:36:00 simonmar Exp $</literal></term>
+         <term><literal>$Id: libraries.sgml,v 1.6 2001/12/21 15:07:26 simonmar Exp $</literal></term>
          <listitem>
            <para>is optional, but usually included if the module is
            under CVS or RCS control.</para>
@@ -1393,6 +1423,7 @@ e.g. <literal>fromInteger</literal>.</para>
 
     Numeric -> Numeric
        added showHex, showOct, showBin & showIntAtBase from NumExts,
+       (not exported yet - these aren't H98)
        but left out floatToDouble & doubleToFloat (realToFrac is more general).
 
     System    -> System.Exit, System.Environment, System.Cmd
@@ -1405,6 +1436,7 @@ e.g. <literal>fromInteger</literal>.</para>
     Directory -> System.IO.Directory
     Ix        -> Data.Ix
     Locale    -> System.Locale
+    Maybe     -> Data.Maybe
     Monad     -> Data.Monad
     Random    -> System.Random
     Ratio     -> Data.Ratio