CGAL: About namespace internal (#8896)

## Summary of Changes

The Developer Manual recommends `namespace CGAL::internal::Pkg`, whereas
we have decided that it must be `namespace CGAL::Pkg::internal`. See
also Issue #257

## Release Management

* Affected package(s): Developer Manual

Documentation/doc/Documentation/Developer_manual/Chapter_namespaces.txt

@@ -13,19 +13,31 @@ but the better alternative is the usage of `namespace`.
 
 \section Developer_manualNamespaceCGAL Namespace CGAL
 
-All names introduced by \cgal should be in namespace `CGAL`, <I>e.g.</I>:
+All names introduced by \cgal should be in namespace `CGAL`,  or in a subnamespace
+corresponding to a package, <I>e.g.</I>:
 \code{.cpp}
 #include <something>
 
 namespace CGAL {
 
-class My_new_cgal_class {};
+/*!
+  * This class ...
+  */
+class Foo {};
 
-My_new_cgal_class
-my_new_function( My_new_cgal_class& );
 
+namespace Polygon_mesh_processing {
+
+/*!
+  * modifies `f` by ...
+  */
+void
+bar( foo & f);
+
+} // namespace Polygon_mesh_processing
 } // namespace CGAL
 \endcode
+
 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.
@@ -35,19 +47,15 @@ added to the namespace.
 All names introduced by \cgal which are not documented to the user
 should be under an `internal` subnamespace of `CGAL`, <I>e.g.</I>:
 \code{.cpp}
-namespace CGAL { namespace internal {
+namespace CGAL {
+namespace Polygon_mesh_processing {
+namespace internal {
 
-class My_undocumented_class {};
+class Baz_used_by_foo {};
 
-void my_new_function( My_undocumented_class& );
-
-}} // namespace CGAL::internal
-
-namespace CGAL { namespace internal { namespace Package { namespace tags {
-
-class Some_further_class_local_to_Package;
-
-}}}} // namespace CGAL::internal::Package::tags
+} // namespace internal
+} // namespace Polygon_mesh_processing
+} // namespace CGAL
 \endcode
 
 \section Developer_manualNoteonglobaltemplatefunctions Note on global template functions