updates to transportation schema concepts

docs/schema/concepts/by-theme/transportation/index.mdx

@@ -1,28 +1,39 @@
 ---
+description: Understanding schema concepts
 title: Transportation
 ---
+
 ## Overview
 The Overture transportation theme is the collection of features and properties that describe the infrastructure and conventions of how people and objects travel around the world. Transportation data includes highways, footways, cycleways, railways, ferry routes, and public transportation.
 
 ## Feature types
-The transportation theme has two feature types.
-- `segment` is a feature type with LineString geometry that represents the center-line of a path that a person or object may travel. Segment properties describe both the physical attributes (e.g. road surface and width) and non-physical attributes (e.g. access restriction rules) of that path
-- `connector` is a feature type with Point geometry that defines the topology of the transportation network by representing the physical connection between two or more segments. Apart from their Point geometry and the core properties required for all Overture features, connectors do not have any other properties
+
+The transportation theme has two feature types. The `segment` type has a LineString geometry that represents the center-line of a path that a person or object may travel. Segment properties describe both the physical attributes (e.g. road surface and width) and non-physical attributes (e.g. access restriction rules) of that path. The `connector` type has a Point geometry that defines the topology of the transportation network by representing the physical connection between two or more segments. Connectors do not have properties beyond geometry the core properties required for all Overture features.
 
 ## Theme concepts
-- **[Roads:](/schema/concepts/by-theme/transportation/roads)** the transportation theme schema models any kind of road, street or
-path, including dedicated walking and cycling paths, as `road` segments Roads are currently the most developed part of the transportation schema. 
-- **[Scoped and rule-based properties:](/schema/concepts/scoping-rules)** the transportation theme schema allows property values to be specified for granular scopes at the sub-feature level. For example:
+
+### [Roads](/schema/concepts/by-theme/transportation/roads)
+The Overture schema models any kind of road, street or path, including dedicated walking and cycling paths, as `road` segments. Roads are currently the most developed part of the transportation schema. 
+
+### [Scoped and rule-based properties](/schema/concepts/scoping-rules)
+The schema allows property values to be specified for granular scopes at the sub-feature level. For example:
  - a speed limit on a road segment might be scoped to apply only to part of the road geometry using _geometric scoping_
  - the directionality of a segment, controlling the direction or directions in which traffic can flow along the segment geometry, may be specified to change at different times of day using _temporal scoping_.
  - the categories of people and vehicles who are allowed to travel on a segment can be controlled using _subjective scoping_
  - a real world property that varies under changing environmental conditions can be modeled using _environmental scoping_
-- **[Shape and connectivity:](/schema/concepts/by-theme/transportation/shape-connectivity)** the transportation theme schema captures the shape
-and connectivity of the transportation network using `segment` and `connector` features. The schema design allows the segmentation process to promote shape stability and ultimately feature ID stability 
-- **[Travel modes:](/schema/concepts/by-theme/transportation/travel-modes)** the transportation theme supports a fuzzy concept called
+
+### [Shape and connectivity:](/schema/concepts/by-theme/transportation/shape-connectivity)
+The schema captures the shape and connectivity of the transportation network using `segment` and `connector` features. The schema design allows the segmentation process to promote shape stability and ultimately feature ID stability. 
+
+### [Linear referencing](/schema/concepts/by-theme/transportation/linear-referencing)
+
+### [Travel modes](/schema/concepts/by-theme/transportation/travel-modes)
+The transportation theme supports a fuzzy concept called
 travel mode which can be used as a way of controlling scoped
 and rule-based properties 
 
+### [Routes and destinations](/schema/concepts/by-theme/transportation/routes-destinations)
+
 
 ## Schema reference
 - [Connector feature type](/schema/reference/transportation/connector)

docs/schema/concepts/by-theme/transportation/linear-referencing.mdx

@@ -1,4 +1,100 @@
 ---
 title: Linear referencing
 draft: true
