Refinements

Author: djowel

docs/modules/ROOT/pages/common.adoc

@@ -15,7 +15,10 @@
 :mit_license: https://opensource.org/licenses/MIT[MIT License]
 
 :layout: xref:layout.adoc[Layout]
-:stretch-elements: xref:layout/stretch_elements.adoc[Stretch Elements]
-:layers: xref:layout/layers.adoc[Layers]
-:layers_semantics: xref:layout/layers.adoc#_semantics[Layer Semantics]
+:limits: xref:layout/limits.adoc[limits]
+:view_limits: xref:layout/limits.adoc#_view_limits[view_limits]
+
+:Stretch-Elements: xref:layout/stretch_elements.adoc[Stretch Elements]
+:Layers: xref:layout/layers.adoc[Layers]
+:Layers_Semantics: xref:layout/layers.adoc#_semantics[Layer Semantics]
 :decks: xref:layout/decks.adoc[Decks]

docs/modules/ROOT/pages/layout/decks.adoc

@@ -4,14 +4,14 @@ include::../common.adoc[]
 
 == Overview
 
-The Deck is very similar to {layers}. Elements are placed in the z-axis. But
+The Deck is very similar to {Layers}. Elements are placed in the z-axis. But
 unlike layers, only the selected element is active (top-most by default).
 
 image::/layout/deck.svg[alt="deck", width=353px, role=center]
 
 === Semantics
 
-. Everything listed in the {layers_semantics}, except 2 and 3.
+. Everything listed in the {Layers_Semantics}, except 2 and 3.
 . Only the active selected element element is drawn.
 . Only the active selected element is given the chance to process UI control.
 

docs/modules/ROOT/pages/layout/floating.adoc

@@ -29,8 +29,8 @@ floating({left, top, right, bottom}, subject)
 === Semantics
 
 . The element will be placed exactly to the specified position in the main
