Clarify providing TUs for modified trips and ReplacementStop time int…

…erpolation

gtfs-realtime/spec/en/reference.md

@@ -572,7 +572,7 @@ Describes the physical path that a vehicle takes when the shape is not part of t
 
 ## _message_ Stop
 
-Represent a new Stop added to the feed dynamically. All fields are as described in the (CSV) GTFS specification. Location type of the new stop is assumed to be `0` (routable stop). 
+Represents a new Stop added to the feed dynamically. All fields are as described in the (CSV) GTFS specification. The location type of the new stop is `0` (routable stop). 
 
 **Fields**
 
@@ -642,7 +642,7 @@ _Propagated detour delays affect all stops following the end of a modification.
 
 ## _message_ ReplacementStop
 
-Each `ReplacementStop` message acts as a template for generating a new stop time in each modified trip. 
+Each `ReplacementStop` message defines a stop that will now be visited by the trip, and optionally specifies the estimated travel time to the stop. 
 
 ![](images/first_stop_reference.png)
 _If a modification affects the first stop of the trip, that stop also serves as the reference stop of the modification._

gtfs-realtime/spec/en/trip-modifications.md

@@ -1,26 +1,32 @@
 # Trip Modifications
 
-A `TripModifications` message identifies a list of similar `trip_ids` from the (CSV) GTFS sharing the same stop pattern, which are all affected by a particular modification, such as a detour. 
+A `TripModifications` message identifies a list of similar `trip_ids` from the (CSV) GTFS sharing the same stop pattern, which are all affected by a particular modification, such as a detour.
 
 ## SLO: Service-level objective
 
-The frequency of data updates is expected to be approximately hourly (~24 times/day). Ingestion time may depend on the total number of affected trips. Consumers are expected to ingest a single TripModification within 5 minutes, and a feed with hundreds of detours within 20 minutes. 
+The frequency of data updates is expected to be approximately hourly (~24 times/day). Ingestion time may depend on the total number of affected trips. Consumers are expected to ingest a single TripModification within 5 minutes, and a feed with hundreds of detours within 20 minutes.
 
 ## TripModifications
 
-The modification is in effect on all of the listed service\_dates, until it is removed from the feed. On any given service date, a trip MUST NOT be assigned to more than one `TripModifications` object. 
+The modification is in effect on all of the listed service\_dates, until it is removed from the feed. On any given service date, a trip MUST NOT be assigned to more than one `TripModifications` object.
 
 There MAY be multiple `TripModifications` for a given stop pattern. It may be desirable to split the trips into multiple modifications e.g. if the `propagated_modification_delay` changes significantly, over the course of the detour.
 
-Each affected trip is deemed to be canceled and replaced with a new trip. The affected trip can be omitted from the feed while it is detoured.  Each replacement trip has an automatically generated ID and shares all of the properties defined in trips.txt for the affected trip it replaced. Replacement trip IDs can be used in the same way as any other trip\_id in GTFS-RT. For example, TripUpdates can be provided using the replacement trip ID.
+The trips created through GTFS-TripModifications modify and replace each specified `trip_id`, and don't create a copy or additional run.
 
-The stop times of each replacement trip are created from those of the affected trip, by performing the changes listed in modifications. Stop sequences are assigned from 1 to n, ignoring the stop\_sequence values of the affected stop times. If a particular stop time is not affected by the detour, all other values will match those originally defined in stop\_times.txt.
+The scheduled stop times of each replacement trip are created from those of the affected trip, by performing the changes listed in modifications. Stop sequences are assigned from 1 to n, increasing by 1 for each stop in the trip. A `TripUpdate` message must be provided to publish real-time arrival/departure times for the replacement trip.
+
+
+## Linkage to TripUpdates
+
+* A TripUpdate SHOULD be provided using the replacement trip ID (`modifications_id` + `_` + `trip_id`). The TripUpdate MAY provide an ETA at the replacement stops.
+* If no such TripUpdate is found, TripUpdates for the original `trip_id` will apply to the modified trip. In this case, no ETA is available at the replacement stops.
 
 ##  Modification
 
 A `Modification` message replaces a span of n stop times (`num_stops_replaced`) from each affected trip starting at `start_stop_sequence`. The spans of the modifications MUST not overlap. Spans may not be contiguous; in this case the two modifications MUST be merged into one.  These stop times are replaced with a new stop time for each replacement stop described by `replacement_stops`.
 
-The sequence of `replacement_stops` may be of arbitrary length. For example, 3 stops could be replaced by 2, 4, or 0 stops as the situation may require. 
+The sequence of `replacement_stops` may be of arbitrary length. For example, 3 stops could be replaced by 2, 4, or 0 stops as the situation may require.
 
 ![](images/trip_modification.png)
 _An example showing the effect of a modification on a particular trip. This modification may also be applied to several other trips._
@@ -30,8 +36,12 @@ _Propagated detour delays affect all stops following the end of a modification.
 
 ## ReplacementStop
 
-Each `ReplacementStop` message acts as a template for generating a new stop time in each modified trip. The generated stop time will have the specified `stop_id`. 
-The `arrival_time` is calculated from a reference stop in the original trip, plus the offset in `travel_time_to_stop`. The `departure_time` always equals the `arrival_time`.
+Each `ReplacementStop` message defines a stop that will now be visited by the trip, and optionally specifies the estimated travel time to the stop. The `ReplacementStop` message is used to construct the scheduled `stop_time` for the stop.
+
+When `travel_time_to_stop` is specified, the `arrival_time` is calculated from a reference stop in the original trip, plus the offset in `travel_time_to_stop`. Otherwise, the `arrival_time` shall be interpolated based on the total duration of the modification in the original trip.
+
+The `departure_time` always equals the `arrival_time`.
+
 The optional fields of [`stop_times.txt`](https://github.com/google/transit/blob/master/gtfs/spec/en/reference.md#stop_timestxt) in the (CSV) GTFS specification are all set to their default values.
 
 ![](images/first_stop_reference.png)
@@ -43,5 +53,5 @@ Describes the physical path that a vehicle takes when the shape is not part of t
 
 ## Stop
 
-Represent a new Stop added to the feed dynamically. All fields are as described in the (CSV) GTFS specification. Location type of the new stop is assumed to be `0` (routable stop). 
+Represents a new Stop added to the feed dynamically. All fields are as described in the (CSV) GTFS specification. The location type of the new stop is `0` (routable stop).