[Boost-commit] svn:boost r41500 - in trunk/libs/filesystem: doc example

From: bdawes_at_[hidden]
Date: 2007-11-30 11:44:24

Author: bemandawes
Date: 2007-11-30 11:44:23 EST (Fri, 30 Nov 2007)
New Revision: 41500
URL: http://svn.boost.org/trac/boost/changeset/41500

Log:
Refresh examples, add example build script, reflect that in docs. Apply suggestions from Darren Cook.
Added:
   trunk/libs/filesystem/example/vc++.bat   (contents, props changed)
Text files modified: 
   trunk/libs/filesystem/doc/index.htm         |    29 ++++++++++++++++++++++-------           
   trunk/libs/filesystem/example/file_size.cpp |     4 ++--                                    
   trunk/libs/filesystem/example/simple_ls.cpp |     8 ++++----                                
   3 files changed, 28 insertions(+), 13 deletions(-)

Modified: trunk/libs/filesystem/doc/index.htm
==============================================================================
--- trunk/libs/filesystem/doc/index.htm	(original)
+++ trunk/libs/filesystem/doc/index.htm	2007-11-30 11:44:23 EST (Fri, 30 Nov 2007)
@@ -38,10 +38,11 @@
   <tr>
     <td width="100%" bgcolor="#E8F5FF">
     <a href="#Introduction">Introduction</a><br>
+    Using the library<br>
     <a href="#tutorial">Two-minute tutorial</a><br>
     <a href="#Cautions">Cautions</a><br>
     <a href="#Using_reference_doc">Using the Reference Documentation</a><br>
-    &nbsp;&nbsp;&nbsp;&nbsp;Examples<br>
+    Example programs<br>
     <a href="#Implementation">Implementation</a><br>
     <a href="#narrow-only">Using only narrow character paths</a><br>
     <a href="#Building">Building the object-library</a><br>
@@ -108,7 +109,18 @@
   Library's <i>fstream</i> header, except 
       that files are identified by <i>basic_path</i> objects rather that <i>char *</i>'s.</li>
 </ul>
+<h2><a name="Using">Using</a> the library</h2>
+<p>Boost.Filesystem is implemented as a separately compiled library, so before 
+using it you must install it in a location that can be found by your linker. See
+Building the object-library. </p>
+<p>The library's example directory contains very simple 
+scripts for building the example programs on various 
+platforms. You can use these scripts to see what's needed to compile and link 
+your own programs.</p>
 <h2>Two-minute <a name="tutorial">tutorial</a></h2>
+<p>(A
+<a href="http://beans.seartipy.com/2006/05/10/boost-filesystem-library-writing-portable-c-programs-to-acess-the-filesystem/">
+more elaborate tutorial</a> is also available from Tabrez Iqbal.)</p>
 <p>First some preliminaries:</p>
 <blockquote>
   <pre>#include &quot;boost/filesystem.hpp&quot;   // includes all needed Boost.Filesystem declarations
@@ -178,7 +190,7 @@
     {
       if ( find_file( itr-&gt;path(), file_name, path_found ) ) return true;
     }
