Merge remote-tracking branch 'upstream/master'

.openscad_docsgen_rc

@@ -1,7 +1,7 @@
 DocsDirectory: BOSL2.wiki/
 TargetProfile: githubwiki
 ProjectName: The Belfry OpenScad Library, v2. (BOSL2)
-GenerateDocs: Files, TOC, Index, Topics, CheatSheet, Sidebar
+GenerateDocs: Files, TOC, Index, Topics, CheatSheet, Sidebar, Glossary
 SidebarHeader:
   ## Indices
   .

paths.scad

@@ -16,17 +16,22 @@
 //////////////////////////////////////////////////////////////////////
 
 // Section: Utility Functions
+// Definitions:
+//   Point|Points = A numeric vector of length 2 or 3 that represents either a 2D or 3D vertex.
+//   Pointlist|Pointlists|Point List|Point Lists = An unordered list of points.
+//   Path|Paths = A list of two or more 2D {{point}} coordinates that specify a route on the XY plane.
+//   Polygon|Polygons = A {{path}} where the first and last {{point}} coordinates are considered to be connected.
 
 // Function: is_path()
-// Synopsis: Returns True if 'list' is a path.
+// Synopsis: Returns True if 'list' is a {{path}}.
 // Topics: Paths
 // See Also: is_region(), is_vnf()
 // Usage:
 //   is_path(list, [dim], [fast])
 // Description:
-//   Returns true if `list` is a path.  A path is a list of two or more numeric vectors (AKA points).
+//   Returns true if `list` is a {{path}}.  A path is a list of two or more numeric vectors (AKA {{points}}).
 //   All vectors must of the same size, and may only contain numbers that are not inf or nan.
-//   By default the vectors in a path must be 2d or 3d.  Set the `dim` parameter to specify a list
+//   By default the vectors in a path must be 2D or 3D.  Set the `dim` parameter to specify a list
 //   of allowed dimensions, or set it to `undef` to allow any dimension.  (Note that this function
 //   returns `false` on 1-regions.)  
 // Example:
@@ -58,13 +63,13 @@ function is_path(list, dim=[2,3], fast=false) =
         && (is_undef(dim) || in_list(len(list[0]), force_list(dim)));
 
 // Function: is_1region()
-// Synopsis: Returns true if path is a region with one component.
+// Synopsis: Returns true if {{path}} is a {{region}} with one component.
 // Topics: Paths, Regions
 // See Also: force_path()
 // Usage:
 //   bool = is_1region(path, [name])
 // Description:
-//   If `path` is a region with one component (a 1-region) then return true.  If path is a region with more components
+//   If `path` is a {{region}} with one component (a single-{{path}} region, or 1-region) then returns true.  If path is a region with more components
 //   then display an error message about the parameter `name` requiring a path or a single component region.  If the input
 //   is not a region then return false.  This function helps path functions accept 1-regions.
 // Arguments:
@@ -84,8 +89,8 @@ function is_1region(path, name="path") =
 // Usage:
 //   outpath = force_path(path, [name])
 // Description:
-//   If `path` is a region with one component (a 1-region) then returns that component as a path.
+//   If `path` is a {{region}} with one component (a single-{{path}} region, or 1-region) then returns that component as a path.
-//   If path is a region with more components then displays an error message about the parameter
+//   If `path` is a region with more components then displays an error message about the parameter
 //   `name` requiring a path or a single component region.  If the input is not a region then
 //   returns the input without any checks.  This function helps path functions accept 1-regions.
 // Arguments:
@@ -134,7 +139,7 @@ function _path_select(path, s1, u1, s2, u2, closed=false) =
 // SynTags: Path
 // Topics: Paths, Regions
 // Description:
-//   Takes a path and removes unnecessary sequential collinear points.  Note that when `closed=true` either of the path
+//   Takes a {{path}} and removes unnecessary sequential collinear {{points}}.  Note that when `closed=true` either of the path
 //   endpoints may be removed.  
 // Usage:
 //   path_merge_collinear(path, [eps])
