[Boost-commit] svn:boost r46821 - website/public_html/beta/development

From: bdawes_at_[hidden]
Date: 2008-06-28 16:20:47

Author: bemandawes
Date: 2008-06-28 16:20:47 EDT (Sat, 28 Jun 2008)
New Revision: 46821
URL: http://svn.boost.org/trac/boost/changeset/46821

Log:
Update Directory and Filename requirements, Documentation guidelines.
Text files modified: 
   website/public_html/beta/development/requirements.html |    57 +++++++++++++++++++++++++++------------ 
   1 files changed, 39 insertions(+), 18 deletions(-)

Modified: website/public_html/beta/development/requirements.html
==============================================================================
--- website/public_html/beta/development/requirements.html	(original)
+++ website/public_html/beta/development/requirements.html	2008-06-28 16:20:47 EDT (Sat, 28 Jun 2008)
@@ -8,7 +8,8 @@
   <link rel="icon" href="/favicon.ico" type="image/ico" />
   <link rel="stylesheet" type="text/css" href=
   "/style/section-development.css" />
-  <!--[if IE]> <style type="text/css"> body { behavior: url(/style/csshover.htc); } </style> <![endif]-->
+  <!--[if IE]> <style type="text/css"> body { behavior: url(/style/csshover.htc); } </style> 
+  <![endif]-->
 </head><!--
 Note: Editing website content is documented at:
 http://www.boost.org/development/website_updating.html
@@ -341,8 +342,7 @@
 
                 <li>A comment line referencing your library on the Boost web
                 site. For example:
-                  <pre>
-// See http://www.boost.org/libs/foo for library home page.
+                  <pre>// See http://www.boost.org/libs/foo for library home page.
 </pre>
 
                   <p>Where <code>foo</code> is the directory name (see below)
@@ -411,13 +411,26 @@
               "Directory_structure"></a>Directory Structure and
               Filenames</h3>
 
+              <p>Naming requirements ensure file and directory names are 
+              relatively portable:</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>
+                <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>). 
+                Note that spaces are not allowed.</li>
+                <li>File names, but not directory names, may include one dot 
+                character (<code>&quot;.&quot;</code>); it must not be the first or last 
+                character..</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>Files intended to be processed by a C++ compiler as part
                 of a translation unit should have <strong>a three-letter
@@ -508,8 +521,7 @@
               <p>If the documentation is in a doc sub-directory, the primary
               directory index.html file should just do an automatic
               redirection to the doc subdirectory:</p>
-              <pre>
-&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+              <pre>&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"&gt;
 
 &lt;html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"&gt;
@@ -611,19 +623,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>
 
@@ -656,8 +678,7 @@
               indicate what exceptions may be thrown, or because the
               programmer hopes they will improved performance. But consider
               the following member from a smart pointer:</p>
-              <pre>
-T&amp; operator*() const throw()  { return *ptr; }
+              <pre>T&amp; operator*() const throw()  { return *ptr; }
 </pre>
 
               <p>This function calls no other functions; it only manipulates
@@ -820,4 +841,4 @@
     <div class="clear"></div>
   </div>
 </body>
-</html>
+</html>
\ No newline at end of file