[std] Rephrase notes giving advice to the programmer.

Partially addresses ISO/CS 017 (C++20 DIS)

Author: jensmaurer

source/algorithms.tex

@@ -203,10 +203,11 @@
 \pnum
 \begin{note}
 Unless otherwise specified, algorithms that take function objects as arguments
-are permitted to copy those function objects freely.
-Programmers for whom object identity is important should consider
-using a wrapper class that points to a noncopied implementation object
-such as \tcode{reference_wrapper<T>}\iref{refwrap}, or some equivalent solution.
+can copy those function objects freely.
+If object identity is important,
+a wrapper class that points to a noncopied implementation object
+such as \tcode{reference_wrapper<T>}\iref{refwrap}, or some equivalent solution,
+can be used.
 \end{note}
 
 \pnum
@@ -390,11 +391,11 @@
 \begin{note}
 This implies that user-supplied function objects cannot rely on
 object identity of arguments for such input sequences.
-Users for whom the object identity of the arguments to these function objects
-is important should consider using a wrapping iterator
+If object identity of the arguments to these function objects
+is important, a wrapping iterator
 that returns a non-copied implementation object
-such as \tcode{reference_wrapper<T>}\iref{refwrap}
-or some equivalent solution.
+such as \tcode{reference_wrapper<T>}\iref{refwrap},
+or some equivalent solution, can be used.
 \end{note}
 
 \pnum

source/containers.tex

@@ -773,18 +773,16 @@
 \pnum
 \begin{note}
 The sequence containers
-offer the programmer different complexity trade-offs and should be used
-accordingly.
+offer the programmer different complexity trade-offs.
 \tcode{vector}
-is the type of sequence container that should be used by default.
+is appropriate in most circumstances.
 \tcode{array}
-should be used when the container has a fixed size known during translation.
+has a fixed size known during translation.
 \tcode{list} or \tcode{forward_list}
-should be used when there are frequent insertions and deletions from the
+support frequent insertions and deletions from the
 middle of the sequence.
 \tcode{deque}
-is the data structure of choice
-when most insertions and deletions take place at the beginning or at the
+supports efficient insertions and deletions taking place at the beginning or at the
 end of the sequence.
 When choosing a container, remember \tcode{vector} is best;
 leave a comment to explain if you choose from the rest!

source/diagnostics.tex

@@ -843,9 +843,10 @@
 \begin{note}
 \tcode{error_category} objects are
 passed by reference, and two such objects
-are equal if they have the same address. This means that applications using
-custom \tcode{error_category} types should create a single object of each
-such type.
+are equal if they have the same address.
+If there is more than a single object of a custom \tcode{error_category} type,
+such equality comparisons can evaluate to \tcode{false}
+even for objects holding the same value.
 \end{note}
 
 \indexlibraryglobal{error_category}%

source/exceptions.tex

@@ -355,8 +355,8 @@
 \end{codeblock}
 \end{example}
 \begin{note}
-\setlength{\emergencystretch}{1em}
-Consequently, destructors should generally catch exceptions and not let them propa\-gate.
+If a destructor directly invoked by stack unwinding exits via an exception,
+\tcode{std::terminate} is invoked.
 \end{note}
 
 

source/iostreams.tex

@@ -11153,8 +11153,8 @@
 \pnum
 \begin{note}
 The member functions of the provided stream buffer
-might be called from \tcode{emit()} while a lock is held.
-Care should be taken to ensure that this does not result in deadlock.
+can be called from \tcode{emit()} while a lock is held,
+which might result in a deadlock if used incautiously.
 \end{note}
 
 \pnum
@@ -11988,7 +11988,7 @@
       the ASCII control characters (0x00 -- 0x1F) in filenames.
 \end{example}
 \begin{note}
-For wide portability, users may wish to limit \grammarterm{filename}
+Wider portability can be achieved by limiting \grammarterm{filename}
 characters to the POSIX Portable Filename Character Set: \\
 \tcode{A B C D E F G H I J K L M N O P Q R S T U V W X Y Z} \\
 \tcode{a b c d e f g h i j k l m n o p q r s t u v w x y z} \\
@@ -14616,11 +14616,11 @@
 
 \pnum
 \begin{note}
-Programs performing directory iteration may wish to test if the
-path obtained by dereferencing a directory iterator actually exists. It could be
-a symbolic link to a non-existent file. Programs recursively
-walking directory trees for purposes of removing and renaming entries may wish
-to avoid following symbolic links.
+A path obtained by dereferencing a directory iterator might not actually exist;
+it could be a symbolic link to a non-existent file.
+Recursively walking directory trees
+for purposes of removing and renaming entries
+might invalidate symbolic links that are being followed.
 \end{note}
 
 \pnum
@@ -15141,9 +15141,9 @@
 \pnum
 \begin{note}
 Because hardware failures, network failures, file system races\iref{fs.race.behavior},
-and many other kinds of errors occur frequently in file system operations, users should be aware
-that any filesystem operation function, no matter how apparently innocuous, may encounter
-an error; see~\ref{fs.err.report}.
+and many other kinds of errors occur frequently in file system operations,
+any filesystem operation function, no matter how apparently innocuous,
+can encounter an error; see~\ref{fs.err.report}.
 \end{note}
 
 \rSec3[fs.op.absolute]{Absolute}
@@ -15634,7 +15634,9 @@
 \pnum
 \begin{note}
 Some operating systems require symlink creation to
-  identify that the link is to a directory. Portable code should use \tcode{create_directory_symlink()} to create directory symlinks rather than \tcode{create_symlink()}
+identify that the link is to a directory.
+Thus, \tcode{create_symlink()} (instead of \tcode{create_directory_symlink()})
+cannot be used reliably to create directory symlinks.
 \end{note}
 
 \pnum

source/lex.tex

@@ -184,7 +184,7 @@
 source of the translation units containing these definitions is required
 to be available.
 \begin{note}
-An implementation could encode sufficient
+An implementation can choose to encode sufficient
 information into the translated translation unit so as to ensure the
 source is not required here.
 \end{note}

source/lib-intro.tex

@@ -3051,13 +3051,6 @@
 Objects constructed by the standard library that may hold a user-supplied pointer value
 or an integer of type \tcode{std::intptr_t} shall store such values in a traceable
 pointer location\iref{basic.stc.dynamic.safety}.
-\begin{note}
-Other libraries are
-strongly encouraged to do the same, since not doing so may result in accidental use of
-pointers that are not safely derived. Libraries that store pointers outside the user's
-address space should make it appear that they are stored and retrieved from a traceable
-pointer location.
-\end{note}
 
 \rSec3[value.error.codes]{Value of error codes}
 

source/preprocessor.tex

@@ -711,11 +711,12 @@
 
 \pnum
 \begin{note}
-Although an implementation can provide a mechanism for making arbitrary
-source files available to the \tcode{< >} search, in general
-programmers should use the \tcode{< >} form for headers provided
-with the implementation, and the \tcode{" "} form for sources
-outside the control of the implementation. For instance:
+An implementation can provide a mechanism for making arbitrary
+source files available to the \tcode{< >} search.
+However, using the \tcode{< >} form for headers provided
+with the implementation and the \tcode{" "} form for sources
+outside the control of the implementation
+achieves wider portability. For instance:
 
 \begin{codeblock}
 #include <stdio.h>

source/strings.tex

@@ -3947,7 +3947,7 @@
 \pnum
 \begin{note}
 The library provides implicit conversions from \tcode{const charT*} and \tcode{std::basic_string<charT, ...>} to \tcode{std::basic_string_view<charT, ...>} so that user code can accept just \tcode{std::basic_string_view<charT>} as a non-templated parameter wherever a sequence of characters is expected.
-User-defined types should define their own implicit conversions to \tcode{std::basic_string_view} in order to interoperate with these functions.
+User-defined types can define their own implicit conversions to \tcode{std::basic_string_view} in order to interoperate with these functions.
 \end{note}
 
 \rSec2[string.view.synop]{Header \tcode{<string_view>} synopsis}

source/support.tex

@@ -1985,7 +1985,7 @@
 A function registered via \tcode{at_quick_exit}
 is invoked by the thread that calls \tcode{quick_exit},
 which can be a different thread
-than the one that registered it, so registered functions should not rely on the identity
+than the one that registered it, so registered functions cannot rely on the identity
 of objects with thread storage duration.
 \end{note}
 After calling registered functions, \tcode{quick_exit} shall call \tcode{_Exit(status)}.