@@ -168,7 +173,7 @@ function path_merge_collinear(path, closed, eps=EPSILON) =
 // Usage:
 //   path_length(path,[closed])
 // Description:
-//   Returns the length of the path.
+//   Returns the length of the given {{path}}.
 // Arguments:
 //   path = Path of any dimension or 1-region. 
 //   closed = true if the path is closed.  Default: false
@@ -185,7 +190,7 @@ function path_length(path,closed) =
 
 
 // Function: path_segment_lengths()
-// Synopsis: Returns a list of the lengths of segments in a path.
+// Synopsis: Returns a list of the lengths of segments in a {{path}}.
 // Topics: Paths
 // See Also: path_length(), path_length_fractions()
 // Usage:
@@ -213,7 +218,7 @@ function path_segment_lengths(path, closed) =
 // Usage:
 //   fracs = path_length_fractions(path, [closed]);
 // Description:
-//    Returns the distance fraction of each point in the path along the path, so the first
+//    Returns the distance fraction of each point in the {{path}} along the path, so the first
 //    point is zero and the final point is 1.  If the path is closed the length of the output
 //    will have one extra point because of the final connecting segment that connects the last
 //    point of the path to the first point.
@@ -241,7 +246,7 @@ function path_length_fractions(path, closed) =
 /// Usage:
 ///   isects = _path_self_intersections(path, [closed], [eps]);
 /// Description:
-///   Locates all self intersection points of the given path.  Returns a list of intersections, where
+///   Locates all self intersection {{points}} of the given {{path}}.  Returns a list of intersections, where
 ///   each intersection is a list like [POINT, SEGNUM1, PROPORTION1, SEGNUM2, PROPORTION2] where
 ///   POINT is the coordinates of the intersection point, SEGNUMs are the integer indices of the
 ///   intersecting segments along the path, and the PROPORTIONS are the 0.0 to 1.0 proportions
@@ -324,10 +329,10 @@ function _sum_preserving_round(data, index=0) =
 // Usage:
 //   newpath = subdivide_path(path, n|refine=|maxlen=, [method=], [closed=], [exact=]);
 // Description:
-//   Takes a path as input (closed or open) and subdivides the path to produce a more
+//   Takes a {{path}} as input (closed or open) and subdivides the path to produce a more
 //   finely sampled path.  You control the subdivision process by using the `maxlen` arg
 //   to specify a maximum segment length, or by specifying `n` or `refine`, which request
-//   a certain point count in the output.
+//   a certain {{point}} count in the output.
 //   .
 //   You can specify the point count using the `n` option, where
 //   you give the number of points you want in the output, or you can use
@@ -470,8 +475,8 @@ function subdivide_path(path, n, refine, maxlen, closed=true, exact, method) =
 // Usage:
 //   newpath = resample_path(path, n|spacing=, [closed=]);
 // Description:
-//   Compute a uniform resampling of the input path.  If you specify `n` then the output path will have n
+//   Compute a uniform resampling of the input {{path}}.  If you specify `n` then the output path will have n
-//   points spaced uniformly (by linear interpolation along the input path segments).  The only points of the
+//   {{points}} spaced uniformly (by linear interpolation along the input path segments).  The only points of the
 //   input path that are guaranteed to appear in the output path are the starting and ending points, and any
 //   points that have an angular deflection of at least the number of degrees given in `keep_corners`.
 //   If you specify `spacing` then the length you give will be rounded to the nearest spacing that gives
@@ -561,14 +566,14 @@ function resample_path(path, n, spacing, keep_corners, closed=true) =
 // Section: Path Geometry
 
 // Function: is_path_simple()
-// Synopsis: Returns true if a path has no self intersections.
+// Synopsis: Returns true if a {{path}} has no self intersections.
 // Topics: Paths
 // See Also: is_path()
 // Usage:
 //   bool = is_path_simple(path, [closed], [eps]);
 // Description:
-//   Returns true if the given 2D path is simple, meaning that it has no self-intersections.
+//   Returns true if the given 2D {{path}} is simple, meaning that it has no self-intersections.
-//   Repeated points are not considered self-intersections: a path with such points can
+//   Repeated {{points}} are not considered self-intersections: a path with such points can
 //   still be simple.  
 //   If closed is set to true then treat the path as a polygon.
 // Arguments:
