[Boost-commit] svn:boost r46830 - website/public_html/live/development

From: bdawes_at_[hidden]
Date: 2008-06-28 17:31:32

Author: bemandawes
Date: 2008-06-28 17:31:31 EDT (Sat, 28 Jun 2008)
New Revision: 46830
URL: http://svn.boost.org/trac/boost/changeset/46830

Log:
Update Directory and Filename requirements, Documentation guidelines.
Text files modified: 
   website/public_html/live/development/requirements.html |    46 ++++++++++++++++++++++++++++++--------- 
   1 files changed, 35 insertions(+), 11 deletions(-)

Modified: website/public_html/live/development/requirements.html
==============================================================================
--- website/public_html/live/development/requirements.html	(original)
+++ website/public_html/live/development/requirements.html	2008-06-28 17:31:31 EDT (Sat, 28 Jun 2008)
@@ -411,13 +411,27 @@
               "Directory_structure"></a>Directory Structure and
               Filenames</h3>
 
+              <p>Naming requirements ensure file and directory names are 
+              relatively portable, including to ISO 9660:1999 and other 
+              relatively limited file systems.</p>
+
+              <ul>
+                <li>File and directory names include only
+                <strong>lowercase</strong> ASCII letters (<code>&quot;a&quot;</code>-<code>&quot;z&quot;</code>), 
+                numbers (<code>&quot;0&quot;</code>-<code>&quot;9&quot;</code>), and underscores (<code>&quot;_&quot;</code>). 
+                Spaces are not allowed.</li>
+                <li>File names may include one dot character (<code>&quot;.&quot;</code>), 
+                but it must not be the first or last character..</li>
+                <li>Directory names must not include dot characters (<code>&quot;.&quot;</code>).</li>
+                <li>The first character of both directory and file names must be 
+                alphabetic.</li>
+                <li>The maximum length of directory and file names is 31 
+                characters.</li>
+              </ul>
+
+              <p>Other conventions ease communication:</p>
+
               <ul>
-                <li>File and directory names must contain only
-                <strong>lowercase</strong> ASCII letters, numbers,
-                underscores, and a period. Leading character must be
-                alphabetic. Maximum length 31. Only a single period is
-                permitted. These requirements ensure file and directory names
-                are relatively portable.</li>
 
                 <li>Files intended to be processed by a C++ compiler as part
                 of a translation unit should have <strong>a three-letter
@@ -611,19 +625,29 @@
               <p>Appropriate topics for documentation often include:</p>
 
               <ul>
-                <li>General introduction to the library.</li>
+                <li>General introduction to the library. The introduction 
+                particularly needs to include:<ul>
+                <li>A very high-level overview of what the library is good for, 
+                and perhaps what it isn't good for, understandable even by those 
+                with no prior knowledge of the problem domain.</li>
+                <li>The simplest possible (&quot;hello world&quot;) example of using the 
+                library.</li>
+              </ul>
 
-                <li>Description of each class.</li>
+                </li>
 
-                <li>Relationship between classes.</li>
+                <li>Tutorial covering basic use cases.</li>
 
+                <li>Reference documentation:<ul>
+                <li>Description of each class.</li>
+                <li>Relationship between classes.</li>
                 <li>For each function, as applicable, description,
                 requirements (preconditions), effects, post-conditions,
                 returns, and throws.</li>
-
                 <li>Discussion of error detection and recovery strategy.</li>
+              </ul>
 
-                <li>How to use including description of typical uses.</li>
+                </li>
 
                 <li>How to compile and link.</li>