----
+---
+
+
+Linear referencing, also known as [geometric scoping](https://docs.overturemaps.org/schema/concepts/scoping-rules), is a key concept in the transportation schema. 
+
+<Tabs>
+ <TabItem value="description" label="Description" default>
+
+The geometric scoping properties `at` and `between` limit the scope of their parent value to a position or range of positions, respectively, along a segment's geometry. When the parent value is a rule object, the rule only matches the position or range of positions specified in the `at` or `between` property.
+
+The value of the `at` property is a single real number `a` where `0` &le; `a`
+&le; `1`. It represents a discrete position along the segment's geometry. The
+value of the `between` property is a pair of numbers `[a, b]` where `0` &le;
+`a` &lt; `b` &le; `1`. It represents a range of positions along the segment's
+geometry. The numbers `a` and `b` are interpreted as percentage displacements
+along the parent segment's geometry starting from the start of the segment.
+(*The terms "start" and "end" are explained in
+[Shape and connectivity](https://docs.overturemaps.org/schema/concepts/by-theme/transportation/shape-connectivity).*) 
+
+So, for example, the scoping property `"at": 0.15` scopes its parent value
+to the position on the segment that is displaced 15% of the segment length from
+the start.
+
+<div style={{textAlign: 'center'}}>
+
+<figure>
+
+<ThemedImage
+ alt="Diagram showing a single geometrically-scoped position"
+ sources={{
+ light: useBaseUrl('/img/transportation/geometric-scoping-position-light.svg'),
+ dark: useBaseUrl('/img/transportation/geometric-scoping-position-dark.svg'),
+ }}
+/>
+
+<figcaption>
+
+<div style={{textAlign: 'center'}}>
+
+*The position along the segment geometry described by `"at": 0.15`.*
+
+</div>
+
+</figcaption>
+</figure>
+
+</div>
+
+The scoping property `"between": [0.35, 0.75]` scopes its parent value to the
+range of positions on the segment beginning at 35% and extending to 75% of the
+segment length from the start.
+
+<div style={{textAlign: 'center'}}>
+
+<figure>
+
+<ThemedImage
+ alt="Diagram showing a geometrically-scoped range"
+ sources={{
+ light: useBaseUrl('/img/transportation/geometric-scoping-range-light.svg'),
+ dark: useBaseUrl('/img/transportation/geometric-scoping-range-dark.svg'),
+ }}
+/>
+
+<figcaption>
+
+<div style={{textAlign: 'center'}}>
+
+*The range on the segment geometry described by `"between": [0.35, 0.75]`.*
+
+</div>
+
+</figcaption>
+</figure>
+
+</div>
+
+ </TabItem>
+ <TabItem value="example" label="Example" default>
+
+The example below shows a road segment whose speed limit is defined by
+two geometrically-scoped speed limit rules:
+
+<CodeBlock language="yaml">{ ExampleGeometricScoping }</CodeBlock>
+
+ </TabItem>
+</Tabs>
+
+## Linear referencing
+https://docs.overturemaps.org/schema/attributes/transportation/shape-connectivity/#geometric-scoping
+https://docs.overturemaps.org/schema/attributes/scoping-rules/ 
+
+
+## Segment subclasses
+Flexible, linearly-referenceable attributes which refine the class value
+Patterned after OSM’s subtags, including service, footway and cycleway
+Critical to resolve merged details of pedestrian networks, particularly for adjacent sidewalk and crosswalks

docs/schema/concepts/by-theme/transportation/routes-destinations.mdx

@@ -1,4 +1,14 @@
 ---
 title: Routes and destinations
 draft: true
----
+---
+
+import ThemedImage from '@theme/ThemedImage';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+## Routes 
+Route relations link multiple road segments together to form higher level and continuous groupings. This enables use cases like improved rendering at low zooms, display of "highway shields", improved road naming and general road relationships/importance even as individual segments are resegmented and reclassified.
+
+
+## Destinations
+Captures signs which indicate a specific transition from one segment to another will result in arriving at the specified location. Also known as “follow signs for” in turn-by-turn.

docs/schema/concepts/by-theme/transportation/shape-connectivity.mdx

@@ -5,7 +5,6 @@ title: Shape and connectivity
 import ThemedImage from '@theme/ThemedImage';
 import useBaseUrl from '@docusaurus/useBaseUrl';
 
-# Shape and connectivity
 
 The Overture transportation theme captures the physical shape and connectivity
 of the transportation network through the interaction of the theme's two feature

docs/schema/concepts/cartography.mdx

@@ -2,8 +2,7 @@
 title: Cartography
 ---
 
-Cartographic suggestions
-===
+
 
 import JSONSchemaViewer from "@theme/JSONSchemaViewer";
 import generateResolverOptions from "@site/src/components/shared-libs/generateResolverOptions"

docs/schema/concepts/scoping-rules.mdx

@@ -1,5 +1,5 @@
 ---
-title: Scoping rules
+title: Scoping Rules
 ---
 
 
@@ -53,7 +53,90 @@ value of the `between` property is a pair of numbers `[a, b]` where `0` ≤
 geometry. The numbers `a` and `b` are interpreted as percentage displacements
 along the parent segment's geometry starting from the start of the segment.
 (*The terms "start" and "end" are explained in
-[Shape and connectivity](https://docs.overturemaps.org/guides/transportation/shape-connectivity).*) 
+[Shape and connectivity]#### Geometric scoping (linear referencing)
+
+<Tabs>
+ <TabItem value="description" label="Description" default>
+
+The geometric scoping properties `at` and `between` limit the scope of their parent value to a position or range of positions, respectively, along a segment's geometry. When the parent value is a rule object, the rule only matches the position or range of positions specified in the `at` or `between` property.
+
+The value of the `at` property is a single real number `a` where `0` &le; `a`
+&le; `1`. It represents a discrete position along the segment's geometry. The
+value of the `between` property is a pair of numbers `[a, b]` where `0` &le;
+`a` &lt; `b` &le; `1`. It represents a range of positions along the segment's
+geometry. The numbers `a` and `b` are interpreted as percentage displacements
+along the parent segment's geometry starting from the start of the segment.
+(*The terms "start" and "end" are explained in
+[Shape and connectivity](https://docs.overturemaps.org/schema/concepts/by-theme/transportation/shape-connectivity).*) 
+
+So, for example, the scoping property `"at": 0.15` scopes its parent value
+to the position on the segment that is displaced 15% of the segment length from
+the start.
+
+<div style={{textAlign: 'center'}}>
+
+<figure>
+
+<ThemedImage
+ alt="Diagram showing a single geometrically-scoped position"
+ sources={{
+ light: useBaseUrl('/img/transportation/geometric-scoping-position-light.svg'),
+ dark: useBaseUrl('/img/transportation/geometric-scoping-position-dark.svg'),
+ }}
+/>
+
+<figcaption>
+
+<div style={{textAlign: 'center'}}>
+
+*The position along the segment geometry described by `"at": 0.15`.*
+
+</div>
+
+</figcaption>
+</figure>
+
+</div>
+
+The scoping property `"between": [0.35, 0.75]` scopes its parent value to the
+range of positions on the segment beginning at 35% and extending to 75% of the
+segment length from the start.
+
+<div style={{textAlign: 'center'}}>
+
+<figure>
+
+<ThemedImage
+ alt="Diagram showing a geometrically-scoped range"
+ sources={{
+ light: useBaseUrl('/img/transportation/geometric-scoping-range-light.svg'),
+ dark: useBaseUrl('/img/transportation/geometric-scoping-range-dark.svg'),
+ }}
+/>
+
+<figcaption>
+
+<div style={{textAlign: 'center'}}>
+
+*The range on the segment geometry described by `"between": [0.35, 0.75]`.*
+
+</div>
+
+</figcaption>
+</figure>
+
+</div>
+
+ </TabItem>
+ <TabItem value="example" label="Example" default>
+
+The example below shows a road segment whose speed limit is defined by
+two geometrically-scoped speed limit rules:
+
+<CodeBlock language="yaml">{ ExampleGeometricScoping }</CodeBlock>
+
+ </TabItem>
+</Tabs>.*) 
 
 So, for example, the scoping property `"at": 0.15` scopes its parent value
 to the position on the segment that is displaced 15% of the segment length from