songsenand
/
cgal
mirror of https://github.com/CGAL/cgal
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Doc improvements

This commit is contained in:
Mael Rouxel-Labbé 2019-10-29 11:00:39 +01:00
parent 23f516d6e3
commit ead5d7478c
10 changed files with 61 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
Documentation/doc/Documentation/Getting_started.txt
View File

@ -1,15 +1,27 @@
/*!
\page general_intro Getting Started with %CGAL
The following pages describe how to use \cgal on different environments
- \subpage usage
- \subpage windows
- \subpage thirdparty gives information (supported versions, download links) of the required and optional third party libraries.
The following pages cover advanced installation options
- \subpage configurationvariables gives information about which CMake variables can be used to help
resolve missing dependencies while using the cmake command line tool.
- \subpage installation describes the deprecated process of configuring and building \cgal.
The following pages cover the structure of the manual and general information about \cgal
- \subpage manual gives an idea of where you should look for documentation.
- \subpage preliminaries lists how to control inlining, thread safety, code deprecation, checking of pre- and postconditions, and how to alter the failure behavior.
- \subpage preliminaries lists how to control inlining, thread safety, code deprecation, checking
of pre- and postconditions, and how to alter the failure behavior.
Once you are familiar with building your programs with \cgal and how the documentation is structured,
you can head over to the \ref tutorials for a gentle introduction to \cgal, or directly to the package(s)

4
Documentation/doc/Documentation/Third_party.txt
View File

@ -18,6 +18,8 @@ supporting <a href="https://isocpp.org/wiki/faq/cpp14">C++14</a> or later.
| MacOS X | \sc{Gnu} `g++` 6.3 or later\cgalFootnote{<A HREF="http://gcc.gnu.org/">`http://gcc.gnu.org/`</A>} |
| | Apple `Clang` compiler versions 7.0.2 and 10.0.1 |
<!-- Windows supported version are also listed on windows.html (must change both) -->
Older versions of the above listed compilers might work, but no guarantee is provided.
\section seccmake CMake
@ -54,7 +56,7 @@ or <A HREF="https://msdn.microsoft.com/en-us/library/1fe2x6kt(v=vs.140).aspx">`h
The \stl comes with the compiler, and as such no installation is required.
\subsection thirdpartyBoost Boost
<b>Version 1.48 or later</b>
<b>Version 1.57 or later</b>
The \sc{Boost} libraries are a set of portable C++ source libraries.
Most of \sc{Boost} libraries are header-only, but a few of them need to be compiled or

2
Documentation/doc/Documentation/Tutorials/Tutorial_hello_world.txt
View File

@ -266,7 +266,7 @@ given by a direction, which is hardwired in the class
\section intro_concept Concepts and Models
In the previous section, we wrote that "Any model of the CGAL concept
Kernel provides what is required by the concept ConvexHullTraits_2".
Kernel provides what is required by the concept `ConvexHullTraits_2`.
A \em concept is a set of requirements on a type, namely that it has
certain nested types, certain member functions, or comes with certain

9
Documentation/doc/Documentation/Tutorials/Tutorials.txt
View File

@ -8,9 +8,7 @@ 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
User Manual.
\section tuto_list List of available tutorials
\section tuto_list List of Available Tutorials
- \subpage tutorial_hello_world presents you some short example
programs to get a first idea for the look and feel of a program that
@ -19,4 +17,9 @@ User Manual.
define what primitives are used by a geometric algorithm, the
notions of \em concept and \em model.
\section tuto_examples Package Examples
Each \cgal package comes with a set of commented examples that illustrate basic features of the package.
See for example Section \ref Triangulation3secexamples of the User Manual of the package \ref PkgTriangulation3.
*/

13
Documentation/doc/Documentation/Usage.txt
View File

@ -1,5 +1,5 @@
/*!
\page usage Using %CGAL on Linux and macOS
\page usage Using %CGAL on Unix (Linux, macOS, ...)
\cgalAutoToc
Since \cgal version 5.0, \cgal is header-only be default, which means
@ -9,7 +9,8 @@ However, some dependencies of \cgal might still need to be installed.
\section usage_introduction Quick Start: Compiling a Program using CGAL
Assuming that you have obtained \cgal through one of the package managers offering \cgal on your platform
(see Section \ref secgettingcgal), you can download \cgal examples <a href="TODO">here</a>
(see Section \ref secgettingcgal), you can download \cgal examples
<a href="https://github.com/CGAL/cgal/releases/CGAL-\cgalReleaseNumber/CGAL-\cgalReleaseNumber-examples.tar.xz">CGAL-\cgalReleaseNumber-examples.tar.xz</a>
and the compilation of an example is as simple as:
cd $HOME/CGAL-\cgalReleaseNumber/examples/Triangulation_2 # go to an example directory
@ -112,6 +113,14 @@ or downloaded separately at
there is no need to even configure it before using it. Programs using \cgal (examples, tests, demos, etc.)
are instead configured using CMake and \cgal will be configured at the same time.
There is one exception to the paragraph before: if you want to install \cgal header files to
a standard location (such as `/usr/local/include`):
cmake .
make install
For more advanced usage, we refer to Section \ref installation_configwithcmake.
Note that even though \cgal is a header-only library, not all its dependencies
are header-only. The libraries \sc{Gmp} and \sc{Mpfr}, for example, are not
header-only. As such, these dependencies must be built or installed independently.

5
Documentation/doc/Documentation/advanced/Configuration_variables.txt
View File

@ -3,6 +3,11 @@
\page configurationvariables Summary of %CGAL's Configuration Variables
\cgalAutoToc
\cgalAdvancedBegin
This page lists CMake variables which you can use to help CMake find missing dependencies
while using the command line. We however recommend using the graphical interface (`cmake-gui`).
\cgalAdvancedEnd
\section installation_summary Summary of CGAL's Configuration Variables
Most configuration variables are not environment variables but

6
Documentation/doc/Documentation/advanced/Installation.txt
View File

@ -2,11 +2,13 @@
\page installation Building %CGAL libraries (non header-only mode)
\cgalAutoToc
<b>Since \cgal version 5.0, \cgal is header-only be default, which means
\cgalAdvancedBegin
Since \cgal version 5.0, \cgal is header-only be default, which means
that there is no need to compile \cgal or its libraries before it can be used.
This page is for advanced users that have a good reason to still use the old way.
If this is not your case, head over back to the page \ref general_intro.</b>
If this is not your case, head over back to the page \ref general_intro.
\cgalAdvancedEnd
This page is a step-by-step description of how to configure, build, and (optionally) install \cgal
in case you do not wish to use the - now enabled by default - header-only mode of \cgal.

8
Documentation/doc/Documentation/advanced/advanced.txt
View File

@ -1,8 +0,0 @@
/*!
\page advanced Advanced
- \subpage configurationvariables lists the various CMake variables that can be used to help find third-party dependencies.
- \subpage installation describes the (optional) process of building and installing %CGAL itself.
*/

