Misc CGAL IO doc fixes

Mesh_3/doc/Mesh_3/Mesh_3.txt

@@ -548,11 +548,11 @@ See the <a href="https://www.threadingbuildingblocks.org/documentation">TBB docu
 for more details.
 
 \section Mesh_3_section_io Input/Output
-Several formats are supported for writing a mesh:
- - VTU, with `CGAL::output_to_vtu()`
- - Avizo, with `CGAL::output_to_avizo()`
- - Medit, with `CGAL::output_to_medit()`
- - Tetgen, with `CGAL::output_to_tetgen()`
+Several file formats are supported for writing a mesh:
+ - \ref IOStreamVTK, using `CGAL::output_to_vtu()`
+ - \ref IOStreamAvizo, using `CGAL::output_to_avizo()`
+ - \ref IOStreamMedit, using `CGAL::output_to_medit()`
+ - \ref IOStreamTetgen, using `CGAL::output_to_tetgen()`
 
 \section Mesh_3_section_examples Examples
 

Point_set_processing_3/doc/Point_set_processing_3/Point_set_processing_3.txt

@@ -158,23 +158,9 @@ per line)
 - \link IOStreamLAS LAS (Lidar Format) \endlink -- \cgalCite{cgal:asprs-lasf-13} This format does
 not handle normals and requires the \ref thirdpartyLASlib library.
 
