On Fri, Feb 19, 2010 at 11:23 AM, Stewart, Robert <Robert.Stewart@sig.com> wrote:
Beman Dawes wrote:
The documentation can be viewed at http://mysite.verizon.net/beman/v3/index.htm
Comments on the tutorial:
Very nicely written. You answered questions that arose as you went along as if you were in my head!
That is really good to hear! I put a lot of hours into the tutorial trying to achieve that effect.
§ Reporting the size of a file
Typo: "file_size function returns an uintmax_t"
s/an/a/
Fixed.
§ Using status queries to determine file existence and type
The code shown for tut2.cpp uses what appears to be inconsistent whitespace inside parentheses. Perhaps your style is to add whitespaces inside parentheses in conditionals, but it looks odd to me.
Ouch... I changed my style from whitespace to no whitespace in the middle of the project, and failed to apply the change uniformly to the tutorial programs. Fixed.
§ Directory iteration
You write, "A directory_entry contains a path and symlink/non-symlink resolving file_status caches, and can be passed to path arguments in function calls." I don't understand that. What are "symlink/non-symlink resolving file_status caches?"
That's really an implementation detail, so I changed to sentence to just say "A directory_entry object contains a path and file_status information."
Split the two parts into separate sentences for clarity.
Done.
tut3.cpp should not create a default constructed directory_iterator each iteration (even if the optimizer could hoist it out of the loop):
for (directory_iterator it(p), end; it != end; ++it)
Perhaps it would be better to use an ostream_iterator.
Done.
§ Class path: Constructors
In tut5.cpp, you commented out two blocks that wouldn't preclude the following two, so why not leave them uncommented?
Changed.
§ Class path: Generic format vs. Native format
It looks like the bold attribute was left on in the beginning of the first paragraph.
Fixed.
Typo: "If a drive specified or a backslash appears"
s/specified/specifier/ (I guess)
Fixed.
§ Class path: Iterators, observers, composition, decomposition, and query
Clarification: "We will only show the output lines we are interested in at the moment."
s/at the moment/at each step/
Changed.
The path_info.cpp element loop also evaluates the end iterator each iteration.
Fixed.
Typo: "Let's look at some at the output from the a slightly different example:"
s/the a/a/
Fixed.
Typo: In the final Linux output box of this section, the last argument to ./path_info is "baz.txt" but the program output suggests that it should be "baa.txt."
Fixed.
§ Error reporting
Clarification: "...and that's why most Boost.Filesystem operational functions come in two flavors."
s/functions come/functions now come/
Clarification: "...by setting the ec argument..."
s/the ec/that/ (there's no signature visible to confirm that "ec" is the name of the mentioned system::error_code & argument)
Section reworked for greater clarity. Links added to reference documentation.
_______________________ Other Issues
There's concern over the term, "stem," expressed by others and me. Did you consider just "name?" I suppose that's too close to "filename," but "stem" is really odd and we should find something better. I think it is easier to explain and remember the difference between "filename" and "name" than to remember the odd meaning of "stem" for a path. That is, with "name," a pathname is a (possibly empty) path plus a filename, where a filename is comprised of a name and an optional extension.
In 2008 we already had several very lengthy discussions of names in this area, and changed several including to improve clarity.
Finally, you use the term "observer" in the path class in an odd way. Those functions are accessors. "Observer" makes me think of MVC, signals/slots, etc.
The "observer" terminology comes from the standard library. Since the reference documentation is basically what will be proposed for TR2, I'd really like to keep it aligned with the standard library's terminology. Thanks very much for your careful reading of the tutorial, and your many suggestions and corrections. They should all be reflected in beta 2. --Beman