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

From: bdawes_at_[hidden]
Date: 2008-07-03 10:43:37

Author: bemandawes
Date: 2008-07-03 10:43:37 EDT (Thu, 03 Jul 2008)
New Revision: 47043
URL: http://svn.boost.org/trac/boost/changeset/47043

Log:
Finalize Directory and File name requirements for 1.36.0. Provide rationale for choices.
Text files modified: 
   website/public_html/beta/development/requirements.html |    99 ++++++++++++++++++++++++++++----------- 
   1 files changed, 70 insertions(+), 29 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-07-03 10:43:37 EDT (Thu, 03 Jul 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
@@ -76,7 +77,8 @@
                     <li><a href="#code_fonts">Source code fonts
                     rationale</a></li>
 
-                    <li>Tabs rationale</li>
+                    <li>Tabs rationale<br>
+                    Directory and filename rationale</li>
 
                     <li><a href="#JavaScript">ECMAScript/JavaScript
                     rationale</a></li>
@@ -341,8 +343,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,29 +412,31 @@
               "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>
+              <p>Naming requirements ensure that file and directory names are
+              relatively portable, including to ISO 9660:1999 (with extensions) and other
+              relatively limited file systems. Superscript links are provided to 
+              detailed rationale for each choice. </p>
+
+              <ul>
+                <li>Names must contain only
+                <strong>lowercase<sup>1</sup></strong> ASCII letters
+                (<code>'a'</code>-<code>'z'</code>), numbers
+                (<code>'0'</code>-<code>'9'</code>), underscores
+                (<code>'_'</code>), hyphens (<code>'-'</code>), and periods (<code>'.'</code>). Spaces are not allowed<sup>2</sup>. </li>
+
+                <li>Directory names must not contain periods (<code>'.'</code>)<sup>3</sup>.</li>
+
+                <li>The first and last character of a file name must not be a 
+                period
+                (<code>'.'</code>)<sup>4</sup>.</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 first character of  names must not
+                be a hyphen (<code>'-'</code>)<sup>5</sup>.</li>
 
                 <li>The maximum length of directory and file names is 31
-                characters.</li>
+                characters<sup>6</sup>. </li>
+
+                <li>The total path length must not exceed 207 characters<sup>7</sup>.</li>
               </ul>
 
               <p>Other conventions ease communication:</p>
@@ -528,8 +531,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;
@@ -694,8 +696,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
@@ -772,6 +773,46 @@
               all use tabs, or all use spaces, and thus the decision to stick
               with spaces.</p>
 
+              <h3><a name="FileNamesRat" id="FileNamesRat"></a>Directory and File Names rationale</h3>
+
+
+              <p><a name="Filename_rationale_1">1</a>. Some legacy file systems 
+              require single-case names. Single-case names eliminate casing 
+              mistakes when moving from case-insensitive to case-sensitive file 
+              systems.</p>
+
+
+              <p><a name="Filename_rationale_2">2</a>. This is the lowercase 
+              portion of the POSIX portable filename character set. To quote the 
+              POSIX standard, &quot;Filenames should be constructed from the portable 
+              filename character set because the use of other characters can be 
+              confusing or ambiguous in certain contexts.&quot;</p>
+
+
+              <p><a name="Filename_Rationale_3">3</a>. Strict implementations of 
+              ISO 9660:1999 and some legacy operating systems prohibit dots in 
+              directory names. The need for this restriction is fading, and it 
+              will probably be removed fairly soon.</p>
+
+
+              <p><a name="Filename_rationale_4">4</a>. POSIX has special rules 
+              for names beginning with a period. Windows prohibits names ending 
+              in a period.</p>
+
+
+              <p><a name="Filename_rationale_5">5</a>. Would be too confusing or 
+              ambiguous in certain contexts.</p>
+
+
+              <p><a name="Filename_rationale_6">6</a>. We had to draw the line 
+              somewhere, and so the limit imposed by a now obsolete Apple file 
+              system was chosen years ago. It still seems a reasonable limit to 
+              aid human comprehension.</p>
+
+
+              <p><a name="Filename_rationale_7">7</a>. ISO 9660:1999.</p>
+
+
               <h3><a name="JavaScript" id=
               "JavaScript"></a>ECMAScript/JavaScript rationale</h3>
 
@@ -858,4 +899,4 @@
     <div class="clear"></div>
   </div>
 </body>
-</html>
+</html>
\ No newline at end of file