From bb9ebdff5a3b2445e9e854be3b54ce5c763b5c48 Mon Sep 17 00:00:00 2001 From: Andreas Fabri Date: Mon, 12 May 2025 11:14:13 +0100 Subject: [PATCH 1/5] Developer Manual: trivial fixes --- .../Developer_manual/Chapter_code_format.txt | 20 +++++++++---------- .../Chapter_iterators_and_circulators.txt | 20 ------------------- .../Chapter_traits_classes.txt | 2 +- 3 files changed, 11 insertions(+), 31 deletions(-) diff --git a/Documentation/doc/Documentation/Developer_manual/Chapter_code_format.txt b/Documentation/doc/Documentation/Developer_manual/Chapter_code_format.txt index 9a8b72e765c..d8aa2337d9f 100644 --- a/Documentation/doc/Documentation/Developer_manual/Chapter_code_format.txt +++ b/Documentation/doc/Documentation/Developer_manual/Chapter_code_format.txt @@ -49,10 +49,10 @@ there are convincing reasons.
  • The first word of a class or enumeration name should be capitalized (e.g., `Quotient`, `Orientation`).
  • Function names are in lowercase - (e.g., `is_zero`). + (e.g., `is_zero()`).
  • Boolean function names should begin with a verb. For example, use - `is_empty` instead of simply `empty` and - `has_on_bounded_side` instead of `on_bounded_side`. + `is_empty()` instead of simply `empty()` and + `has_on_bounded_side()` instead of `on_bounded_side()`.
  • Names of macros should begin with the prefix `CGAL_`. @@ -72,23 +72,23 @@ there are convincing reasons. \subsection Developer_manualKerneltraits Kernel traits @@ -183,7 +183,7 @@ In addition, for each functor the kernel traits class has a member function that returns an instance of this functor. The name of this function should be the (uncapitalized) name of the functor followed by the suffix `_object`.For example, the function that returns an instance of the -`Less_xy_2` functor is called `less_xy_2_object`. +`Less_xy_2` functor is called `less_xy_2_object()`. \subsection Developer_manualFilenames File names diff --git a/Documentation/doc/Documentation/Developer_manual/Chapter_iterators_and_circulators.txt b/Documentation/doc/Documentation/Developer_manual/Chapter_iterators_and_circulators.txt index bb7567c4858..794fe7c1378 100644 --- a/Documentation/doc/Documentation/Developer_manual/Chapter_iterators_and_circulators.txt +++ b/Documentation/doc/Documentation/Developer_manual/Chapter_iterators_and_circulators.txt @@ -150,28 +150,8 @@ and used to output values to the output stream to which it is bound. \cgal provides extensions of the classes `istream_iterator` and `ostream_iterator`. The class `CGAL::Ostream_iterator` is an output iterator adaptor for the stream class `Stream` and value - type `T`. It provides output iterators that can be used to output values of type `T` to objects of the class `Stream`. -For example, the following code fragment inserts a list of segments into -a window stream (i.e., it draws the segments in the window) using the -standard copy function: - -\code{.cpp} -typedef CGAL::Cartesian K; -typedef K::Segment_2 Segment; - -std::vector segments; -Window_stream W( 400, 400); - -int main (int argc, char** argv) -{ - // initialize segments - std::copy( segments.begin(), - segments.end(), - CGAL::Ostream_iterator< Segment, Window_stream>( W)); -} -\endcode Likewise, the class `CGAL::Istream_iterator` is an input iterator adaptor for the stream class `Stream` and value type `T`. diff --git a/Documentation/doc/Documentation/Developer_manual/Chapter_traits_classes.txt b/Documentation/doc/Documentation/Developer_manual/Chapter_traits_classes.txt index 92b7f4569bc..b685b648a9d 100644 --- a/Documentation/doc/Documentation/Developer_manual/Chapter_traits_classes.txt +++ b/Documentation/doc/Documentation/Developer_manual/Chapter_traits_classes.txt @@ -19,7 +19,7 @@ sections. \section secwhat_is_a_traits_class What are traits classes in CGAL? -The algorithms in CGAL's basic library are implemented as function templates +The algorithms in \cgal's basic library are implemented as function templates or class templates, usually having a template parameter whose name contains the word `Traits`. This template parameter represents a concept and so has a corresponding set of requirements that From 914b86b6b5ca9cc5d91e8b594668e310a2d0f3bb Mon Sep 17 00:00:00 2001 From: Andreas Fabri Date: Mon, 12 May 2025 11:44:55 +0100 Subject: [PATCH 2/5] More trivial changes --- .../Developer_manual/Chapter_code_format.txt | 2 +- .../Developer_manual/Chapter_handles.txt | 16 +++++++------- .../Developer_manual/Chapter_namespaces.txt | 21 ++++++------------- .../Developer_manual/Chapter_objects.txt | 4 ++-- 4 files changed, 17 insertions(+), 26 deletions(-) diff --git a/Documentation/doc/Documentation/Developer_manual/Chapter_code_format.txt b/Documentation/doc/Documentation/Developer_manual/Chapter_code_format.txt index d8aa2337d9f..ded4f9d7900 100644 --- a/Documentation/doc/Documentation/Developer_manual/Chapter_code_format.txt +++ b/Documentation/doc/Documentation/Developer_manual/Chapter_code_format.txt @@ -30,7 +30,7 @@ there are convincing reasons.
  • Words in the names of concepts (e.g., template parameters) should be separated using capital letters. The only use of underscores in concept names is before the dimension suffix. For example, one - should use a name such as ConvexHullTraits_2 for the concept + should use a name such as `ConvexHullTraits_2` for the concept in contrast to `Convex_hull_traits_2` for the name of the class that is a model of this concept. This different naming scheme for concepts and classes was adopted mainly for two reasons (a) it is consistent with diff --git a/Documentation/doc/Documentation/Developer_manual/Chapter_handles.txt b/Documentation/doc/Documentation/Developer_manual/Chapter_handles.txt index 9caa0f25203..ed970f18148 100644 --- a/Documentation/doc/Documentation/Developer_manual/Chapter_handles.txt +++ b/Documentation/doc/Documentation/Developer_manual/Chapter_handles.txt @@ -7,8 +7,8 @@ \section Developer_manualReferencecounting Reference counting As of release 2.1, a reference counting scheme is used for -the kernel objects in the kernels `Cartesian` and -`Homogeneous`. +the kernel objects in the kernels `CGAL::Cartesian` and +`CGAL::Homogeneous`. All copies of an object share a common representation object storing the data associated with a kernel object; see \cgalFigureRef{figrefcounted}. @@ -19,7 +19,7 @@ of the data that we would have to copy without sharing representations. The drawback is an indirection in accessing the data. Such an indirection is bad in terms of cache efficiency. Thus there are also non-reference-counting kernels available -`Simple_cartesian` and `Simple_homogeneous`. +`CGAL::Simple_cartesian` and `CGAL::Simple_homogeneous`. \cgalFigureBegin{figrefcounted,reference_counting.png} Objects using reference counting (bottom) share common representation; copying creates a new handle (drawn at the right) pointing to the same representation as the object copied. Without reference counting (top) all data are copied to the new object (drawn at the right); @@ -161,13 +161,13 @@ following member functions to manage its internal reference counting: See the UML class diagram in \cgalFigureRef{figHandleFor}. @@ -257,7 +257,7 @@ You get this functionality by including `CGAL/Handle_for.h` \section Developer_manualAllocation Allocation -Class `Handle_for` has two template parameters. Besides the +Class `CGAL::Handle_for` has two template parameters. Besides the type of the stored object, there is also a parameter specifying an allocator. Any concrete argument must be a model for the `Allocator` concept diff --git a/Documentation/doc/Documentation/Developer_manual/Chapter_namespaces.txt b/Documentation/doc/Documentation/Developer_manual/Chapter_namespaces.txt index f2241888167..2564834e1ed 100644 --- a/Documentation/doc/Documentation/Developer_manual/Chapter_namespaces.txt +++ b/Documentation/doc/Documentation/Developer_manual/Chapter_namespaces.txt @@ -7,17 +7,9 @@ Names, in particular (member) function names and class names should be descriptive and easily remembered. So it is not surprising that different libraries or packages choose the same name for corresponding -or similar classes and functions. A common approach to solving the -naming problem is to add a prefix, for example, -OpenGL adds `gl` -and FLTK adds `fl`. \leda uses prefix `leda_` - -to some extent, -but you have to tell \leda not to make the corresponding unprefixed names -available as well.\cgalFootnote{\cgal's makefile does this by setting \cgalFootnoteCode{-DLEDA_PREFIX}.} Initially, \cgal used -prefix `CGAL_`. -At the beginning of 1999, it was decided to drop prefix `CGAL_` and to -introduce namespace `CGAL`. +or similar classes and functions. A common approach to avoid ambiguities +is to add a prefix, for example, OpenGL adds `gl` and FLTK adds `fl`, +but the better alternative is the usage of `namespace`. \section Developer_manualNamespaceCGAL Namespace CGAL @@ -34,10 +26,9 @@ my_new_function( My_new_cgal_class& ); } // namespace CGAL \endcode -Make sure not to have include statements nested between - namespace CGAL { and } // namespace CGAL. -Otherwise all names defined in the file included will be -added to namespace `CGAL`. +Make sure not to have include statements inside the +`namespace CGAL`. Otherwise, all names defined in the file included will be +added to the namespace. \section Developer_manualNamespaceinternal Namespace internal diff --git a/Documentation/doc/Documentation/Developer_manual/Chapter_objects.txt b/Documentation/doc/Documentation/Developer_manual/Chapter_objects.txt index 2dd3ab4ff72..28ea4da096c 100644 --- a/Documentation/doc/Documentation/Developer_manual/Chapter_objects.txt +++ b/Documentation/doc/Documentation/Developer_manual/Chapter_objects.txt @@ -16,7 +16,7 @@ appropriate base class interface functions (besides `draw()`). \cgal has chosen a different approach, since \cgal wants to avoid large class hierarchies. With the \cgal -class `Object`, you can fake a common +class `CGAL::Object`, you can fake a common base class, see \cgalFigureRef{FigObject}. \cgalFigureBegin{FigObject,Object.png } @@ -24,7 +24,7 @@ UML class diagram for faked object hierarchies (since 2.2-I-4). \cgalFigureEnd Functions having a polymorphic return type create an object of the actual -result type and wrap it into an object of type `Object`. +result type and wrap it into an object of type `CGAL::Object`. Refer to the documentation of `CGAL::Object` class for more details. An alternative is to use a class handling several output iterators at the same time such as the classes `CGAL::Dispatch_output_iterator`. From eaedf7661bd2b90cdeeeaa0b54456291a779b1c8 Mon Sep 17 00:00:00 2001 From: Andreas Fabri Date: Mon, 12 May 2025 11:52:26 +0100 Subject: [PATCH 3/5] Fix in Tutorial --- Documentation/doc/Documentation/Tutorials/Tutorials.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/doc/Documentation/Tutorials/Tutorials.txt b/Documentation/doc/Documentation/Tutorials/Tutorials.txt index bc903ed2905..69690255d6b 100644 --- a/Documentation/doc/Documentation/Tutorials/Tutorials.txt +++ b/Documentation/doc/Documentation/Tutorials/Tutorials.txt @@ -5,7 +5,7 @@ \cgal provides a large number of data structures and algorithms dedicated to various applications. Most of these data structures and algorithms can be combined to achieve extensive and complex geometric tasks. The tutorials aim at -providing help and ideas on how to use CGAL beyond the simple examples of the +providing help and ideas on how to use \cgal beyond the simple examples of the User Manual. \section tuto_list List of Available Tutorials From 56f3e7a278db776f25854ae3b79410f676170fe3 Mon Sep 17 00:00:00 2001 From: Andreas Fabri Date: Mon, 12 May 2025 13:07:38 +0100 Subject: [PATCH 4/5] For testing refer to the wiki on github --- .../Developer_manual/Chapter_testing.txt | 22 +------------------ 1 file changed, 1 insertion(+), 21 deletions(-) diff --git a/Documentation/doc/Documentation/Developer_manual/Chapter_testing.txt b/Documentation/doc/Documentation/Developer_manual/Chapter_testing.txt index fc075c63253..92c352ab334 100644 --- a/Documentation/doc/Documentation/Developer_manual/Chapter_testing.txt +++ b/Documentation/doc/Documentation/Developer_manual/Chapter_testing.txt @@ -9,26 +9,6 @@ Before submitting a change for integration into \cgal it is good style to run the testsuite of the modified package and all packages that could be impacted. -All examples and tests in CGAL are now compatible with `ctest`. So to test all examples or all tests -of a package, you simply need to configure with `cmake` the examples/tests of the package you want to -test, adding the option `CGAL_ENABLE_TESTING` and setting its value to `ON`. In order to report more -warnings, it is recommended to also add the option `CGAL_DEV_MODE` and to set it to `ON`. -Then a call to the command `ctest` will compile and run the tests/examples. - - -\section fullTestsuite Running the Whole Testsuite -We describe here how to proceed to the testing of a full copy of `master` or any branch by creating a flat release -(that is having a layout similar to a release rather than a branch layout with header files gathered by packages). - -The creation of the flat release is done using the `cmake` script `cgal_create_release_with_cmake.cmake` located in the directory `Scripts/developer_scripts`. -You can run it using the option `-P` of `cmake`: `cmake -P cgal_create_release_with_cmake.cmake`. -For an up-to-date documentation of available options, check the comments at the beginning of the script. - -Then for testing all examples, tests, and demos, in a build directory call `cmake` on the created release -(the path is given by the script if not manually specified) - -`cmake -DBUILD_TESTING=ON -DWITH_examples=ON -DWITH_tests=ON -DWITH_demos=ON ../CGAL-X.XX/` - -Finally, a call to the command `ctest` will compile and run the tests, examples, and demos. +For details see Testing on the CGAL wiki on github. */ From 206be8d951d7e356736ed552b6190c5b9105404b Mon Sep 17 00:00:00 2001 From: Andreas Fabri Date: Mon, 12 May 2025 13:41:42 +0100 Subject: [PATCH 5/5] more small fixes --- .../doc/Documentation/Developer_manual/Chapter_portability.txt | 2 +- .../doc/Documentation/Developer_manual/Chapter_robustness.txt | 2 +- Documentation/doc/Documentation/deprecated.txt | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/doc/Documentation/Developer_manual/Chapter_portability.txt b/Documentation/doc/Documentation/Developer_manual/Chapter_portability.txt index 9be392c25ce..f5e598bc84f 100644 --- a/Documentation/doc/Documentation/Developer_manual/Chapter_portability.txt +++ b/Documentation/doc/Documentation/Developer_manual/Chapter_portability.txt @@ -65,7 +65,7 @@ probably must be deprecated and phased out), trying not to break backward compatibility too much. A list of reasonable Boost libraries to use in the \cgal API is -Graph, Optional, Parameter (for packages already using it), +Graph, Parameter (for packages already using it), Property Map, Smart Pointers (for packages already using it), Variant. diff --git a/Documentation/doc/Documentation/Developer_manual/Chapter_robustness.txt b/Documentation/doc/Documentation/Developer_manual/Chapter_robustness.txt index a581e570192..3c2206492b7 100644 --- a/Documentation/doc/Documentation/Developer_manual/Chapter_robustness.txt +++ b/Documentation/doc/Documentation/Developer_manual/Chapter_robustness.txt @@ -60,7 +60,7 @@ that (are still fairly generic and) guarantee exact predicate results and much higher efficiency than exact number types like arbitrary precision integers or rationals. The efficiency relies on the use of speedy floating-point arithmetic in order to filter out reliable floating-point -computations. Interval arithmetic is largely used in such filter steps. +computations. %Interval arithmetic is largely used in such filter steps. \section Developer_manualRequirementsandrecommendations Requirements and recommendations diff --git a/Documentation/doc/Documentation/deprecated.txt b/Documentation/doc/Documentation/deprecated.txt index 74c64425716..0135887b891 100644 --- a/Documentation/doc/Documentation/deprecated.txt +++ b/Documentation/doc/Documentation/deprecated.txt @@ -2,7 +2,7 @@ \page deprecated Deprecation Notice -In \cgal, we are trying as much as possible not to break the backward compatibility. If we have to do it, it will be announced in the release notes , +In \cgal, we are trying as much as possible not to break the backward compatibility. If we have to do it, it will be announced in the release notes, and a solution will always be provided. When possible, we keep the deprecated API for two releases before removing it. If you reached this page after clicking on a link, it must probably mean that the documentation page you were trying to reach is now deprecated. Have a look at the release notes for more information.