Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r76410 - trunk/libs/filesystem/v3/doc/src
From: bdawes_at_[hidden]
Date: 2012-01-11 12:03:48

Author: bemandawes
Date: 2012-01-11 12:03:43 EST (Wed, 11 Jan 2012)
New Revision: 76410
URL: http://svn.boost.org/trac/boost/changeset/76410

Log:
Docs source work-in-progress
Text files modified:
   trunk/libs/filesystem/v3/doc/src/boost_snippets.html | 22 ++++
   trunk/libs/filesystem/v3/doc/src/source.html | 189 ++++++++++++++++++++-------------------
   trunk/libs/filesystem/v3/doc/src/tr2_snippets.html | 67 +++++++++++++
   3 files changed, 181 insertions(+), 97 deletions(-)

Modified: trunk/libs/filesystem/v3/doc/src/boost_snippets.html
==============================================================================
--- trunk/libs/filesystem/v3/doc/src/boost_snippets.html (original)
+++ trunk/libs/filesystem/v3/doc/src/boost_snippets.html 2012-01-11 12:03:43 EST (Wed, 11 Jan 2012)
@@ -41,6 +41,28 @@
<h1>Reference Documentation</h1>

$endid
+
+$id wording_prefix=
+<h2><a name="Introduction">Introduction</a></h2>
+
+This reference documentation describes components that C++ programs may use
+to perform operations involving file systems, including paths, regular files,
+and directories.
+$endid
+
+$id wording_suffix=
+$endid
+
+$id backmatter=
+© Copyright Beman Dawes, 2002, 2006, 2007, 2009, 2010, 2011
+Distributed under the Boost Software License, Version 1.0. See
+
+www.boost.org/LICENSE_1_0.txt
+Revised
+11 January 2012
+
+$endid
+
</body>

</html>
\ No newline at end of file

Modified: trunk/libs/filesystem/v3/doc/src/source.html
==============================================================================
--- trunk/libs/filesystem/v3/doc/src/source.html (original)
+++ trunk/libs/filesystem/v3/doc/src/source.html 2012-01-11 12:03:43 EST (Wed, 11 Jan 2012)
@@ -8,6 +8,8 @@
<title>
$if $TARGET; == BOOST
 Filesystem V3 Reference
+ $def WHAT "reference documentation"
+ $def SNIPPET_FILE "boost_snippets.html"
 $def HEADER "boost/filesystem.hpp"
 $def NAMESPACE boost
 $def SUBNAMESPACE filesystem
@@ -19,6 +21,8 @@
} // namespace boost"
$else
 Filesystem TR2 Proposal
+ $def WHAT "Clause"
+ $def SNIPPET_FILE "tr2_snippets.html"
 $def HEADER "files"
 $def NAMESPACE std
 $def SUBNAMESPACE files
@@ -33,11 +37,7 @@
</head>

<body>
-$if $TARGET; == BOOST
-$snippet frontmatter "boost_snippets.html"
-$elif $TARGET; == TR2
-$snippet frontmatter "tr2_snippets.html"
-$endif
+$snippet frontmatter "$SNIPPET_FILE;"

<h2><a name="TOC">Table of Contents</a></h2>

@@ -123,7 +123,7 @@
   &nbsp is_regular_file 
   &nbsp is_symlink 
   &nbsp last_write_time 
-     permissions 
+     permissions 
     read_symlink 
   &nbsp remove 
   &nbsp remove_all 
@@ -146,15 +146,70 @@
 </tr>
</table>

-<h2><a name="Introduction">Introduction</a></h2>
+$snippet wording_prefix "$SNIPPET_FILE;"