-The following functions are available:
-
-- `read_points()`
-- `read_XYZ()`
-- `read_OFF()`
-- `read_PLY()`
-- `read_LAS()`
-- `write_points()`
-- `write_XYZ()`
-- `write_OFF()`
-- `write_PLY()`
-- `write_LAS()`
-
-All of these functions (with the exception of the LAS format) can read
-and write either points alone or points with normals (depending on
+All of the functions in \ref PkgPointSetProcessing3IO (with the exception of the LAS format)
+can read and write either points alone or points with normals (depending on
 whether the `normal_map` named parameter is used by the user or not).
-
 Note that the %PLY format handles both ASCII and binary formats. In
 addition, %PLY and %LAS are extensible formats that can embed additional
 properties. These can also be read by \cgal (see Section \ref

Point_set_processing_3/include/CGAL/IO/read_las_points.h

@@ -370,6 +370,7 @@ void process_properties (const LASpoint& reader, OutputValueType& new_element,
    \returns `true` if reading was successful, `false` otherwise.
 
    \sa `make_las_point_reader()`
+
    \sa \ref IOStreamLAS
 */
 template <typename OutputIteratorValueType,
@@ -421,7 +422,7 @@ bool read_LAS_with_properties(std::istream& is,
 /**
    \ingroup PkgPointSetProcessing3IOLas
 
-   \brief reads points (position only) from a .las or .laz stream.
+   \brief reads points (position only) using the \ref IOStreamLAS.
 
    Potential additional properties are ignored.
 
@@ -450,7 +451,7 @@ bool read_LAS_with_properties(std::istream& is,
 
    \returns `true` if reading was successful, `false` otherwise.
 
-   \sa \ref IOStreamLAS
+   \sa `read_LAS_with_properties()`
 */
 template <typename OutputIteratorValueType,
           typename PointOutputIterator,
@@ -526,7 +527,8 @@ bool read_LAS(std::istream& is, OutputIterator output,
    \cgalNamedParamsEnd
 
    \returns `true` if reading was successful, `false` otherwise.
-   \sa \ref IOStreamLAS
+
+   \sa `read_LAS_with_properties()`
 */
 template <typename OutputIteratorValueType,
           typename PointOutputIterator,

Point_set_processing_3/include/CGAL/IO/read_ply_points.h

@@ -128,9 +128,9 @@ make_ply_normal_reader(VectorMap normal_map);
 
   \returns `true` if reading was successful, `false` otherwise.
 
+  \sa \ref IOStreamPLY
   \sa `make_ply_point_reader()`
   \sa `make_ply_normal_reader()`
-  \sa \ref IOStreamPLY
 */
 template <typename OutputIteratorValueType,
           typename PointOutputIterator,
@@ -233,6 +233,8 @@ bool read_PLY_with_properties(std::istream& is,
    \attention Be mindful of the flag `std::ios::binary` flag when creating the `ifstream` when reading a binary file
 
    \returns `true` if reading was successful, `false` otherwise.
+
+   \sa `read_PLY_with_properties()`
 */
 template <typename OutputIteratorValueType,
           typename PointOutputIterator,
@@ -313,6 +315,7 @@ bool read_PLY(std::istream& is,
    \returns `true` if reading was successful, `false` otherwise.
 
    \sa \ref IOStreamPLY
+   \sa `read_PLY_with_properties()`
 */
 template <typename OutputIteratorValueType,
           typename PointOutputIterator,

Point_set_processing_3/include/CGAL/IO/write_las_points.h

@@ -247,7 +247,7 @@ bool write_LAS_with_properties(std::ostream& os, ///< output stream.
 /**
    \ingroup PkgPointSetProcessing3IOLas
 
-   Saves the range of `points` (positions only) to a .las stream.
+   Saves the range of `points` (positions only) using the \ref IOStreamLAS.
 
    \tparam PointRange is a model of `ConstRange`. The value type of
    its iterator is the key type of the named parameter `point_map`.
@@ -280,6 +280,7 @@ bool write_LAS_with_properties(std::ostream& os, ///< output stream.
    \returns `true` if writing was successful, `false` otherwise.
 
    \sa \ref IOStreamLAS
+   \sa `write_LAS_with_properties()`
 */
 template <typename PointRange, typename CGAL_BGL_NP_TEMPLATE_PARAMETERS>
 bool write_LAS(std::ostream& os,
@@ -343,7 +344,7 @@ bool write_LAS(std::ostream& os,
 
    \returns `true` if writing was successful, `false` otherwise.
 
-   \sa \ref IOStreamLAS
+   \sa `write_LAS_with_properties()`
 */
 template <typename PointRange, typename CGAL_BGL_NP_TEMPLATE_PARAMETERS>
 bool write_LAS(const char* filename,

Point_set_processing_3/include/CGAL/IO/write_ply_points.h

@@ -78,7 +78,7 @@ namespace CGAL {
 /**
    \ingroup PkgPointSetProcessing3IOPly
 
-   \brief saves the range of `points` with properties to a .ply stream.
+   \brief saves the range of `points` with properties using \ref IOStreamPLY.
 
    %PLY is either ASCII or binary depending on the value of `CGAL::get_mode(os)`.
 
@@ -140,7 +140,7 @@ template <typename PointRange,
 /**
    \ingroup PkgPointSetProcessing3IOPly
 
-   \brief saves the range of `points` (positions + normals, if available) to a .ply stream.
+   \brief saves the range of `points` (positions + normals, if available) using \ref IOStreamPLY.
 
     %PLY is either ASCII or binary depending on the value of `CGAL::get_mode(os)`.
 
@@ -181,6 +181,8 @@ template <typename PointRange,
    \attention Be mindful of the flag `std::ios::binary` flag when creating the `ofstream` when writing a binary file
 
    \returns `true` if writing was successful, `false` otherwise.
+
+   \sa `write_PLY_with_properties()`
 */
 template <typename PointRange,
           typename CGAL_BGL_NP_TEMPLATE_PARAMETERS>
@@ -236,7 +238,7 @@ bool write_PLY(std::ostream& os, const PointRange& points,
 /**
    \ingroup PkgPointSetProcessing3IOPly
 
-   \brief saves the range of `points` (positions + normals, if available) to a .ply stream.
+   \brief saves the range of `points` (positions + normals, if available) using \ref IOStreamPLY.
 
    %PLY is either ASCII or binary depending on the value of `CGAL::get_mode(os)`.
 
@@ -282,7 +284,7 @@ bool write_PLY(std::ostream& os, const PointRange& points,
 
    \returns `true` if writing was successful, `false` otherwise.
 
-   \sa \ref IOStreamPLY
+   \sa `write_PLY_with_properties()`
 */
 template <typename PointRange, typename CGAL_BGL_NP_TEMPLATE_PARAMETERS>
 bool write_PLY(const char* filename,

Stream_support/doc/Stream_support/File_formats/Supported_file_formats.txt

@@ -291,7 +291,7 @@ We only support coordinates and normals.
 
 <table class="iotable">
   <tr>
-    <th colspan="4">LAS (Lidar) File Format</th>
+    <th colspan="4">XYZ File Format</th>
   </tr>
   <tr>
     <td rowspan="2" width="75">Input</td>
@@ -330,23 +330,23 @@ A precise specification of the format is available <a href="http://paulbourke.ne
     <td rowspan="2" width="75">Input</td>
     <td rowspan="1" width="175">Polygon Mesh</td>
     <td width="250">Any model of `MutableFaceGraph`</td>
-    <td width="500">\link PkgBGLIoFuncsOBJ CGAL::read_OBJ(const char*, Graph&)\endlink</td>
+    <td width="500">\link PkgBGLIoFuncsGOCAD CGAL::read_GOCAD(const char*, Graph&)\endlink</td>
   </tr>
   <tr>
     <td>Polygon Soup</td>
     <td>Any point + polygon range</td>
-    <td>\link PkgStreamSupportIoFuncsOBJ CGAL::read_OBJ(const char*, PointRange&, PolygonRange&)\endlink</td>
+    <td>\link PkgStreamSupportIoFuncsGOCAD CGAL::read_GOCAD(const char*, PointRange&, PolygonRange&)\endlink</td>
   </tr>
   <tr>
     <td rowspan="2">Output</td>
     <td rowspan="1">Polygon Mesh</td>
     <td>Any model of `FaceGraph`</td>
-    <td>\link PkgBGLIoFuncsOBJ CGAL::write_OBJ(const char*, Graph&)\endlink</td>
+    <td>\link PkgBGLIoFuncsGOCAD CGAL::write_GOCAD(const char*, Graph&)\endlink</td>
   </tr>
   <tr>
     <td>Polygon Soup</td>
     <td>Any point + polygon range</td>
-    <td>\link PkgStreamSupportIoFuncsOBJ CGAL::write_OBJ(const char*, PointRange&, PolygonRange&)\endlink</td>
+    <td>\link PkgStreamSupportIoFuncsGOCAD CGAL::write_GOCAD(const char*, PointRange&, PolygonRange&)\endlink</td>
   </tr>
 </table>
 

Stream_support/doc/Stream_support/IOstream.txt

@@ -269,8 +269,8 @@ is available on the page: \ref IOStreamSupportedFileFormats.
 Note that these categories will grow as the on-going effort to uniformize I/O in \cgal progresses.
 
 \subsection IOstreamPointSetIO Point Set IO
-A set of points is the basic input of many algorithms. The following table shows which file formats
-can be read from and written to for basic point ranges.
+A set of points - possibly with normals - is the basic input of many algorithms.
+The following table shows which file formats can be read from and written for point ranges.
 
 <table class="iotable">
     <tr>
@@ -299,6 +299,14 @@ can be read from and written to for basic point ranges.
     </tr>
 </table>
 
+All of these functions (with the exception of the LAS format) can read
+and write either points alone or points with normals (depending on
+whether the `normal_map` named parameter is used by the user or not).
+
+Note that the %PLY format handles both ASCII and binary formats. In
+addition, %PLY and %LAS are extensible formats that can embed additional
+properties. These can also be read by \cgal (see Section \ref
+Point_set_processing_3Properties_io).
 
 The class `CGAL::Point_set_3` is the data structure used in \cgal to represent point sets.
 It is a vector-based data structure that contains a default property (named <em>point</em>)
@@ -377,9 +385,10 @@ their indices per face (i.e a vector of 3 integers represent a triangle face).
 </table>
 
 \subsection IOstreamPolygonMeshIO Polygon Mesh IO
-A Polygon Mesh is a 3D structure that refines the concept of `FaceGraph`
-with some additional restrictions; a more precise definition can be found \ref PMPDef "here".
-The table above only lists the functions that work with any Polygon Mesh.
+A \a polygon \a mesh is a consistent and orientable surface mesh, that can have
+one or more boundaries. This refines the concept of `FaceGraph` with some additional restrictions;
+a complete definition can be found \ref PMPDef "here".
+The table above only lists the functions that work with any polygon mesh.
 
 <table class="iotable">
     <tr>
@@ -420,7 +429,7 @@ See the reference manual of each data structure for more information.
 
 The functions above require the input to represent a 2-manifold surface (possibly with boundaries).
 If this is not the case, the package \ref PkgPolygonMeshProcessing offers the function
-\link PMP_IO_grp `CGAL::Polgyon_mesh_processing::read_polygon_mesh()` \endlink
+\link PMP_IO_grp `CGAL::Polygon_mesh_processing::read_polygon_mesh()` \endlink
 which can perform some combinatorial repairing to ensure the input data is a 2-manifold.
 
 \subsection IOstreamWKT Simple 2D Geometry IO