TIME Notation and Metadata for Compact Time Recording

[evelyn]

This proposal introduces a new TIME notation for recording the duration of a performance in Traindown, along with additional metadata keys for capturing overall session duration and other time-based training details. The TIME token and related metadata keys are designed to be compact, clear, and consistent with existing Traindown conventions, enhancing the language's expressiveness and utility while keeping notes succinct and portable.

Rationale

The current Traindown specification provides a flexible method for recording training sessions but lacks standardized ways to succinctly record performance durations and overall session timing. This proposal introduces the TIME token for individual performance durations and additional metadata keys like Duration, Rest, Warmup, Cooldown, Interval, Pace, Recovery, and Pause to capture important details relevant to time-based training. The focus remains on keeping the notes portable and concise, aligning with Traindown’s core philosophy.

TIME Notation Specification

Syntax

LOAD [REPS] [SETS] [TIME] [FAILS]

• LOAD: The load or weight used (e.g., weight in lbs or kg, or bw for body weight).
• REPS: Optional reps token.
• SETS: Optional sets token.
• TIME: Optional time token. (A token used to indicate the duration of a performance.)
• FAILS: Optional failures token.

TIME Token Format

TIME @Hh:Mm:Ss

• @Hh:Mm:Ss: A compact format for recording time.
  • Hh: Hours, optional. May be one or more digits.
  • Mm: Minutes, required if hours are used. Must be two digits if hours are used.
  • Ss: Seconds, required if minutes are present. Must be two digits if minutes are used (e.g., 05 for 5 seconds).
  • No Spaces: There should be no spaces within the @Hh:Mm:Ss token itself.

Compact and Context-Aware Notation

• Minutes and Seconds: Format as Mm:Ss if time is under 1 hour (e.g., 8:00 for 8 minutes).
• Seconds Only: Format as Ss if time is under 1 minute (e.g., 45 for 45 seconds).
• Hours, Minutes, and Seconds: Use Hh:Mm:Ss if hours are included (e.g., 1:15:00 for 1 hour and 15 minutes).

Contextual Use of @ Symbol

Existing Usage:

• Session-Level @ Symbol:
  • The @ symbol is currently used at the session level to mark the start of a session with the date and/or time when the training session occurred. For example:

    @ 2024-08-19 06:00am
    

  • This usage is distinct and appears at the beginning of a session entry, serving to timestamp the session as a whole.

Proposed Usage:

• Performance-Level @ Symbol:
  • The @ symbol is proposed to be used within the TIME token at the performance level, following SETS and before FAILS, to indicate the duration of that specific performance. For example:

    Squat:
      225 5r 3s @2:00
    

  • This usage is embedded within a performance entry, ensuring it is contextually separated from the session-level @.

How TIME is Interpreted

In the example:

Squat:
  225 5r 3s @2:00

• 225: The load used, which is 225 pounds.
• 5r: Denotes that each set consisted of 5 repetitions.
• 3s: Indicates that the exercise was performed for 3 sets.
• @2:00: Indicates that each set took 2 minutes to perform. This 2-minute duration includes the time taken to complete all 5 repetitions within that set.

This structure keeps the core components of the workout (load, reps, sets) together before introducing the performance-specific details like duration, making the overall entry more readable and logically consistent.

Ensuring Clarity and Avoiding Conflicts

1. Contextual Clarity:

   • The @ symbol at the session level is always used at the start of a session, whereas the TIME token using @ appears within performance entries. The contextual difference ensures that the two usages are not confused.

2. No Overlap:

   • The session-level @ symbol is placed at the top of the session, while the TIME token with @ is embedded within performance entries. There should be no scenario where these two uses conflict.

3. Documentation and Specification:

   • The specification should clearly define the dual-purpose use of the @ symbol:
     • Session-Level: Used to mark the start of a session and timestamp it.
     • Performance-Level: Used within the TIME token to record the duration of a specific performance.
   • Example:

     The `@` symbol is utilized in two distinct contexts within Traindown:
     - **Session-Level**: Placed at the start of a session to record the date and/or time.
     - **Performance-Level**: Embedded within the `TIME` token, following `SETS`, to record the duration of a performance.
     

Additional Metadata for Time-Based Training

Duration Metadata Key

• Key Name: Duration
• Purpose: To record the overall duration of the entire session.
• Format: Follows the @Hh:Mm:Ss format.

Rest Metadata Key

