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>"a"</code>-<code>"z"</code>),
+ numbers (<code>"0"</code>-<code>"9"</code>), and underscores (<code>"_"</code>).
+ Spaces are not allowed.</li>
+ <li>File names may include one dot character (<code>"."</code>),
+ but it must not be the first or last character..</li>
+ <li>Directory names must not include dot characters (<code>"."</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 ("hello world") 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>