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>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+ <pre><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
@@ -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& operator*() const throw() { return *ptr; }
+ <pre>T& 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, "Filenames should be constructed from the portable
+ filename character set because the use of other characters can be
+ confusing or ambiguous in certain contexts."</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