• Key Name: Rest
• Purpose: To specify the rest time between sets or exercises within a session.
• Format: Follows the @Hh:Mm:Ss format.

Warmup Metadata Key

• Key Name: Warmup
• Purpose: To specify the duration of the warm-up phase before the main workout.
• Format: Follows the @Hh:Mm:Ss format.

Cooldown Metadata Key

• Key Name: Cooldown
• Purpose: To specify the duration of the cooldown phase after the main workout.
• Format: Follows the @Hh:Mm:Ss format.

Interval Metadata Key

• Key Name: Interval
• Purpose: To specify the duration of intervals within interval-based training sessions.
• Format: Follows the @Hh:Mm:Ss format.

Pace Metadata Key

• Key Name: Pace
• Purpose: To specify the pace of a particular movement or exercise, commonly used in activities like running, cycling, or swimming where pace tracking is essential.
• Format: Follows the @Hh:Mm:Ss format with a unit of distance.

Usage Examples:

1. Running Pace (per mile):

   # Pace: @8:00 per mile
   

   • Explanation: Indicates a pace of 8 minutes per mile.

2. Cycling Pace:

   # Pace: @1:15:00 per 20 miles
   

   • Explanation: Indicates a pace of 1 hour and 15 minutes to cover 20 miles.

3. Swimming Pace (per 100 meters):

   # Pace: @2:30 per 100 meters
   

   • Explanation: Indicates a pace of 2 minutes and 30 seconds per 100 meters.

Recovery Metadata Key

• Key Name: Recovery
• Purpose: To specify the recovery time between intervals or sets, particularly in high-intensity interval training (HIIT).
• Format: Follows the @Hh:Mm:Ss format.

Pause Metadata Key

• Key Name: Pause
• Purpose: To specify the duration of pauses between repetitions or sets, particularly useful in strength training.
• Format: Follows the @Hh:Mm:Ss format.

Expanded Usage Examples

Example 1: Strength Training with Exercise-Specific Metadata

@ 2024-08-19 06:00am

Squat:
  225 5r 3s @2:00
  # Rest: @1:30
  # Depth: below parallel
  # Bar Position: high bar

Bench:
  185 5r 3s @1:30
  # Rest: @2:00
  # Grip: medium
  # Tempo: @2 down, @1 pause, @1 up

Deadlift:
  315 5r 1s @3:00
  # Rest: @3:00
  # Stance: shoulder-width
  # Grip: overhand
  # Tempo: @2 lift, @2 lower

• Squat: 3 sets of 5 reps at 225 pounds, each set taking 2 minutes with a rest of 1 minute and 30 seconds between sets. Specific metadata notes that the squat depth is below parallel, and the bar position is high bar.
• Bench: 3 sets of 5 reps at 185 pounds, each set taking 1 minute and 30 seconds with a rest of 2 minutes. The tempo for the bench press includes 2 seconds down, 1-second pause, and 1 second up, using @ notation for clarity.
• Deadlift: 1 set of 5 reps at 315 pounds, taking 3 minutes. The tempo for the deadlift includes 2 seconds to lift and 2 seconds to lower, with additional metadata specifying a shoulder-width stance and an overhand grip.

Example 2: Running Session with Sparse Session Metadata

@ 2024-08-20 07:00am

# Duration: @1:00:00
# Rest: @45

Warmup:
  bw @10:00
  # Activity: dynamic stretches

Jog:
  bw 3mi @25:00
  # Pace: @8:20 per mile
  # Terrain: hilly

Intervals:
  bw 5r @1:00
  # Pace: @6:00 per mile
  # Rest: @1:30

Cooldown:
  bw @5:00
  # Activity: light jog and stretches

• Warmup: A 10-minute warm-up with dynamic stretches.
• Jog: A 3-mile jog completed in 25 minutes, with a pace of 8 minutes and 20 seconds per mile, noting that the terrain was hilly.
• Intervals: 5 repetitions of 1-minute runs at a pace of 6 minutes per mile, with 1 minute and 30 seconds of rest between intervals.
• Cooldown: A 5-minute cooldown consisting of a light jog and stretches.

Example 3: Swimming Session with Interval Training

@ 2024-08-21 06:30am

# Duration: @45:00

Warmup:
  bw @5:00
  # Activity: freestyle easy pace

Swim:
  100m 5r 4s @2:30
  # Stroke: freestyle
  # Rest: @1:00