-view, constrained to the subject's natural _limits_.
-. The floating element does not violate the natural _limits_ of the subject.
+view, constrained to the subject's natural {limits}.
+. The floating element does not violate the natural {limits} of the subject.
 . Returns instance of `Proxy`.
 
 '''

docs/modules/ROOT/pages/layout/grids.adoc

@@ -20,7 +20,7 @@ image::/layout/hgrid.svg[alt="hgrid", width=347px, role=center]
 Horizontal Grids are composites that lay out one or more child elements in a
 row following externally supplied horizontal fractional positions. Horizontal
 Grids have computed horizontal and vertical sizes following the natural
-`limits` of its children.
+{limits} of its children.
 
 === Semantics
 
@@ -152,7 +152,7 @@ image::/layout/vgrid.svg[alt="vgrid", width=347px, role=center]
 Vertical Grids are composites that lay out one or more child elements in a
 column following externally supplied vertical fractional positions. Vertical
 Grids have computed horizontal and vertical sizes following the natural
-`limits` of its children.
+{limits} of its children.
 
 === Semantics
 

docs/modules/ROOT/pages/layout/limits.adoc

@@ -6,18 +6,13 @@ include::../common.adoc[]
 
 Each element provides information on how it wants to be sized by means of
 `min` and `max` limits: a hint that determine its actual extent and how it
-will be placed in the view depending on available window space. The element's
-`limits` member function determines the minimum and maximum extents of an
-element:
+will be placed in the view depending on available window space.
 
-[,c++]
-----
-view_limits limits(basic_context const& ctx) const;
-----
+== view_limits
 
-+++<a name="view_limits">++++++</a>+++
-See link:context[Context] for information about `basic_context`. `view_limits`
-is a struct that gives us the `min` and `max` information:
+`view_limits` is a struct that gives us the `min` and `max` information:
+
+=== Declaration
 
 [,c++]
 ----
@@ -28,39 +23,17 @@ struct view_limits
 };
 ----
 
-For the purpose of this document, we will use these terms and expressions:
+=== Notation
 
-limits:: The limits of an element
+`full_extent`:: An implementation-defined huge number that signifies an unbounded extent.
 
-limits.min:: The minimum limits of an element
+`point`:: A data structure representing a coordinate in a 2D space used to
+specify positions or dimensions within the graphical context.
 
-limits.min.x:: The minimum horizontal limit of an element
+=== full_limits
 
-limits.min.y:: The minimum vertical limit of an element
-
-limits.max:: The maximum limits of an element
-
-limits.max.x:: The maximum horizontal limit of an element
-
-limits.max.y:: The maximum vertical limit of an element
-
-horizontal limits:: (limits.min.x, limits.max.x)
-
-vertical limits:: (limits.min.y, limits.max.y)
-
-minimum limits:: (limits.min.x, limits.min.y)
-
-maximum limits:: (limits.max.x, limits.max.y)
-
-minimum horizontal limit:: limits.min.x
-
-maximum horizontal limit:: limits.max.x
-
-minimum vertical limit:: limits.min.y
-
-maximum vertical limit:: limits.max.y
-
-By default, an element has full limits: it is infinitely resizable:
+By default, an element has full limits, meaning there is no constraints on
+its size. It is infinitely resizable:
 
 [,c++]
 ----
@@ -73,17 +46,12 @@ constexpr view_limits full_limits = {
 An element with `full_limits` can be resized from an empty point (zero x and
 y size) up to the full extent of the screen, and beyond (if possible).
 
-NOTE: `full_extent` is actually an implementation defined huge
-number near the _maximum limits_ of the coordinate's data type (also
-implementation defined).
-
 * An element has a fixed horizontal size if this expression is true:
 `limits.min.x == limits.max.x`.
 * An element has a fixed vertical size if this expression is true:
 `limits.min.y == limits.max.y`.
 
-[discrete]
-==== Examples
+=== Examples
 
 [,c++]
 ----
@@ -100,6 +68,40 @@ implementation defined).
 {{100, 100}, {100, 200}}; // Fixed width, semi-flexible height (100 to 200)
 ----
 
+=== Terms and Expressions
+
+For the purpose of this document, we will use these terms and expressions:
+
+limits:: The limits of an element
+
+limits.min:: The minimum limits of an element
+
+limits.min.x:: The minimum horizontal limit of an element
+
+limits.min.y:: The minimum vertical limit of an element
+
+limits.max:: The maximum limits of an element
+
+limits.max.x:: The maximum horizontal limit of an element
+
+limits.max.y:: The maximum vertical limit of an element
+
+horizontal limits:: (limits.min.x, limits.max.x)
+
+vertical limits:: (limits.min.y, limits.max.y)
+
+minimum limits:: (limits.min.x, limits.min.y)
+
+maximum limits:: (limits.max.x, limits.max.y)
+
+minimum horizontal limit:: limits.min.x
+
+maximum horizontal limit:: limits.max.x
+
+minimum vertical limit:: limits.min.y
+
+maximum vertical limit:: limits.max.y
+
 '''
 
 _Copyright (c) 2014-2024 Joel de Guzman. All rights reserved._

docs/modules/ROOT/pages/layout/margin_elements.adoc

@@ -30,8 +30,8 @@ margin({left, top, right, bottom}, subject)
 
 . Space is added to the left, top, right, and bottom of the subject with the
 given parameters.
-. The element's _limits_ is overridden to account for the additional space.
-. The `margin` does not violate the natural _limits_ of the subject.
+. The element's {limits} is overridden to account for the additional space.
+. The `margin` does not violate the natural {limits} of the subject.
 `margin` will respect the subject's min-max constraints and resizability.
 . Returns instance of `Proxy`.
 
@@ -58,8 +58,8 @@ margin_left(left, subject)
 === Semantics
 
 . Space is added to the left of the subject with the given parameter.
-. The element's _limits_ is overridden to account for the additional space.
-. The `margin_left` does not violate the natural _limits_ of the subject.
+. The element's {limits} is overridden to account for the additional space.
+. The `margin_left` does not violate the natural {limits} of the subject.
 `margin_left` will respect the subject's min-max constraints and
 resizability.
 . Returns instance of `Proxy`.
@@ -87,8 +87,8 @@ margin_right(right, subject)
 === Semantics
 
 . Space is added to the right of the subject with the given parameter.
