CGAL users discussion list

[Pouget Marc <>]

Dear Paul Heckbert,

thank you for taking time to report on your experience with our library.

Documentation is a constant work in progress for any software and we will 
take into account your remarks and suggestions for further improvements.

We will soon answer some of your specific questions on this list, and will 
work out your more general comments during our next developers meeting in 
September.

Best regards,

Editorial Board Manager of CGAL
Marc Pouget

On Aug 16, 2014, at 6:35 AM, paulheckbert wrote:

> CGAL is not as easy to use as advertised, and your examples and manual could
> use much better introductory explanation. CGAL seems to do a number of
> things right: code that uses CGAL is often admirably concise, but with your
> current documentation I think you’re scaring away a lot of potential CGAL
> users, and parts of the system are inscrutable to people who aren’t on the
> inside.
> 
> For example, for my first use of CGAL I tried using Min_sphere_of_spheres_d.
> Your manuals suggest that it’s easy to print objects (points, spheres, etc)
> and I tried that, with frustrating results:
> 
> * a Sphere with either coordinate type *does not print* to ostream! This was
> the first thing I tried. (got compiler error)
> * a Point with coordinate type double prints fine.
> * a Point with coordinate type rational (Gmpq) prints fine.
> * a Min_sphere (output of the function) with either coordinate type *does
> not print*.
> * the center of a Min_sphere with coordinate type double can be printed,
> coordinate by coordinate, if you dive into the manuals.
> * the center of a Min_sphere with coordinate type rational *does not print*,
> coordinate by coordinate.
> * the radius of a Min_sphere with coordinate type rational *does not print*.
> 
> About half the things I tried to do, above, generated voluminous compiler
> errors.
> 
> But your documentation led me to believe that output is easy. This page
> 
> http://doc.cgal.org/latest/Stream_support/index.html
> <http://doc.cgal.org/latest/Stream_support/index.html>  
> 
> says
> 
> /“All classes in the CGAL kernel provide input and output operators for IO
> streams. Classes external to CGAL are also supported, by means of
> oformat()”/
> 
> Apparently this is wrong. This document doesn’t give troubleshooting advice,
> unfortunately. Which classes are considered to be external to CGAL? I tried
> oformat and it didn’t help my problems.
> 
> To duplicate the problems mentioned above, take the attached code, and run
> 
> 
> I’m guessing that there’s probably a one-line fix to the above problems, but
> whatever it is, it’s not mentioned on the Stream_support web page. Perhaps
> there are ostream methods for these types but I haven’t “turned them on”? Or
> perhaps I should be converting explicitly to double or other type before
> printing? Is it documented somewhere? I’ve been trying to get this working
> better for a couple of hours.
> 
> More generally, I observe:
> 
> Your documentation does not adequately explain some key concepts of your
> software that obviously its developers understand well, but new users will
> find confusing. You are scaring away potential users by failing to document
> them better:
> 
> What do you mean by “kernel”? Not the same as the “kernel” of operating
> systems, or the “kernel” of signal processing, apparently. Why is a “kernel”
> needed?
> 
> What does FT stand for? Not floating-point type, apparently.
> 
> Explain Traits better. Perhaps demonstrate several examples that implement
> the traits in several different ways? Why are traits needed?
> 
> Give examples that motivate exact arithmetic better. The SIGGRAPH 2008
> tutorial has a nice picture, but why isn’t it in your Manual web pages?
> 
> At  http://doc.cgal.org/latest/Manual/introduction.html
> <http://doc.cgal.org/latest/Manual/introduction.html>   your first example
> does not print points! Example 4 is very important, since it discusses
> Traits, but it’s very confusing. This one needs a lot of work. To CGAL,
> “concept” means something special? If you hand example 4 to a CS senior,
> will it make sense to them?
> 
> Your documentation should say more about memory use and running time - not
> just “big Oh”, but actual times. What are the relative speeds of various
> data types and kernels? Multithreaded?
> 
> I bet, by improving your documentation, you could easily double your number
> of users.
> 
> thanks
> -Paul
> 
> PS: My background: PhD in computer science, taught computer graphics, image
> processing, computer vision, scientific computing at Carnegie Mellon
> University for nine years, editor of the book “Graphics Gems 4”, fluent in
> C++. If someone with my background finds CGAL frustrating, imagine how
> daunting it is for a novice.
> 
> I’m using CGAL 4.4 on Mac OS 10.9, g++ compiler. I installed CGAL with ‘sudo
> port install cgal’.
> 
> 
> —
> 
> *Makefile*:
> 
> 
> *printsphere.cpp*:
> 
> 
> 
> 
> --
> View this message in context: 
> http://cgal-discuss.949826.n4.nabble.com/Suggestions-regarding-CGAL-s-documentation-tp4659700.html
> Sent from the cgal-discuss mailing list archive at Nabble.com.
> 
> -- 
> You are currently subscribed to cgal-discuss.
> To unsubscribe or access the archives, go to
> https://sympa.inria.fr/sympa/info/cgal-discuss
> 
>