Intervals:
  50m 10r @1:00
  # Stroke: butterfly
  # Rest: @0:45

Cooldown:
  bw @5:00
  # Activity: backstroke easy pace

• Warmup: A 5-minute warm-up with freestyle swimming at an easy pace.
• Swim: 4 sets of 5 repetitions of 100 meters, each set taking 2 minutes and 30 seconds, with a 1-minute rest between sets. The stroke used is freestyle.
• Intervals: 10 repetitions of 50 meters, each taking 1 minute with 45 seconds of rest between intervals. The stroke used is butterfly.
• Cooldown: A 5-minute cooldown with backstroke swimming at an easy pace.

Example 4: Circuit Training with Varied Exercises and Time Notations

@ 2024-08-22 06:45am

# Duration: @1:15:00

Warmup:
  bw @15:00
  # Activity: jump rope, dynamic stretches

Circuit:
  Push-ups:
    bw 20r 3s @30
    # Tempo: @2 down, @1 hold, @1 up

  Kettlebell Swings:
    24kg 15r 3s @45
    # Rest: @1:00
    # Tempo: @1 swing, @2 down

  Plank:
    bw 3s @1:00
    # Rest: @0:30
    # Form: elbows on mat, straight body line

Cooldown:
  bw @10:00
  # Activity: walking and static stretches

• Warmup: A 15-minute warm-up involving jump rope and dynamic stretches.
• Push-ups: 3 sets of 20 reps, each set taking 30 seconds. The tempo for push-ups includes 2 seconds down, 1-second hold, and 1 second up.
• Kettlebell Swings: 3 sets of 15 reps with a 24kg kettlebell, each set taking 45 seconds with a rest of 1 minute between sets. The tempo for the swings is 1 second per swing and 2 seconds to lower.
• Plank: 3 sets of planks held for 1 minute each, with 30 seconds of rest between sets. The form is noted as elbows on the mat and a straight body line.
• Cooldown: A 10-minute cooldown involving walking and static stretches.

Example 5: Military Fitness Test

@ 2024-08-23 05:00am

# Duration: @45:57

Warmup:
  bw @10:00
  # Activity: dynamic stretches, light jogging

Hand-Release Push-Ups:
  bw 56 @2:00
  # Tempo: @1 down, @1 up
  # Form: hands fully released at bottom

Cross Leg Reverse Crunches:
  bw 46 @2:00
  # Tempo: @2 up, @2 down
  # Form: cross legs, engage core, slow and controlled

Run:
  bw 1.5mi @12:31
  # Pace: @8:20 per mile
  # Terrain: flat

• Warmup: A 10-minute warm-up including dynamic stretches and light jogging.
• Hand-Release Push-Ups: 56 hand-release push-ups performed in 2 minutes. The tempo is 1 second down, 1 second up, with a full hand release at the bottom of each rep.
• Cross Leg Reverse Crunches: 46 cross leg reverse crunches performed in 2 minutes. The tempo is 2 seconds up, 2 seconds down, with emphasis on slow and controlled movements.
• Run: A 1.5-mile run completed in 12 minutes and 31 seconds, with a pace of 8 minutes and 20 seconds per mile on a flat terrain.

Benefits of the Duration, Rest, Pace, Pause, and Other Time-Based Metadata Keys:

1. Comprehensive Tracking:

   • These keys allow users to log every phase of their workout, from warm-up to cooldown, and everything in between, providing a complete picture of the session.

2. Flexibility:

   • Users can choose which keys are relevant to their specific training regimen, making the system adaptable to various types of workouts.

3. Consistency and Succinctness:

   • The use of a consistent @Hh:Mm:Ss format across different time-related keys ensures clarity, while the correct application of time entries supports portability and succinctness.

Conclusion

The introduction of the TIME token and related metadata keys like Duration, Rest, Warmup, Cooldown, Interval, Pace, Recovery, and Pause enhances the Traindown language by providing a clear, concise, and consistent method for recording various time-related aspects of training sessions. This proposal maintains the minimalist ethos of Traindown while offering users additional flexibility and precision in documenting their training sessions.

[scottt2]

@evelyn Holy cow this is such a well thought out proposal! I am so grateful for the time you put into this. I think this would be a great addition to Traindown especially for the "density" use case--i.e., weight over time, etc. I want to digest a bit more and then figure out what an implementation may look like.