@@ -597,13 +602,13 @@ function is_path_simple(path, closed, eps=EPSILON) =
 
 
 // Function: path_closest_point()
-// Synopsis: Returns the closest place on a path to a given point.
+// Synopsis: Returns the closest place on a {{path}} to a given {{point}}.
 // Topics: Paths
 // See Also: point_line_distance(), line_closest_point()
 // Usage:
 //   index_pt = path_closest_point(path, pt);
 // Description:
-//   Finds the closest path segment, and point on that segment to the given point.
+//   Finds the closest {{path}} segment, and {{point}} on that segment to the given point.
 //   Returns `[SEGNUM, POINT]`
 // Arguments:
 //   path = Path of any dimension or a 1-region.
@@ -635,7 +640,7 @@ function path_closest_point(path, pt, closed=true) =
 // Usage:
 //   tangs = path_tangents(path, [closed], [uniform]);
 // Description:
-//   Compute the tangent vector to the input path.  The derivative approximation is described in deriv().
+//   Compute the tangent vector to the input {{path}}.  The derivative approximation is described in deriv().
 //   The returns vectors will be normalized to length 1.  If any derivatives are zero then
 //   the function fails with an error.  If you set `uniform` to false then the sampling is
 //   assumed to be non-uniform and the derivative is computed with adjustments to produce corrected
@@ -674,15 +679,15 @@ function path_tangents(path, closed, uniform=true) =
 // Usage:
 //   norms = path_normals(path, [tangents], [closed]);
 // Description:
-//   Compute the normal vector to the input path.  This vector is perpendicular to the
+//   Compute the normal vector to the input {{path}}.  This vector is perpendicular to the
 //   path tangent and lies in the plane of the curve.  For 3d paths we define the plane of the curve
-//   at path point i to be the plane defined by point i and its two neighbors.  At the endpoints of open paths
+//   at path {{point}} i to be the plane defined by point i and its two neighbors.  At the endpoints of open paths
 //   we use the three end points.  For 3d paths the computed normal is the one lying in this plane that points
-//   towards the center of curvature at that path point.  For 2d paths, which lie in the xy plane, the normal
+//   towards the center of curvature at that path point.  For 2D paths, which lie in the xy plane, the normal
 //   is the path pointing to the right of the direction the path is traveling.  If points are collinear then
 //   a 3d path has no center of curvature, and hence the 
 //   normal is not uniquely defined.  In this case the function issues an error.
-//   For 2d paths the plane is always defined so the normal fails to exist only
+//   For 2D paths the plane is always defined so the normal fails to exist only
 //   when the derivative is zero (in the case of repeated points).
 // Arguments:
 //   path = 2D or 3D path or a 1-region
@@ -713,13 +718,13 @@ function path_normals(path, tangents, closed) =
 
 
 // Function: path_curvature()
-// Synopsis: Returns the estimated numerical curvature of the path.
+// Synopsis: Returns the estimated numerical curvature of the {{path}}.
 // Topics: Paths
 // See Also: path_tangents(), path_normals(), path_torsion()
 // Usage:
 //   curvs = path_curvature(path, [closed]);
 // Description:
-//   Numerically estimate the curvature of the path (in any dimension).
+//   Numerically estimate the curvature of the {{path}} (in any dimension).
 // Arguments:
 //   path = path in any dimension or a 1-region
 //   closed = if true then treat the path as a polygon.  Default: false
@@ -741,13 +746,13 @@ function path_curvature(path, closed) =
 
 
 // Function: path_torsion()
-// Synopsis: Returns the estimated numerical torsion of the path.
+// Synopsis: Returns the estimated numerical torsion of the {{path}}.
 // Topics: Paths
 // See Also: path_tangents(), path_normals(), path_curvature()
 // Usage:
 //   torsions = path_torsion(path, [closed]);
 // Description:
-//   Numerically estimate the torsion of a 3d path.
+//   Numerically estimate the torsion of a 3d {{path}}.
 // Arguments:
 //   path = 3D path
 //   closed = if true then treat path as a polygon.  Default: false
@@ -766,16 +771,16 @@ function path_torsion(path, closed=false) =
 
 
 // Function: surface_normals()
-// Synopsis: Estimates the normals to a surface defined by a point array
+// Synopsis: Estimates the normals to a surface defined by a {{point}} array
 // Topics: Math, Geometry
 // See Also: path_tangents(), path_normals()
 // Usage:
 //   normals = surface_normals(surf, [col_wrap=], [row_wrap=]);
 // Description:
-//   Numerically estimate the normals to a surface defined by a 2d array of 3d points, which can
+//   Numerically estimate the normals to a surface defined by a 2D array of 3d {{points}}, which can
-//   also be regarded as an array of paths (all of the same length).  
+//   also be regarded as an array of {{paths}} (all of the same length).  
 // Arguments:
-//   surf = surface in 3d defined by a 2d array of points
+//   surf = surface in 3d defined by a 2D array of points
 //   ---
 //   row_wrap = if true then wrap path in the row direction (first index)
 //   col_wrap = if true then wrap path in the column direction (second index)
@@ -796,19 +801,19 @@ function surface_normals(surf, col_wrap=false, row_wrap=false) =
 
 
 // Function: path_cut()
-// Synopsis: Cuts a path into subpaths at various points.
+// Synopsis: Cuts a {{path}} into subpaths at various {{points}}.
 // SynTags: PathList
 // Topics: Paths, Path Subdivision
 // See Also: split_path_at_self_crossings(), path_cut_points()
 // Usage:
 //   path_list = path_cut(path, cutdist, [closed]);
 // Description:
-//   Given a list of distances in `cutdist`, cut the path into
+//   Given a list of distances in `cutdist`, cut the {{path}} into
 //   subpaths at those lengths, returning a list of paths.
 //   If the input path is closed then the final path will include the
-//   original starting point.  The list of cut distances must be
+//   original starting {{point}}.  The list of cut distances must be
 //   in ascending order and should not include the endpoints: 0 
-//   or len(path).  If you repeat a distance you will get an
+//   or `len(path)`.  If you repeat a distance you will get an
 //   empty list in that position in the output.  If you give an
 //   empty cutdist array you will get the input path as output
 //   (without the final vertex doubled in the case of a closed path).
@@ -858,14 +863,14 @@ function _path_cut_getpaths(path, cutlist, closed) =
 
 
 // Function: path_cut_points()
-// Synopsis: Returns a list of cut points at a list of distances from the first point in a path.
+// Synopsis: Returns a list of cut {{points}} at a list of distances from the first point in a {{path}}.
 // Topics: Paths, Path Subdivision
 // See Also: path_cut(), split_path_at_self_crossings()
 // Usage:
 //   cuts = path_cut_points(path, cutdist, [closed=], [direction=]);
 //
 // Description:
-//   Cuts a path at a list of distances from the first point in the path.  Returns a list of the cut
+//   Cuts a {{path}} at a list of distances from the first {{point}} in the path.  Returns a list of the cut
 //   points and indices of the next point in the path after that point.  So for example, a return
 //   value entry of [[2,3], 5] means that the cut point was [2,3] and the next point on the path after
 //   this point is path[5].  If the path is too short then path_cut_points returns undef.  If you set
@@ -996,14 +1001,14 @@ function _cut_to_seg_u_form(pathcut, path, closed) =
 
 
 // Function: split_path_at_self_crossings()
-// Synopsis: Split a 2D path wherever it crosses itself.
+// Synopsis: Split a 2D {{path}} wherever it crosses itself.
 // SynTags: PathList
 // Topics: Paths, Path Subdivision
 // See Also: path_cut(), path_cut_points()
 // Usage:
 //   paths = split_path_at_self_crossings(path, [closed], [eps]);
 // Description:
-//   Splits a 2D path into sub-paths wherever the original path crosses itself.
+//   Splits a 2D {{path}} into sub-paths wherever the original path crosses itself.
 //   Splits may occur mid-segment, so new vertices will be created at the intersection points.
 //   Returns a list of the resulting subpaths.  
 // Arguments:
@@ -1067,14 +1072,14 @@ function _tag_self_crossing_subpaths(path, nonzero, closed=true, eps=EPSILON) =
 
 
 // Function: polygon_parts()
-// Synopsis: Parses a self-intersecting polygon into a list of non-intersecting polygons.
+// Synopsis: Parses a self-intersecting polygon into a list of non-intersecting {{polygons}}.
 // SynTags: PathList
 // Topics: Paths, Polygons
 // See Also: split_path_at_self_crossings(), path_cut(), path_cut_points()
 // Usage:
 //   splitpolys = polygon_parts(poly, [nonzero], [eps]);
 // Description:
-//   Given a possibly self-intersecting 2d polygon, constructs a representation of the original polygon as a list of
+//   Given a possibly self-intersecting 2D {{polygon}}, constructs a representation of the original polygon as a list of
 //   non-intersecting simple polygons.  If nonzero is set to true then it uses the nonzero method for defining polygon membership.
 //   For simple cases, such as the pentagram, this will produce the outer perimeter of a self-intersecting polygon.  
 // Arguments:
@@ -1327,7 +1332,4 @@ function _assemble_partial_paths_recur(edges, eps, paths=[], i=0) =
 
 
 
-
-
-
 // vim: expandtab tabstop=4 shiftwidth=4 softtabstop=4 nowrap

regions.scad

@@ -19,7 +19,7 @@
 
 
 // Section: Regions
-//   A region is a list of polygons meeting these conditions:
+//   A {{region}} is a list of polygons meeting these conditions:
 //   .
 //   - Every polygon on the list is simple, meaning it does not intersect itself
 //   - Two polygons on the list do not cross each other
@@ -37,32 +37,56 @@
 //   Checking that a list of polygons is a valid region, meaning that it satisfies all of the conditions
 //   above, can be a time consuming test, so it is not done automatically.  It is your responsibility to ensure that your regions are
 //   compliant.  You can construct regions by making a suitable list of polygons, or by using
-//   set operation function such as union() or difference(), which all acccept polygons, as
+//   set operation function such as {{union()}} or {{difference()}}, which all acccept polygons, as
 //   well as regions, as their inputs. If you must, you can clean up an ill-formed region using
-//   {{make_region()}}, which breaks up self-intersecting polygons and polygons that cross each other.  
+//   {{make_region()}}, which breaks up self-intersecting polygons and polygons that cross each other.
+//
+// Figure(2D): An Sample {{Region}}
+//   path1 = union([
+//       circle(d=100),
+//       translate([50,20], p=circle(d=40))
+//   ])[0];
+//   rgn = [
+//       // Main shape
+//       select(path1, hull(path1)),
+//       translate([50,20], p=circle(d=20)),
+//       rot(-8, p=hexagon(d=60, rounding=10)),
+//       // Inner disjointed shape
+//       circle(d=25),
+//       rot(30-8, p=rect(10)),
+//       // External disjoined shape
+//       each translate([60,-25], p=rot(55, p=[
+//           rect([20,15], rounding=5),
+//           ellipse([6,3])
+//       ])),
+//   ];
+//   region(rgn);
+//
+// Definitions:
+//   Region|Regions = A list of zero or more non-intersecting {{polygons}}, representing possibly disjointed shape perimeters with enclosed holes.
 
 
 // Function: is_region()
-// Synopsis: Returns true if the input appears to be a region.
+// Synopsis: Returns true if the input appears to be a {{region}}.
 // Topics: Regions, Paths, Polygons, List Handling
 // See Also: is_valid_region(), is_1region(), is_region_simple()
 // Usage:
 //   bool = is_region(x);
 // Description:
-//   Returns true if the given item looks like a region.  A region is a list of non-crossing simple polygons.  This test just checks
+//   Returns true if the given item looks like a {{region}}.  A region is a list of non-crossing simple {{polygons}}.  This test just checks
 //   that the argument is a list whose first entry is a path.  
 function is_region(x) = is_list(x) && is_path(x.x);
 
 
 // Function: is_valid_region()
-// Synopsis: Returns true if the input is a valid region.
+// Synopsis: Returns true if the input is a valid {{region}}.
 // Topics: Regions, Paths, Polygons, List Handling
 // See Also: is_region(), is_1region(), is_region_simple()
 // Usage:
 //   bool = is_valid_region(region, [eps]);
 // Description:
-//   Returns true if the input is a valid region, meaning that it is a list of simple polygons whose segments do not cross each other.
+//   Returns true if the input is a valid {{region}}, meaning that it is a list of simple {{polygons}} whose segments do not cross each other.
-//   This test can be time consuming with regions that contain many points.
+//   This test can be time consuming with regions that contain many {{points}}.
 //   It differs from `is_region()`, which simply checks that the object is a list whose first entry is a path
 //   because it searches all the list polygons for any self-intersections or intersections with each other.  
 //   Also returns true if given a single simple polygon.  Use {{make_region()}} to convert sets of self-intersecting polygons into
@@ -220,7 +244,7 @@ function _polygon_crosses_region(region, poly, eps=EPSILON) =
 // Usage:
 //   bool = is_region_simple(region, [eps]);
 // Description:
-//   We extend the notion of the simple path to regions: a simple region is entirely
+//   We extend the notion of the simple {{path}} to {{regions}}: a simple region is entirely
 //   non-self-intersecting, meaning that it is formed from a list of simple polygons that
 //   don't intersect each other at all—not even with corner contact points.
 //   Regions with corner contact are valid but may fail CGAL.  Simple regions
@@ -247,7 +271,7 @@ function is_region_simple(region, eps=EPSILON) =
   
   
 // Function: make_region()
-// Synopsis: Converts lists of intersecting polygons into valid regions.
+// Synopsis: Converts lists of intersecting {{polygons}} into valid {{regions}}.
 // SynTags: Region
 // Topics: Regions, Paths, Polygons, List Handling
 // See Also: force_region(), region()
@@ -255,8 +279,8 @@ function is_region_simple(region, eps=EPSILON) =
 // Usage:
 //   region = make_region(polys, [nonzero], [eps]);
 // Description:
-//   Takes a list of polygons that may intersect themselves or cross each other 
+//   Takes a list of {{polygons}} that may intersect themselves or cross each other 
-//   and converts it into a properly defined region without these defects.
+//   and converts it into a properly defined {{region}} without these defects.
 // Arguments:
 //   polys = list of polygons to use
 //   nonzero = set to true to use nonzero rule for polygon membership.  Default: false
@@ -297,14 +321,14 @@ function force_region(poly) = is_path(poly) ? [poly] : poly;
 // Section: Turning a region into geometry
 
 // Module: region()
-// Synopsis: Creates the 2D polygons described by the given region or list of polygons.
+// Synopsis: Creates the 2D {{polygons}} described by the given {{region}} or list of polygons.
 // SynTags: Geom
 // Topics: Regions, Paths, Polygons, List Handling
 // See Also: make_region(), debug_region()
 // Usage:
 //   region(r, [anchor], [spin=], [cp=], [atype=]) [ATTACHMENTS];
 // Description:
-//   Creates the 2D polygons described by the given region or list of polygons.  This module works on
+//   Creates the 2D {{polygons}} described by the given {{region}} or list of polygons.  This module works on
 //   arbitrary lists of polygons that cross each other and hence do not define a valid region.  The
 //   displayed result is the exclusive-or of the polygons listed in the input. 
 // Arguments:
@@ -345,7 +369,7 @@ module region(r, anchor="origin", spin=0, cp="centroid", atype="hull")
 
 
 // Module: debug_region()
-// Synopsis: Draws an annotated region.
+// Synopsis: Draws an annotated {{region}}.
 // SynTags: Geom
 // Topics: Shapes (2D)
 // See Also: region(), debug_polygon(), debug_vnf(), debug_bezier()
@@ -353,7 +377,7 @@ module region(r, anchor="origin", spin=0, cp="centroid", atype="hull")
 // Usage:
 //   debug_region(region, [vertices=], [edges=], [convexity=], [size=]);
 // Description:
-//   A replacement for {{region()}} that displays the region and labels the vertices and
+//   A replacement for {{region()}} that displays the {{region}} and labels the vertices and
 //   edges.  The region vertices and edges are labeled with letters to identify the path
 //   component in the region, starting with A.  
 //   The start of each path is marked with a blue circle and the end with a pink diamond.
@@ -392,13 +416,13 @@ module debug_region(region, vertices=true, edges=true, convexity=2, size=1)
 // Section: Geometrical calculations with regions
 
 // Function: point_in_region()
-// Synopsis: Tests if a point is inside, outside, or on the border of a region. 
+// Synopsis: Tests if a point is inside, outside, or on the border of a {{region}}. 
 // Topics: Regions, Points, Comparison
 // See Also: region_area(), are_regions_equal()
 // Usage:
 //   check = point_in_region(point, region, [eps]);
 // Description:
-//   Tests if a point is inside, outside, or on the border of a region.  
+//   Tests if a point is inside, outside, or on the border of a {{region}}.  
 //   Returns -1 if the point is outside the region.
 //   Returns 0 if the point is on the boundary.
 //   Returns 1 if the point lies inside the region.
@@ -430,12 +454,12 @@ function _point_in_region(point, region, eps=EPSILON, i=0, cnt=0) =
 
 
 // Function: region_area()
-// Synopsis: Computes the area of the specified valid region.
+// Synopsis: Computes the area of the specified valid {{region}}.
 // Topics: Regions, Area
 // Usage:
 //   area = region_area(region);
 // Description:
-//   Computes the area of the specified valid region. (If the region is invalid and has self intersections
+//   Computes the area of the specified valid {{region}}. (If the region is invalid and has self intersections
 //   the result is meaningless.)
 // Arguments:
 //   region = region whose area to compute
@@ -561,15 +585,15 @@ function _region_region_intersections(region1, region2, closed1=true,closed2=tru
 
 
 // Function: split_region_at_region_crossings()
-// Synopsis: Splits regions where polygons touch and at intersections.
+// Synopsis: Splits {{regions}} where {{polygons}} touch and at intersections.
 // Topics: Regions, Polygons, List Handling
 // See Also: region_parts()
 // 
 // Usage:
 //   split_region = split_region_at_region_crossings(region1, region2, [closed1], [closed2], [eps])
 // Description:
-//   Splits region1 at the places where polygons in region1 touches each other at corners and at locations
+//   Splits the {{region} `region1` at the places where its {{polygons}} touches each other at corners and at locations
-//   where region1 intersections region2.  Split region2 similarly with respect to region1.
+//   where `region1` intersects `region2`.  Split `region2` similarly with respect to `region1`.
 //   The return is a pair of results of the form [split1, split2] where split1=[frags1,frags2,...]
 //   and frags1 is a list of paths that when placed end to end (in the given order), give the first polygon of region1.
 //   Each path in the list is either entirely inside or entirely outside region2.  
@@ -628,14 +652,14 @@ function split_region_at_region_crossings(region1, region2, closed1=true, closed
                 
 
 // Function: region_parts()
-// Synopsis: Splits a region into a list of connected regions.
+// Synopsis: Splits a {{region}} into a list of connected regions.
 // SynTags: RegList
 // Topics: Regions, List Handling
 // See Also: split_region_at_region_crossings()
 // Usage:
 //   rgns = region_parts(region);
 // Description:
-//   Divides a region into a list of connected regions.  Each connected region has exactly one clockwise outside boundary
+//   Divides a {{region}} into a list of connected regions.  Each connected region has exactly one clockwise outside boundary
 //   and zero or more counter-clockwise outlines defining internal holes. Behavior is undefined on invalid regions whose
 //   components cross each other.
 // Example(2D,NoAxes):
@@ -804,14 +828,14 @@ function _point_dist(path,pathseg_unit,pathseg_len,pt) =
 
 
 // Function: offset()
-// Synopsis: Takes a 2D path, polygon or region and returns a path offset by an amount.
+// Synopsis: Takes a 2D {{path}}, {{polygon}} or {{region}} and returns a path offset by an amount.
 // SynTags: Path, Region, Ext
 // Topics: Paths, Polygons, Regions
 // Usage:
 //   offsetpath = offset(path, [r=|delta=], [chamfer=], [closed=], [check_valid=], [quality=], [error=], [same_length=])
 //   path_faces = offset(path, return_faces=true, [r=|delta=], [chamfer=], [closed=], [check_valid=], [quality=], [error=], [firstface_index=], [flip_faces=])
 // Description:
-//   Takes a 2D input path, polygon or region and returns a path offset by the specified amount.  As with the built-in
+//   Takes a 2D input {{path}}, {{polygon}} or {{region}} and returns a path offset by the specified amount.  As with the built-in
 //   offset() module, you can use `r` to specify rounded offset and `delta` to specify offset with
 //   corners.  If you used `delta` you can set `chamfer` to true to get chamfers.
 //   When `closed=true` (the default), the input is treated as a polygon.  If the input is a region it is treated as a collection
@@ -1200,7 +1224,7 @@ function _list_three(a,b,c) =
 //   region = union(REGION1,REGION2);
 //   region = union(REGION1,REGION2,REGION3);
 // Description:
-//   When called as a function and given a list of regions or 2D polygons,
+//   When called as a function and given a list of {{regions}} or 2D {{polygons}},
 //   returns the union of all given regions and polygons.  Result is a single region.
 //   When called as the built-in module, makes the union of the given children.
 //   This function is **much** slower than the native union module acting on geometry,
@@ -1237,7 +1261,7 @@ function union(regions=[],b=undef,c=undef,eps=EPSILON) =
 //   region = difference(REGION1,REGION2);
 //   region = difference(REGION1,REGION2,REGION3);
 // Description:
-//   When called as a function, and given a list of regions or 2D polygons, 
+//   When called as a function, and given a list of {{regions}} or 2D {{polygons}}, 
 //   takes the first region or polygon and differences away all other regions/polygons from it.  The resulting
 //   region is returned.
 //   When called as the built-in module, makes the set difference of the given children.
@@ -1276,7 +1300,7 @@ function difference(regions=[],b=undef,c=undef,eps=EPSILON) =
 //   region = intersection(REGION1,REGION2);
 //   region = intersection(REGION1,REGION2,REGION3);
 // Description:
-//   When called as a function, and given a list of regions or polygons returns the
+//   When called as a function, and given a list of {{regions}} or {{polygons}} returns the
 //   intersection of all given regions.  Result is a single region.
 //   When called as the built-in module, makes the intersection of all the given children.
 // Arguments:
@@ -1312,7 +1336,7 @@ function intersection(regions=[],b=undef,c=undef,eps=EPSILON) =
 //   region = exclusive_or(REGION1,REGION2);
 //   region = exclusive_or(REGION1,REGION2,REGION3);
 // Description:
-//   When called as a function and given a list of regions or 2D polygons, 
+//   When called as a function and given a list of {{regions}} or 2D {{polygons}}, 
 //   returns the exclusive_or of all given regions.  Result is a single region.
 //   When called as a module, performs a Boolean exclusive-or of up to 10 children. Note that when
 //   the input regions cross each other, the exclusive-or operator produces shapes that
@@ -1466,14 +1490,14 @@ module exclusive_or() {
 
 
 // Function&Module: hull_region()
-// Synopsis: Compute convex hull of region or 2d path
+// Synopsis: Compute convex hull of {{region}} or 2D {{path}}
 // SynTags: Geom, Path
 // Topics: Regions, Polygons, Shapes2D
 // Usage:
 //    path = hull_region(region);
 //    hull_region(region);
 // Description:
-//   Given a path, or a region, compute the convex hull
+//   Given a {{path}}, or a {{region}}, compute the convex hull
 //   and return it as a path.  This differs from {{hull()}} and {{hull2d_path()}}, which
 //   return an index list into the point list.  As a module invokes the native hull() on
 //   the specified region.