-This reference documentation describes components that C++ programs may use
-to perform operations involving file systems, including paths, regular files,
-and directories.
+This $WHAT; describes components that perform operations on file systems and
+their components, such as paths, regular files, and directories.
+Operating systems such as MAC OS, UNIX, and Windows are
+mentioned in this $WHAT; for purposes of illustration or to give guidance to
+implementers. No slight to other operating systems is implied or intended.
+<a name="Footnote-3">Footnote 3</a>: MAC OS® is a registered trademark
+of Apple Inc.
+<a name="Footnote-4">Footnote 4</a>: Windows® is a registered
+trademark of Microsoft Corporation.
+
+<h2><a name="Conformance">Conformance</a></h2>
+Behavior is sometimes specified by reference to ISO/IEC 9945:2003, 
+POSIX. How such behavior is actually implemented is unspecified.
+<blockquote>
+[Note: This constitutes an "as if" rule for implementation of
+operating system dependent behavior. Presumably implementations will usually call native
+operating system API's. --end note]
+</blockquote>
+Implementations are encouraged, but not required, to support such behavior
+
+as it is defined by POSIX. Implementations shall document any
+behavior that differs from the POSIX defined behavior. Implementations that do not support exact POSIX behavior are
+encouraged to provide behavior as close to POSIX behavior as is reasonable given the
+limitations of actual operating systems and file systems. If an implementation cannot provide any
+reasonable behavior, the implementation shall report an error in an
+implementation-defined manner.
+<blockquote>
+[Note: Such errors might be reported by an #error directive, a <code>
+static_assert</code>, a <code>filesystem_error</code> exception, a special
+return value, or some other manner. --end note]
+</blockquote>
+Implementations are not required to provide behavior that is not supported by
+a particular file system.
+<blockquote>
+[Example: The <a href="http://en.wikipedia.org/wiki/FAT_filesystem">
+FAT file system</a> used by some memory cards, camera memory, and floppy discs
+does not support hard links, symlinks, and many other features of more capable
+file systems. Implementations are only required to support the FAT features
+supported by the host operating system. -- end example]
+</blockquote>
+Specific operating systems such as OpenVMS,
+UNIX, and Windows are mentioned only for purposes of illustration or to
+give guidance to users and implementers. No slight to other operating systems is implied
+or intended. When unlikely to cause confusion, the term POSIX is
+sometimes used to refer to "POSIX-compliant operating systems".
+The behavior of functions described in this
+reference
+may differ from their specification in
+the presence of file system races. No diagnostic is required.
+If the possibility of a file system race would make it unreliable for a program to
+test for a precondition before calling a function described in this $WHAT;, 
+Requires is not specified for the condition. Instead, the condition is
+specified as a Throws condition.
+<blockquote>
+[Note: As a design practice, preconditions are not specified when it
+is unreasonable for a program to detect them prior to calling the function. 
+-- end note]
+</blockquote>
<h2><a name="Definitions">Definitions</a></h2>
The following definitions shall apply throughout this reference documentation:
<a name="File">File</a>: An object that can be written to, or read from, or both. A file
-has certain attributes, including type. Common types of files include regular files
+has certain attributes, including type. File types include regular files
and directories. Other types of files, such as symbolic links, may be supported by the
implementation.
<a name="File-system">File system</a>: A collection of files and certain of their attributes.
@@ -177,7 +232,7 @@
A pathname is the concrete representation of a path. --end note]
<a name="Absolute-path">Absolute path</a>: A path that
unambiguously
-identifies the location of a file within a filesystem without reference to an
+identifies the location of a file within a file system without reference to an
additional starting location. The format is implementation defined. 
<blockquote>
 [Note: For POSIX-like implementations, including Unix
@@ -189,16 +244,15 @@
 specifier followed by a slash, or begin with two slashes, are absolute paths. --end
 note]
</blockquote>
-<a name="Relative-path">Relative path</a>: A path that only
+<a name="Relative-path">Relative path</a>: A path that only
unambiguously
identifies the location of a file within a filesystem when resolved relative to
a starting location. The format is implementation defined. [Note:
Paths "." and ".." are considered to be relative paths. --end note]
-<a name="Canonical-path">Canonical path</a>: An absolute path that has
+<a name="Canonical-path">Canonical path</a>: An absolute path that has
no elements which are symbolic links, and no dot or dot dot elements.
<a name="Pathname">Pathname</a>: A character string that represents a
-path. Pathnames are formatted according to the generic pathname format or the
-implementation defined
+path. Pathnames are formatted according to the generic pathname format or an implementation defined
native pathname format.
<a name="generic-pathname-format">Generic pathname format:</a>
<blockquote>
@@ -210,7 +264,7 @@
implementation-defined
<blockquote>
 <blockquote>