32
Documentation/doc/Documentation/main.txt
View File

@ -5,12 +5,15 @@
The Computational Geometry Algorithms Library (\cgal) is a software project
that provides easy access to efficient and reliable geometric algorithms
in the form of a C++ library.
<br><br>
<h2>Package Overview</h2>
\cgal offers data structures and algorithms like \ref PartTriangulationsAndDelaunayTriangulations "triangulations",
\ref PartVoronoiDiagrams "Voronoi diagrams", \ref PartPolygons, \ref PartPolyhedra,
\ref PartArrangements "arrangements of curves", \ref PartMeshing "mesh generation",
\ref PartGeometryProcessing "geometry processing", \ref PartConvexHullAlgorithms "convex hull algorithms",
to name just a few.
All these data structures and algorithms operate on geometric objects
like points and segments, and perform geometric tests on them. These
objects and predicates are regrouped in \ref PartKernels "CGAL Kernels".
@ -21,33 +24,26 @@ solver for linear and quadratic programs. It further offers interfaces
to third party software such as the GUI libraries Qt, Geomview, and
the Boost Graph Library.
Getting Started
===============
The complete list of packages is available on the page \ref packages.
<h2>Getting Started</h2>
- \ref usage describes how to obtain \cgal and the few steps required to build a program using \cgal.
Head over to \ref general_intro to learn how to obtain, install, and use \cgal.
- \ref thirdparty lists required and optional third party libraries.
<h2>License</h2>
- \ref manual gives an idea of where you should look for documentation.
- \ref preliminaries lists how to control inlining, thread safety, code deprecation, checking of pre- and postconditions, and how to alter the failure behavior.
Once you are familiar with building your programs with \cgal and how the documentation is structured,
you can head over to the \ref tutorials for a hand-in-hand introduction to \cgal data structures
and algorithms, or directly to the package(s) that interest you the \ref packages. Each package
contains simple examples of the various functionalities of the package.
License
=======
%CGAL is distributed under a dual-license scheme. %CGAL can be used
together with Open Source software free of charge. Using %CGAL in
other contexts can be done by obtaining a commercial license from
[GeometryFactory](http://www.geometryfactory.com). For more details
see the \ref license "License" page.
Manuals for the Previous Releases
=================================
<h2>Acknowledgement</h2>
We provide bibtex entries for each package so that you can cite \cgal correctly in your publications,
see the page \ref how_to_cite_cgal.
<h2>Manuals for the Previous Releases</h2>
For releases >= 4.2, visit [https://doc.cgal.org/X.Y](https://doc.cgal.org/4.2)

5
Documentation/doc/Documentation/windows.txt
View File

@ -2,6 +2,9 @@
\page windows Using %CGAL on Windows (with Visual C++)
\cgalAutoToc
\cgal \cgalReleaseNumber is supported for the following \sc{MS} Visual `C++` compilers:
14.0, 15.9, 16.0 (\sc{Visual Studio} 2015, 2017, and 2019).
\cgal is a library that has mandatory dependencies that must be first installed:
\ref thirdpartyBoost and \ref thirdpartyMPFR.
@ -57,7 +60,7 @@ Note that \cgal is a header-only library, and there are therefore no `lib` or `d
In this section we show how to compile a program that uses \cgal.
The examples you find in these User Manual pages are not downloaded when you install \cgal
with the Vcpkg library manager. You must download them separately from the following download page:
<a href="https://github.com/CGAL/cgal/releases/CGAL-\cgalReleaseNumber-examples.zip">CGAL-\cgalReleaseNumber-examples.zip</a>
<a href="https://github.com/CGAL/cgal/releases/CGAL-\cgalReleaseNumber/CGAL-\cgalReleaseNumber-examples.zip">CGAL-\cgalReleaseNumber-examples.zip</a>
Assuming you have unzipped this file in your home directory `C:\Users\Me`,
we will next compile an example from the 2D Triangulation package.