-. The element's _limits_ is overridden to account for the additional space.
-. The `margin_right` does not violate the natural _limits_ of the subject.
+. The element's {limits} is overridden to account for the additional space.
+. The `margin_right` does not violate the natural {limits} of the subject.
 `margin_right` will respect the subject's min-max constraints and
 resizability.
 . Returns instance of `Proxy`.
@@ -116,8 +116,8 @@ margin_top(top, subject)
 === Semantics
 
 . Space is added to the top of the subject with the given parameter.
-. The element's _limits_ is overridden to account for the additional space.
-. The `margin_top` does not violate the natural _limits_ of the subject.
+. The element's {limits} is overridden to account for the additional space.
+. The `margin_top` does not violate the natural {limits} of the subject.
 `margin_top` will respect the subject's min-max constraints and
 resizability.
 . Returns instance of `Proxy`.
@@ -146,8 +146,8 @@ margin_bottom(bottom, subject)
 
 . Space is added to the to the bottom of the subject with the given
 parameter.
-. The element's _limits_ is overridden to account for the additional space.
-. The `margin_bottom` does not violate the natural _limits_ of the subject.
+. The element's {limits} is overridden to account for the additional space.
+. The `margin_bottom` does not violate the natural {limits} of the subject.
 `margin_bottom` will respect the subject's min-max constraints and
 resizability.
 . Returns instance of `Proxy`.
@@ -186,8 +186,8 @@ margin_left_right(left, right, subject)
 
 . Space is added to the to the left and right sides of the subject with the
 given parameters.
-. The element's _limits_ is overridden to account for the additional space.
-. The `hmargin` (and variants) does not violate the natural _limits_ of the
+. The element's {limits} is overridden to account for the additional space.
+. The `hmargin` (and variants) does not violate the natural {limits} of the
 subject. `hmargin` (and variants) will respect the subject's min-max
 constraints and resizability.
 . Returns instance of `Proxy`.
@@ -228,8 +228,8 @@ margin_top_bottom(top, bottom, subject)
 
 . Space is added to the to the top and bottom sides of the subject with the
 given parameters.
-. The element's _limits_ is overridden to account for the additional space.
-. The `vmargin` (and variants) does not violate the natural _limits_ of the
+. The element's {limits} is overridden to account for the additional space.
+. The `vmargin` (and variants) does not violate the natural {limits} of the
 subject. `vmargin` (and variants) will respect the subject's min-max
 constraints and resizability.
 . Returns instance of `Proxy`.
@@ -262,8 +262,8 @@ margin_left_top(left, top, subject)
 
 . Space is added to the to the left and top sides of the subject with the
 given parameters.
-. The element's _limits_ is overridden to account for the additional space.
-. The `margin_left_top` (and variant) does not violate the natural _limits_
+. The element's {limits} is overridden to account for the additional space.
+. The `margin_left_top` (and variant) does not violate the natural {limits}
 of the subject. `margin_left_top` (and variant) will respect the subject's
 min-max constraints and resizability.
 . Returns instance of `Proxy`.
@@ -296,9 +296,9 @@ margin_left_bottom(left, bottom, subject)
 
 . Space is added to the to the left and bottom sides of the subject with the
 given parameters.
-. The element's _limits_ is overridden to account for the additional space.
+. The element's {limits} is overridden to account for the additional space.
 . The `margin_left_bottom` (and variant) does not violate the natural
-_limits_ of the subject. `margin_left_bottom` (and variant) will respect
+{limits} of the subject. `margin_left_bottom` (and variant) will respect
 the subject's min-max constraints and resizability.
 . Returns instance of `Proxy`.
 
@@ -330,8 +330,8 @@ margin_right_top(right, top, subject)
 
 . Space is added to the to the right and top sides of the subject with the
 given parameters.
-. The element's _limits_ is overridden to account for the additional space.
-. The `margin_right_top` (and variant) does not violate the natural _limits_
+. The element's {limits} is overridden to account for the additional space.
+. The `margin_right_top` (and variant) does not violate the natural {limits}
 of the subject. `margin_right_top` (and variant) will respect the
 subject's min-max constraints and resizability.
 . Returns instance of `Proxy`.
@@ -364,7 +364,7 @@ margin_right_bottom(right, bottom, subject)
 
 . Space is added to the to the right and bottom sides of the subject with the
 given parameters.