-[Note: Most POSIX and Windows based operating system define a name
+[Note: Most POSIX and Windows based operating systems define a name
beginning with two slashes (or backslashes, for Windows) as a root-name
identifying network locations. Windows defines a single letter followed by a
<code>":"</code> as a root-name identifying a disc drive. --end note]
@@ -264,61 +318,13 @@
If the file pointed to does not exist, the symbolic link is said to be a
"dangling" symbolic link. -- end note] 
</blockquote>
-<a name="Race-condition">Race condition</a>: The condition that occurs
+<a name="Race-condition">File system race</a>: The condition that occurs
when multiple threads, processes, or computers interleave access and
modification of
the same object within a file system.
<a name="Dot">Dot</a>, Dot Dot: Synonyms for the filenames <code>"."</code>
and <code>".."</code>, respectively. The dot filename names the current
directory. The dot dot filename names the parent directory.
-<h2><a name="Conformance">Conformance</a></h2>
-Behavior is sometimes specified by reference to ISO/IEC 9945:2003, 
-POSIX. How such behavior is actually implemented is unspecified.
-<blockquote>
-[Note: This constitutes an "as if" rule for implementation of
-operating system dependent behavior. Presumably implementations will usually call native
-operating system API's. --end note]
-</blockquote>
-Implementations are encouraged, but not required, to support such behavior
-
-as it is defined by POSIX. Implementations shall document any
-behavior that differs from the POSIX defined behavior. Implementations that do not support exact POSIX behavior are
-encouraged to provide behavior as close to POSIX behavior as is reasonable given the
-limitations of actual operating systems and file systems. If an implementation cannot provide any
-reasonable behavior, the implementation shall report an error in an
-implementation-defined manner.
-<blockquote>
-[Note: Such errors might be reported by an #error directive, a <code>
-static_assert</code>, a <code>filesystem_error</code> exception, a special
-return value, or some other manner. --end note]
-</blockquote>
-Implementations are not required to provide behavior that is not supported by
-a particular file system.
-<blockquote>
-[Example: The <a href="http://en.wikipedia.org/wiki/FAT_filesystem">
-FAT file system</a> used by some memory cards, camera memory, and floppy discs
-does not support hard links, symlinks, and many other features of more capable
-file systems. Implementations are only required to support the FAT features
-supported by the host operating system. -- end example]
-</blockquote>
-Specific operating systems such as OpenMVS,
-UNIX, and Windows are mentioned only for purposes of illustration or to
-give guidance to users and implementers. No slight to other operating systems is implied
-or intended. When unlikely to cause confusion, the term POSIX is
-sometimes used to refer to "POSIX-compliant operating systems".
-The behavior of functions described in this
-reference
-may not be achieved in
-the presence of race conditions. No diagnostic is required.
-If the possibility of race conditions would make it unreliable for a program to
-test for a precondition before calling a function described in this clause, 
-Requires is not specified for the condition. Instead, the condition is
-specified as a Throws condition.
-<blockquote>
-[Note: As a design practice, preconditions are not specified when it
-is unreasonable for a program to detect them prior to calling the function. 
--- end note]
-</blockquote>
<h2><a name="Header-filesystem-synopsis">Header <code><$HEADER;></code> synopsis</a></h2>
<pre>$NAMESPACE_BEGIN;
 class path;
@@ -1368,7 +1374,7 @@
$NAMESPACE_END;</pre>
The class template <code>basic_filesystem_error</code> defines the type of
objects thrown as exceptions to report file system errors from functions described in this
-clause.
+$WHAT;.
<h4> <a name="filesystem_error-members"> <code>filesystem_error</code> members</a></h4>
<pre><a name="filesystem_error-2-arg">filesystem_error</a>(const std::string& what_arg, error_code ec);</pre>
<blockquote>
@@ -1608,7 +1614,7 @@
<tr><td><code><a name="sticky_bit">sticky_bit</a> </code> </td><td><code>01000</code></td><td> <code>S_ISVTX</code></td>
 <td> Meaning varies; see http:en.wikipedia.org/wiki/Sticky_bit</td>
</tr>
-<tr><td><code>perms_mask</code></td><td><code>07777</code></td><td>  </td>
+<tr><td><code><a name="perms_mask">perms_mask</a></code></td><td><code>07777</code></td><td>  </td>
 <td><code>all_all | set_uid_on_exe | set_gid_on_exe | sticky_bit</code></td>
</tr>
<tr><td><code>perms_not_known</code></td><td><code>0xFFFF</code></td><td></td><td>
@@ -1745,7 +1751,7 @@
[Note: Because <code>status()</code>on a pathname may be a very expensive operation,
some operating systems provide status information as a byproduct of directory
iteration. Caching such status information can result is significant time savings. Cached and
-non-cached results may differ in the presence of race conditions. -- end note]
+non-cached results may differ in the presence of file system races. -- end note]
Actual cold-boot timing of iteration over
a directory with 15,047 entries was six seconds for non-cached status queries
versus one second for cached status queries. Windows XP, 3.0 GHz processor, with
@@ -2200,7 +2206,7 @@
<a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap04.html#tag_04_11">
Pathname Resolution</a> mechanism.
[Note: Because hardware failures, network failures,
-race conditions, and many
+file system races, and many
other kinds of errors occur frequently in file system operations, users should be aware
that any filesystem operational function, no matter how apparently innocuous, may encounter
an error. See Error reporting. -- end note]
@@ -2345,20 +2351,20 @@
</blockquote>
<pre>void <a name="create_directory_symlink">create_directory_symlink</a>(const path& to, const path& new_symlink);
void create_directory_symlink(const path& to, const path& new_symlink, system::error_code& ec);</pre>
-<blockquote style="font-size: 10pt">
- Effects:
+<blockquote>
+ Effects:
 Establishes the postcondition, as if by 
 POSIX
 <code>
 <a href="http://www.opengroup.org/onlinepubs/000095399/functions/symlink.html">
 symlink()</a></code>.