-    else if ( itr-&gt;path().leaf() == file_name ) // see below
+    else if ( itr-&gt;leaf() == file_name ) // see below
     {
       path_found = itr-&gt;path();
       return true;
@@ -259,8 +271,8 @@
 BOOST_NO_EXCEPTIONS at the time the filesystem source files are compiled.</p>
 <p>Non-throwing versions are provided of several functions that are often used 
 in contexts where error codes may be the preferred way to report an error.</p>
-<h2><a name="Examples">Examples</a></h2>
-<h3>simple_ls.cpp</h3>
+<h2><a name="Examples">Example programs</a></h2>
+<h3>simple_ls.cpp</h3>
 <p>The example program simple_ls.cpp is 
 given a path as a command line argument. Since the command line argument may be 
 a relative path, the complete path is determined so that messages displayed 
@@ -274,6 +286,8 @@
 <p>Try compiling and executing simple_ls.cpp 
 to see how it works on your system. Try various path arguments to see what 
 happens.</p>
+<h3>file_size.cpp</h3>
+<p>This example program prints the file's size if it is a regular file.</p>
 <h3>Other examples</h3>
 <p>The programs used to generate the Boost regression test status tables use the 
 Filesystem Library extensively.&nbsp; See:</p>
@@ -305,7 +319,8 @@
 macro BOOST_FILESYSTEM_NARROW_ONLY. That may be useful for dealing with legacy 
 compilers or operating systems.</p>
 <h2><a name="Building">Building</a> the object-library</h2>
-<p>The object-library will normally be built automatically. See
+<p>The object-library will  be built automatically if you are using the Boost 
+build system. See
 <a href="../../../more/getting_started.html">Getting Started</a>. It can also be 
 built manually using a Jamfile 
 supplied in directory libs/filesystem/build, or the user can construct an IDE 
@@ -341,7 +356,7 @@
 <h2><a name="Acknowledgements">Acknowledgements</a></h2>
 <p>The Filesystem Library was designed and implemented by Beman Dawes. The 
 original <i>directory_iterator</i> and <i>filesystem_error</i> classes were 
-based on prior work from Dietmar Kühl, as modified by Jan Langer. Thomas Witt 
+based on prior work from Dietmar Kuehl, as modified by Jan Langer. Thomas Witt 
 was a particular help in later stages of initial development. Peter Dimov and 
 Rob Stewart made many useful suggestions and comments over a long period of 
 time. Howard Hinnant helped with internationalization issues.</p>
@@ -540,7 +555,7 @@
 
 <hr>
 <p>Revised
-<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->08 November, 2007<!--webbot bot="Timestamp" endspan i-checksum="39371" --></p>
+<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->30 November, 2007<!--webbot bot="Timestamp" endspan i-checksum="39358" --></p>
 
 <p>© Copyright Beman Dawes, 2002-2005</p>
 <p> Use, modification, and distribution are subject to the Boost Software 

Modified: trunk/libs/filesystem/example/file_size.cpp
==============================================================================
--- trunk/libs/filesystem/example/file_size.cpp	(original)
+++ trunk/libs/filesystem/example/file_size.cpp	2007-11-30 11:44:23 EST (Fri, 30 Nov 2007)
@@ -32,9 +32,9 @@
     return 1;
   }
 
-  if ( fs::is_directory( p ) )
+  if ( !fs::is_regular( p ) )
   {
-    std::cout << "not a file: " << argv[1] << std::endl;
+    std::cout << "not a regular file: " << argv[1] << std::endl;
     return 1;
   }
  

Modified: trunk/libs/filesystem/example/simple_ls.cpp
==============================================================================
--- trunk/libs/filesystem/example/simple_ls.cpp	(original)
+++ trunk/libs/filesystem/example/simple_ls.cpp	2007-11-30 11:44:23 EST (Fri, 30 Nov 2007)
@@ -51,24 +51,24 @@
         if ( fs::is_directory( dir_itr->status() ) )
         {
           ++dir_count;
-          std::cout << dir_itr->path().leaf() << " [directory]\n";
+          std::cout << dir_itr->leaf() << " [directory]\n";
         }
         else if ( fs::is_regular( dir_itr->status() ) )
         {
           ++file_count;
-          std::cout << dir_itr->path().leaf() << "\n";
+          std::cout << dir_itr->leaf() << "\n";
         }
         else
         {
           ++other_count;
-          std::cout << dir_itr->path().leaf() << " [other]\n";
+          std::cout << dir_itr->leaf() << " [other]\n";
         }
 
       }
       catch ( const std::exception & ex )
       {
         ++err_count;
-        std::cout << dir_itr->path().leaf() << " " << ex.what() << std::endl;
+        std::cout << dir_itr->leaf() << " " << ex.what() << std::endl;
       }
     }
     std::cout << "\n" << file_count << " files\n"

Added: trunk/libs/filesystem/example/vc++.bat
==============================================================================
--- (empty file)
+++ trunk/libs/filesystem/example/vc++.bat	2007-11-30 11:44:23 EST (Fri, 30 Nov 2007)
@@ -0,0 +1,5 @@
+set BOOST_ROOT=..\..\..
+rem A more robust script would test for BOOST_ROOT already set in the environment.
+
+cl -EHsc -I%BOOST_ROOT% %* -link -LIBPATH:%BOOST_ROOT%\lib
+