-. The element's _limits_ is overridden to account for the additional space.
+. The element's {limits} is overridden to account for the additional space.
 . The `margin_right_bottom` (and variant) does not violate the natural
 limits of the subject. `margin_right_bottom` (and variant) will respect
 the subject's min-max constraints and resizability.

docs/modules/ROOT/pages/layout/size_elements.adoc

@@ -5,7 +5,7 @@ include::../common.adoc[]
 
 == Overview
 
-Size elements override the _limits_ of an enclosed element. There is a
+Size elements override the {limits} of an enclosed element. There is a
 comprehensive list of size related elements in the Elements Library that can
 be used for various purposes. This section catalogues all the available size
 elements.
@@ -14,11 +14,11 @@ elements.
 
 image::/layout/limit.svg[alt="limit", width=360px, role=center]
 
-Overrides the _limits_ of an element.
+Overrides the {limits} of an element.
 
 === Notation
 
-`limits`    :: Instance of <<view_limits,`view_limits`>>
+`limits`    :: Instance of {view_limits}
 `subject`   :: Instance of `Element`
 
 === Expression
@@ -30,8 +30,8 @@ limit(limits, subject)
 
 === Semantics
 
-. The _limits_ of `subject` will be set to the specified `limits`
-constrained by the natural _limits_ of the `subject` (the natural _limits_
+. The {limits} of `subject` will be set to the specified {limits}
+constrained by the natural {limits} of the `subject` (the natural {limits}
 of the element will not be violated).
 . Returns instance of `Proxy`.
 
@@ -56,7 +56,7 @@ fixed_size({width, height}, subject)
 === Semantics
 
 . `subject` will be laid out with a fixed `width` and `height`, constrained
-by the natural _limits_ of the `subject` (the natural _limits_ of the
+by the natural {limits} of the `subject` (the natural {limits} of the
 element will not be violated).
 . Returns instance of `Proxy`.
 

docs/modules/ROOT/pages/layout/tiles.adoc

@@ -8,7 +8,7 @@ Tiles are the most useful layout elements. Tiles are used everywhere for
 composing hierarchical elements in rows and columns, typical to all GUIs.
 Tiles allow elements to fluidly adjust depending on available space. Tiles
 compute the layout of its elements using the children elements' size
-`limits`.
+{limits}.
 
 == Horizontal Tiles
 
@@ -22,7 +22,7 @@ available space.
 . The elements are laid out in a single row, left to right, immediately next
 to each other with no intervening space.
 . The elements are positioned horizontally using the children's natural
-_limits_.
+{limits}.
 . Horizontal space is allocated using this algorithm:
  .. Space is allocated for each child element following the child's natural
 _minimum horizontal limit_.
@@ -34,7 +34,7 @@ to it according to the element's `stretch()` member function. A stretch
 value of `1.0` is default. A stretchiness value of 2.0 means that the
 element is able to stretch twice as much compared to its siblings.
 Horizontally fixed-sized elements will not be stretched (element d in
-the diagram). (Also see {stretch-elements}).
+the diagram). (Also see {Stretch-Elements}).
 . The tile's _minimum vertical limit_ is computed as the maximum of the
 children elements' __minimum vertical limit__s.
 . The grid's _maximum vertical limit_ is computed as the minimum of the
@@ -130,7 +130,7 @@ available space.
 . The elements are laid out in a single column, top to bottom, immediately
 next to each other with no intervening space.
 . The elements are positioned vertically using the children's natural
-_limits_.
+{limits}.
 . Vertical space is allocated using this algorithm:
  .. Space is allocated for each child element following the child's natural
 _minimum vertical limit_.
@@ -142,7 +142,7 @@ to it according to the element's `stretch()` member function. A stretch
 value of `1.0` is default. A stretchiness value of 2.0 means that the
 element is able to stretch twice as much compared to its siblings.
 Vertically fixed-sized elements will not be stretched (element b in the
-diagram). (Also see {stretch-elements}).
+diagram). (Also see {Stretch-Elements}).
 . The tile's _minimum horizontal limit_ is computed as the maximum of the
 children elements' __minimum horizontal limit__s.
 . The grid's _maximum horizontal limit_ is computed as the minumum of the