- 
+ 
 Postcondition: <code>new_symlink</code> resolves to a symbolic link file that
 contains an unspecified representation of <code>to</code>.
- Throws: As specified in
+ Throws: As specified in
 <a href="#Error-reporting">
 Error reporting</a>.
- [Note:
+ [Note:
 Some operating systems, such as Windows, require symlink creation to
 identify that the link is to a directory. Portable code should use <code>
 create_directory_symlink()</code> to create directory symlinks rather than
@@ -2661,13 +2667,11 @@
 new_time</code> is not specified since it might not hold for file systems
 with coarse time granularity. -- end note]
</blockquote>
-<pre>void permissions(const path& p, perms prms);
+<pre>void <a name="permissions">permissions</a>(const path& p, perms prms);
void permissions(const path& p, perms prms, system::error_code& ec);</pre>
<blockquote>
- Applies an operating system set of permissions to a file. See
- perms for specifics. 
- 
- Requires: <code>!((prms & add_perms) && (prms & remove_perms))</code>.
+ 
+ Requires: <code>!((prms & add_perms) && (prms & remove_perms))</code>.
 Effects: Applies the effective permissions bits from <code>
 prms</code> to the file <code>p</code> resolves to, as if by POSIX
 <code>
@@ -2686,16 +2690,19 @@
 <tr>
 <td><code>add_perms</code></td>
 <td>
- current_status.permissions() | (<code>prms & perms_mask</code>)
+ <code>status(p).permissions() | (prms &
+ perms_mask)</code>
 </td>
 </tr>
 <tr>
 <td><code>remove_perms</code></td>
- <td>current_status.permissions() & ~(<code>prms & perms_mask</code>) </td>
+ <td><code>status(p)</code><code>.permissions() & ~(prms &
+ perms_mask)
+ </code> </td>
 </tr>
 </table>
 [Note: Conceptually permissions are viewed as bits, but the actual
- implementation by a file system may use some other mechanism. -- end note]
+ implementation may use some other mechanism. -- end note]
</blockquote>
<pre>path <a name="read_symlink">read_symlink</a>(const path& p);
path read_symlink(const path& p, system::error_code& ec);</pre>
@@ -2860,7 +2867,8 @@
 return <code>
 file_status(regular_file)</code>. [Note: <code>
regular_file</code> implies appropriate <code><fstream></code> operations
- would succeed, assuming no hardware, permission, access, or race condition
+ would succeed, assuming no hardware, permission, access, or file system
+ race
 errors. Lack of
<code>regular_file</code> does not necessarily imply <code><fstream></code> operations would
fail on a directory.
@@ -3044,6 +3052,8 @@
 typedef basic_ofstream<wchar_t> wofstream;

$NAMESPACE_END;</pre>
+$snippet wording_suffix "$SNIPPET_FILE;"
+
<h2><a name="Path-decomposition-table">Path decomposition table</a></h2>
The table is generated by a program compiled with the Boost implementation.
Shaded entries indicate cases where POSIX and Windows
@@ -3594,13 +3604,12 @@
final document.
Peter Dimov suggested a single class path, with member templates to adapt to
multiple string types. His idea became the basis for the version 3 path design.
- 
<h2><a name="References">References</a></h2>
<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="100%">
 <tr>
 <td width="16%" valign="top">[<a name="ISO_POSIX">ISO-POSIX</a>]</td>
 <td width="84%">ISO/IEC 9945:2003, IEEE Std 1003.1-2001, and The Open Group
- Base Specifications, Issue 6. Also known as The Single UnixÂ®
+ Base Specifications, Issue 6. Also known as The Single Unix®
 Specification, Version 3. Available from each of the organizations involved
 in its creation. For example, read online or download from
 <a href="http://www.unix.org/single_unix_specification/">
@@ -3616,13 +3625,7 @@
 </tr>
</table>
<hr>
-Â© Copyright Beman Dawes, 2002, 2006, 2007, 2009, 2010, 2011
-Distributed under the Boost Software License, Version 1.0. See
-
-www.boost.org/LICENSE_1_0.txt
-Revised
-10 January 2012
-
+$snippet backmatter "$SNIPPET_FILE;"
</body>

</html>
\ No newline at end of file

Modified: trunk/libs/filesystem/v3/doc/src/tr2_snippets.html
==============================================================================
--- trunk/libs/filesystem/v3/doc/src/tr2_snippets.html (original)
+++ trunk/libs/filesystem/v3/doc/src/tr2_snippets.html 2012-01-11 12:03:43 EST (Wed, 11 Jan 2012)
@@ -13,12 +13,12 @@
 <table border="0" cellpadding="0" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="579">
 <tr>
 <td width="153" align="left" valign="top">Document number:</td>
- <td width="426">N3239 = 11-0009</td>
+ <td width="426">D3335=12-0025</td>
 </tr>
 <tr>
 <td width="153" align="left" valign="top">Date:</td>
 <td width="426">
- 2012-01-10</td>
+ 2012-01-11</td>
 </tr>
 <tr>
 <td width="153" align="left" valign="top">Project:</td>
@@ -31,7 +31,7 @@
 </table>

-<h1>Filesystem Library Update for TR2 (Preliminary)</h1>
+<h1>Filesystem Library for C++11/TR2 (Revision 1)</h1>

This paper proposes that the filesystem library component of C++ Standard
@@ -120,7 +120,66 @@
 <h2>Revisions</h2>
 TBS

- $endid
+$endid
+
+$id wording_prefix=
+<h2>Proposed Wording</h2>
+
+
+Gray-shaded italic text is commentary on the proposal. It is not to be added to
+the TR.
+<blockquote>
+ <table style="border-collapse: collapse" bgcolor="#E0E0E0" border="1" bordercolor="#111111" cellpadding="7" cellspacing="0">
+ <tr>
+ <td>The following wording is a lighted
+ edited version of the Boost Filesystem reference documentation. Although
+ further editing is required, the features described are relatively stable
+ and major feature changes are not anticipated. </td>
+ </tr>
+ </table>
+</blockquote>
+Add the following
+to the Technical Report's front matter:
+The following standard contains provisions which, through reference in this
+text, constitute provisions of this Technical Report. At the time of
+publication, the editions indicated were valid. All standards are subject to
+revision, and parties to agreements based on this Technical Report are
+encouraged to investigate the possibility of applying the most recent editions
+of the standard indicated below. Members of IEC and ISO maintain registers of
+currently valid International Standards.
+<ul>
+ <li>ISO/IEC 9945:2003, Portable Operating System Interface (POSIX¹),
+ part 1 (Base Definitions) and part 2 (System Interfaces), both as
+ corrected by their respective 2004 Correction 1 documents.[Note:
+ ISO/IEC 9945:2003 is also IEEE Std 1003.1-2001, and The Open Group Base
+ Specifications, Issue 6, and is also known as The Single Unix2
+ Specification, Version 3. It is available from each of those
+ organizations, and may be read online or downloaded from
+ <a href="http://www.unix.org/single_unix_specification/">
+ www.unix.org/single_unix_specification/</a> -- end note]</li>
+</ul>
+ISO/IEC 9945:2003, with the indicated corrections, is hereinafter called 
+POSIX.
+<a name="Footnote-1">Footnote 1</a>: POSIX® is a registered trademark
+of The IEEE.
+<a name="Footnote-2">Footnote 2</a>: UNIX® is a registered trademark
+of The Open Group.
+Add the following
+to the Technical Report as a new Clause:
+<h2>Filesystem Library</h2>
+
+$endid
+
+$id wording_suffix=
+
+
+End of proposed wording.
+<hr>
+$endid
+
+$id backmatter=
+$endid
+
</body>

</html>
\ No newline at end of file

Date view	Thread view	Subject view	Author view

Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk