programmatic scrolling: update documentation.

CHANGELOG.md

@@ -12,6 +12,11 @@ Although Moulti's Python packages, modules and functions are obviously available
 
 - `moulti set --step-position=bottom`
 - `moulti set --step-direction=up`
+- Programmatic scrolling:
+  - `moulti scroll step_id offset`
+  - `moulti step add --scroll-on-actvity=-1`
+  - `moulti step update --scroll-on-actvity=false`
+  - "Lock scroll" action to prevent programmatic scrolling
 
 ### Fixed
 

Documentation.md

@@ -439,6 +439,69 @@ last line<enter>
 
 ## Scrolling
 
+## Manually scrolling through steps
+
+You can scroll through steps:
+- by grabbing the main scrollbar handle using the mouse pointer;
+- using the mouse wheel (or its laptop equivalent) -- tip: ensure the cursor is not over a scrollable step log part;
+- by hitting the `Up`, `PgUp`, `Home` or `End` key -- tip: ensure the focus is not held by a step log part.
+
+If necessary, hit `l` or click "L Lock scroll" in the footer to prevent programmatic scrolling from interfering with your actions.
+When this lock is enabled, the main scrollbar handle turns green.
+
+## Programmatically scrolling through steps
+
+### moulti scroll
+
+Use `moulti scroll step_name` to make Moulti scroll to a given step.
+If this step cannot be displayed entirely, `moulti scroll` will display its upper part.
+
+It is possible to define which line of the step should absolutely be displayed by specifying an offset as second argument.
+Important: here, a line does not mean a line of the text output shown by the chosen step but rather one of the lines that make up the entire chosen step on screen.
+
+```console
+# Ensure the first line of the step is displayed:
+moulti scroll step_name 0
+# Ensure the second line of the step is displayed:
+moulti scroll step_name 1
+# Ensure the third line of the step is displayed:
+moulti scroll step_name 2
+
+# Ensure the last line of the step is displayed:
+moulti scroll step_name -1
+# Ensure the second to last line of the step is displayed:
+moulti scroll step_name -2
+```
+
+It often makes sense to call `moulti scroll` after adding an interactive step (buttonquestion, inputquestion).
+
+### Scroll on activity
+
+Sometimes, it is desirable to make a step visible when a new line of output shows up.
+This can be achieved using `--scroll-on-activity`:
+
+```console
+# By default, steps do not scroll on activity:
+moulti step add foo --bottom-text=' ' --title='Your shiny title here'
+moulti pass foo <<< 'do not scroll'
+
+# Enable scroll on activity:
+moulti step update foo --scroll-on-activity=true
+# Try it:
+moulti pass foo --append <<< 'scroll!'
+
+# A typical use case is to ensure the last line of output is displayed:
+moulti step update foo --max-height=0 --scroll-on-activity=-1
+# Try it:
+yes 'scroll to the last line!' | nl -ba | head -500 | moulti pass foo --append
+
+# Disable scroll on activity:
+moulti step update foo --scroll-on-activity=false
+moulti pass foo --append <<< 'do not scroll!'
+```
+
+## Manually scrolling inside steps
+
 By default, Moulti strives to display the latest lines it received and thus keeps scrolling down as long as lines keep coming.
 This constant scrolling stops as soon as you scroll up:
 - using the mouse wheel (or its laptop equivalent);
@@ -447,6 +510,10 @@ This constant scrolling stops as soon as you scroll up:
 
 The constant scrolling resumes when you hit the `End` key.
 
+## Programmatically scrolling inside steps
+
+Moulti currently offers no suport for programmatic scrolling inside steps.
+
 ## Environment variables
 
 ### Environment variables you may set

README.md

@@ -31,7 +31,9 @@ As shown in the demo, Moulti enables user interactions through **questions**:
 
 ![Moulti button question](https://xavier.kindwolf.org/p/moulti/doc/img/moulti-button-question.png?20240218)
 
-Moulti also features a **progress bar**: [documentation](Documentation.md#progress-bar)
+Moulti also features:
+- a **progress bar**: [documentation](Documentation.md#progress-bar)
+- programmatic scrolling: [documentation](Documentation.md#programmatically-scrolling-through-steps)
 
 When it comes to look and feel, Moulti can be customised: