From c8cc0747faef2af6f36e4aeefa06b19a4883990f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mael=20Rouxel-Labb=C3=A9?=
 <mael.rouxel.labbe@geometryfactory.com>
Date: Mon, 27 Sep 2021 15:33:42 +0200
Subject: [PATCH] Clarify binary warning

---
 BGL/include/CGAL/boost/graph/IO/PLY.h                     | 6 ++++--
 BGL/include/CGAL/boost/graph/IO/STL.h                     | 6 ++++--
 Point_set_3/include/CGAL/Point_set_3/IO.h                 | 6 ++++--
 Point_set_3/include/CGAL/Point_set_3/IO/LAS.h             | 4 ++--
 Point_set_3/include/CGAL/Point_set_3/IO/PLY.h             | 6 ++++--
 Point_set_processing_3/include/CGAL/IO/read_las_points.h  | 4 ++--
 Point_set_processing_3/include/CGAL/IO/read_ply_points.h  | 4 ++--
 Point_set_processing_3/include/CGAL/IO/write_las_points.h | 4 ++--
 Point_set_processing_3/include/CGAL/IO/write_ply_points.h | 8 ++++++--
 Stream_support/doc/Stream_support/IOstream.txt            | 6 ++++--
 Stream_support/doc/Stream_support/PackageDescription.txt  | 2 +-
 Stream_support/include/CGAL/IO/PLY.h                      | 6 ++++--
 Stream_support/include/CGAL/IO/STL.h                      | 6 ++++--
 Surface_mesh/include/CGAL/Surface_mesh/IO/PLY.h           | 6 ++++--
 14 files changed, 47 insertions(+), 27 deletions(-)

diff --git a/BGL/include/CGAL/boost/graph/IO/PLY.h b/BGL/include/CGAL/boost/graph/IO/PLY.h
index 881d3f86b0d..2d6b3d55661 100644
--- a/BGL/include/CGAL/boost/graph/IO/PLY.h
+++ b/BGL/include/CGAL/boost/graph/IO/PLY.h
@@ -84,7 +84,7 @@ bool read_PLY_BGL(std::istream& is,
 
   The data is expected to represent a 2-manifold (possibly with borders).
 
-  \attention When reading a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ifstream`.
+  \attention To read a binary file, the flag `std::ios::binary` must be set during the creation of the `ifstream`.
 
   \tparam Graph a model of `MutableFaceGraph`
   \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters"
@@ -266,7 +266,9 @@ bool read_PLY(const std::string& fname, Graph& g,
 
  \brief writes the graph in an output stream, using the \ref IOStreamPLY.
 
- \attention When writing a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ofstream`.
+ \attention To write to a binary file, the flag `std::ios::binary` must be set during the creation
+            of the `ofstream`, and the \link PkgStreamSupportEnumRef `IO::Mode` \endlink
+            of the stream must be set to `BINARY`.
 
  \tparam Graph a model of `FaceListGraph`
  \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters"
diff --git a/BGL/include/CGAL/boost/graph/IO/STL.h b/BGL/include/CGAL/boost/graph/IO/STL.h
index 7bce5d9734b..b9041e25e1e 100644
--- a/BGL/include/CGAL/boost/graph/IO/STL.h
+++ b/BGL/include/CGAL/boost/graph/IO/STL.h
@@ -73,7 +73,7 @@ public:
 
   \attention The graph `g` is not cleared, and the data from the stream are appended.
 
-  \attention When reading a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ifstream`.
+  \attention To read a binary file, the flag `std::ios::binary` must be set during the creation of the `ifstream`.
 
   \tparam Graph a model of `MutableFaceGraph`
   \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters"
@@ -208,7 +208,9 @@ bool read_STL(const std::string& fname, Graph& g) { return read_STL(fname, g, pa
 
   \brief writes the graph `g` in the output stream `os`, using the \ref IOStreamSTL.
 
-  \attention When writing a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ofstream`.
+  \attention To write to a binary file, the flag `std::ios::binary` must be set during the creation
+             of the `ofstream`, and the \link PkgStreamSupportEnumRef `IO::Mode` \endlink of the stream
+             must be set to `BINARY`.
 
   \tparam Graph a model of `FaceListGraph` and `HalfedgeListGraph`
   \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters"
diff --git a/Point_set_3/include/CGAL/Point_set_3/IO.h b/Point_set_3/include/CGAL/Point_set_3/IO.h
index ba6c41ceaa7..bc66d378822 100644
--- a/Point_set_3/include/CGAL/Point_set_3/IO.h
+++ b/Point_set_3/include/CGAL/Point_set_3/IO.h
@@ -53,7 +53,7 @@ class Point_set_3;
   normal vectors, the normal map is added to the point set. For PLY
   input, all point properties found in the header are added.
 
-  \attention When reading a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ifstream`.
+  \attention To read a binary file, the flag `std::ios::binary` must be set during the creation of the `ifstream`.
 
   \param is input stream
   \param ps point set
@@ -167,7 +167,9 @@ bool read_point_set(const std::string& fname, CGAL::Point_set_3<Point, Vector>&
 
   All properties are inserted in their instantiation order.
 
-  \attention When writing a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ofstream`.
+  \attention To write to a binary file, the flag `std::ios::binary` must be set during the creation
+             of the `ofstream`, and the \link PkgStreamSupportEnumRef `IO::Mode` \endlink
+             of the stream must be set to `BINARY`.
 
   \param os the output stream
   \param ps the point set
diff --git a/Point_set_3/include/CGAL/Point_set_3/IO/LAS.h b/Point_set_3/include/CGAL/Point_set_3/IO/LAS.h
index b68091e5fbb..7ecf30255ba 100644
--- a/Point_set_3/include/CGAL/Point_set_3/IO/LAS.h
+++ b/Point_set_3/include/CGAL/Point_set_3/IO/LAS.h
@@ -54,7 +54,7 @@ void check_if_property_is_used(PointSet& point_set,
 
   \brief reads the content of an intput stream in the \ref IOStreamLAS into a point set.
 
-  \attention When reading a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ifstream`.
+  \attention To read a binary file, the flag `std::ios::binary` must be set during the creation of the `ifstream`.
 
   \param is the input stream
   \param point_set the point set
@@ -194,7 +194,7 @@ namespace IO {
 
   \brief writes the content of a point set into an output stream in the \ref IOStreamLAS.
 
-  \attention When writing a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ofstream`.
+  \attention To write to a binary file, the flag `std::ios::binary` must be set during the creation of the `ofstream`.
 
   \tparam Point the point type of the `Point_set_3`
   \tparam Vector the vector type of the `Point_set_3`
diff --git a/Point_set_3/include/CGAL/Point_set_3/IO/PLY.h b/Point_set_3/include/CGAL/Point_set_3/IO/PLY.h
index fafccda8376..7c07a11f7e0 100644
--- a/Point_set_3/include/CGAL/Point_set_3/IO/PLY.h
+++ b/Point_set_3/include/CGAL/Point_set_3/IO/PLY.h
@@ -234,7 +234,7 @@ public:
   header. Each line starting by "comment " in the header is
   appended to the `comments` string (without the "comment " word).
 
-  \attention When reading a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ifstream`.
+  \attention To read a binary file, the flag `std::ios::binary` must be set during the creation of the `ifstream`.
 
   \param is the input stream
   \param point_set the point set
@@ -443,7 +443,9 @@ namespace IO {
   the header of the PLY stream (each line will be precedeed by
   "comment ").
 
-  \attention When writing a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ofstream`.
+  \attention To write to a binary file, the flag `std::ios::binary` must be set during the creation
+             of the `ofstream`, and the \link PkgStreamSupportEnumRef `IO::Mode` \endlink
+             of the stream must be set to `BINARY`.
 
   \tparam Point the point type of the `Point_set_3`
   \tparam Vector the vector type of the `Point_set_3`
diff --git a/Point_set_processing_3/include/CGAL/IO/read_las_points.h b/Point_set_processing_3/include/CGAL/IO/read_las_points.h
index 5e9e127d0f8..45c9a02e1d3 100644
--- a/Point_set_processing_3/include/CGAL/IO/read_las_points.h
+++ b/Point_set_processing_3/include/CGAL/IO/read_las_points.h
@@ -365,7 +365,7 @@ void process_properties (const LASpoint& reader, OutputValueType& new_element,
    - `LAS_property::B` with type `unsigned short`
    - `LAS_property::I` with type `unsigned short`
 
-   \attention When reading a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ifstream`.
+   \attention To read a binary file, the flag `std::ios::binary` must be set during the creation of the `ifstream`.
 
    \tparam OutputIteratorValueType type of objects that can be put in `PointOutputIterator`.
    It must be a model of `DefaultConstructible` and defaults to `value_type_traits<PointOutputIterator>::%type`.
@@ -430,7 +430,7 @@ bool read_LAS_with_properties(std::istream& is,
 
    Potential additional properties are ignored.
 
-   \attention When reading a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ifstream`.
+   \attention To read a binary file, the flag `std::ios::binary` must be set during the creation of the `ifstream`.
 
    \tparam OutputIteratorValueType type of objects that can be put in `PointOutputIterator`.
    It must be a model of `DefaultConstructible` and defaults to `value_type_traits<PointOutputIterator>::%type`.
diff --git a/Point_set_processing_3/include/CGAL/IO/read_ply_points.h b/Point_set_processing_3/include/CGAL/IO/read_ply_points.h
index 53fad444a93..fe20113c7f3 100644
--- a/Point_set_processing_3/include/CGAL/IO/read_ply_points.h
+++ b/Point_set_processing_3/include/CGAL/IO/read_ply_points.h
@@ -124,7 +124,7 @@ make_ply_normal_reader(VectorMap normal_map);
   second element of the tuple should be a functor that constructs
   the value type of `PropertyMap` from N objects of types `T`.
 
-  \attention When reading a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ifstream`.
+  \attention To read a binary file, the flag `std::ios::binary` must be set during the creation of the `ifstream`.
 
   \tparam OutputIteratorValueType type of objects that can be put in `PointOutputIterator`.
   It must be a model of `DefaultConstructible` and defaults to `value_type_traits<PointOutputIterator>::%type`.
@@ -207,7 +207,7 @@ bool read_PLY_with_properties(std::istream& is,
 
    Potential additional point properties and faces are ignored.
 
-   \attention When reading a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ifstream`.
+  \attention To read a binary file, the flag `std::ios::binary` must be set during the creation of the `ifstream`.
 
    \tparam OutputIteratorValueType type of objects that can be put in `PointOutputIterator`.
    It must be a model of `DefaultConstructible` and defaults to `value_type_traits<PointOutputIterator>::%type`.
diff --git a/Point_set_processing_3/include/CGAL/IO/write_las_points.h b/Point_set_processing_3/include/CGAL/IO/write_las_points.h
index 14679ca570a..62b38730c87 100644
--- a/Point_set_processing_3/include/CGAL/IO/write_las_points.h
+++ b/Point_set_processing_3/include/CGAL/IO/write_las_points.h
@@ -176,7 +176,7 @@ namespace LAS {
    See documentation of `read_LAS_with_properties()` for the
    list of available `LAS_property::Tag` classes.
 
-   \attention When writing a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ofstream`.
+   \attention To write to a binary file, the flag `std::ios::binary` must be set during the creation of the `ofstream`.
 
    \tparam PointRange is a model of `ConstRange`. The value type of
    its iterator is the key type of the named parameter `point_map`.
@@ -254,7 +254,7 @@ bool write_LAS_with_properties(std::ostream& os, ///< output stream.
 
    \brief writes the range of `points` (positions only), using the \ref IOStreamLAS.
 
-   \attention When writing a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ofstream`.
+  \attention To write to a binary file, the flag `std::ios::binary` must be set during the creation of the `ofstream`.
 
    \tparam PointRange is a model of `ConstRange`. The value type of
    its iterator is the key type of the named parameter `point_map`.
diff --git a/Point_set_processing_3/include/CGAL/IO/write_ply_points.h b/Point_set_processing_3/include/CGAL/IO/write_ply_points.h
index 33c1b8da3b5..84c5bef12d3 100644
--- a/Point_set_processing_3/include/CGAL/IO/write_ply_points.h
+++ b/Point_set_processing_3/include/CGAL/IO/write_ply_points.h
@@ -96,7 +96,9 @@ namespace IO {
    be provided for `PropertyMap::value_type` that handles both ASCII
    and binary output (see `CGAL::IO::get_mode()`).
 
-   \attention When writing to a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ofstream`.
+   \attention To write to a binary file, the flag `std::ios::binary` must be set during the creation
+              of the `ofstream`, and the \link PkgStreamSupportEnumRef `IO::Mode` \endlink
+              of the stream must be set to `BINARY`.
 
    \tparam PointRange is a model of `ConstRange`. The value type of
    its iterator is the key type of the `PropertyMap` objects provided
@@ -145,7 +147,9 @@ template <typename PointRange,
 
    \brief writes the range of `points` (positions + normals, if available) using \ref IOStreamPLY.
 
-   \attention When writing a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ofstream`.
+   \attention To write to a binary file, the flag `std::ios::binary` must be set during the creation
+              of the `ofstream`, and the \link PkgStreamSupportEnumRef `IO::Mode` \endlink
+              of the stream must be set to `BINARY`.
 
    \tparam PointRange is a model of `ConstRange`. The value type of
    its iterator is the key type of the named parameter `point_map`.
diff --git a/Stream_support/doc/Stream_support/IOstream.txt b/Stream_support/doc/Stream_support/IOstream.txt
index 7456fcb56ff..64d9b53dd7d 100644
--- a/Stream_support/doc/Stream_support/IOstream.txt
+++ b/Stream_support/doc/Stream_support/IOstream.txt
@@ -176,7 +176,8 @@ int main()
 
 \subsubsection IOstreamUsingOutputFormatting Using Output Formatting
 
-To ensure that non-\cgal types are formatted correctly (i.e., respecting `IO::Mode`), `oformat()` can be used.
+To ensure that non-\cgal types are formatted correctly (i.e., respecting \link PkgStreamSupportEnumRef `IO::Mode` \endlink),
+`oformat()` can be used.
 For types with a `Output_rep` specialization, the respective output routine of `Output_rep`
 will be called by `oformat()`. Otherwise, the stream output operator will be called.
 
@@ -197,7 +198,8 @@ refer to the documentation of the respective type.
 In some situations, you want to control the output formatting for a
 type `T`. For external types (third party libraries etc.),
 there might be problems if their stream output operator does not
-respect `IO::Mode`. The purpose of `Output_rep` is to provide a way to
+respect \link PkgStreamSupportEnumRef `IO::Mode` \endlink.
+The purpose of `Output_rep` is to provide a way to
 control output formatting that works independently of the object's
 stream output operator.
 
diff --git a/Stream_support/doc/Stream_support/PackageDescription.txt b/Stream_support/doc/Stream_support/PackageDescription.txt
index cb40fcd8607..cfd500f102c 100644
--- a/Stream_support/doc/Stream_support/PackageDescription.txt
+++ b/Stream_support/doc/Stream_support/PackageDescription.txt
@@ -58,7 +58,7 @@
 All classes in the \cgal kernel provide input and output operators for
 I/O streams.
 \cgal provides three different printing mode, defined in the enum
-`IO::Mode`, as well as different functions to set and get
+\link PkgStreamSupportEnumRef `IO::Mode` \endlink, as well as different functions to set and get
 the printing mode.
 
 \cgalClassifedRefPages
diff --git a/Stream_support/include/CGAL/IO/PLY.h b/Stream_support/include/CGAL/IO/PLY.h
index 6c38859388d..2e70adb9a1b 100644
--- a/Stream_support/include/CGAL/IO/PLY.h
+++ b/Stream_support/include/CGAL/IO/PLY.h
@@ -276,7 +276,7 @@ bool read_PLY(std::istream& is,
  *
  * \attention The polygon soup is not cleared, and the data from the stream are appended.
  *
- * \attention When reading a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ifstream`.
+ * \attention To read a binary file, the flag `std::ios::binary` must be set during the creation of the `ifstream`.
  *
  * \tparam PointRange a model of the concepts `RandomAccessContainer` and `BackInsertionSequence`
  *                    whose value type is the point type
@@ -426,7 +426,9 @@ bool read_PLY(const std::string& fname, PointRange& points, PolygonRange& polygo
  *
  * \brief writes the content of `points` and `polygons` in `out`, using the \ref IOStreamPLY.
  *
- * \attention When writing a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ofstream`.
+ * \attention To write to a binary file, the flag `std::ios::binary` must be set during the creation
+ *            of the `ofstream`, and the \link PkgStreamSupportEnumRef `IO::Mode` \endlink
+ *            of the stream must be set to `BINARY`.
  *
  * \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type
  * \tparam PolygonRange a model of the concept `SequenceContainer`
diff --git a/Stream_support/include/CGAL/IO/STL.h b/Stream_support/include/CGAL/IO/STL.h
index 52507655d33..ffb6da813dc 100644
--- a/Stream_support/include/CGAL/IO/STL.h
+++ b/Stream_support/include/CGAL/IO/STL.h
@@ -49,7 +49,7 @@ namespace IO {
  *
  * \attention The polygon soup is not cleared, and the data from the stream are appended.
  *
- * \attention When reading a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ifstream`.
+ * \attention To read a binary file, the flag `std::ios::binary` must be set during the creation of the `ifstream`.
  *
  * \tparam PointRange a model of the concepts `RandomAccessContainer` and `BackInsertionSequence`
  *                    whose value type is the point type
@@ -269,7 +269,9 @@ bool read_STL(const std::string& fname, PointRange& points, TriangleRange& facet
  *
  * \brief writes the content of `points` and `facets` in `os`, using the \ref IOStreamSTL.
  *
- * \attention When writing a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ofstream`.
+ * \attention To write to a binary file, the flag `std::ios::binary` must be set during the creation
+ *            of the `ofstream`, and the \link PkgStreamSupportEnumRef `IO::Mode` \endlink
+ *            of the stream must be set to `BINARY`.
  *
  * \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type.
  * \tparam TriangleRange a model of the concept `SequenceContainer`
diff --git a/Surface_mesh/include/CGAL/Surface_mesh/IO/PLY.h b/Surface_mesh/include/CGAL/Surface_mesh/IO/PLY.h
index dd2fbf0a781..ce6deef92ff 100644
--- a/Surface_mesh/include/CGAL/Surface_mesh/IO/PLY.h
+++ b/Surface_mesh/include/CGAL/Surface_mesh/IO/PLY.h
@@ -717,7 +717,7 @@ void fill_header(std::ostream& os, const Surface_mesh<Point>& sm,
 
 /// \ingroup PkgSurfaceMeshIOFuncPLY
 ///
-/// \attention When reading a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ifstream`.
+/// \attention To read a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ifstream`.
 ///
 /// \brief extracts the surface mesh from an input stream in the \ref IOStreamPLY
 ///        and appends it to the surface mesh `sm`.
@@ -890,7 +890,9 @@ namespace IO {
 /// simple types are inserted in the stream. The halfedges follow
 /// the same behavior.
 ///
-/// \attention When writing a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ofstream`.
+///  \attention To write to a binary file, the flag `std::ios::binary` must be set during the creation
+///             of the `ofstream`, and the \link PkgStreamSupportEnumRef `IO::Mode` \endlink
+///             of the stream must be set to `BINARY`.
 ///
 /// \tparam Point The type of the \em point property of a vertex. There is no requirement on `P`,
 ///               besides being default constructible and assignable.