From a8f866e4795abb3e7842a5750d60c7c0593a472a Mon Sep 17 00:00:00 2001
From: Alexander Medvednikov <alexander@medvednikov.com>
Date: Sun, 24 May 2026 16:07:48 +0300
Subject: [PATCH] term: fix misleading example in README (fix #27120) (#27229)

---
 vlib/term/README.md | 70 ++++++++++++++++++++++++++++++++++-----------
 1 file changed, 54 insertions(+), 16 deletions(-)

diff --git a/vlib/term/README.md b/vlib/term/README.md
index 891fa5dff..ae5971a19 100644
--- a/vlib/term/README.md
+++ b/vlib/term/README.md
@@ -41,42 +41,80 @@ This simple program covers many of the principal aspects of the `term ` module.
 
 ## API
 
-Here are some of the main functions of the `term `module:
+Here are some of the main functions of the `term` module. Note that the
+coloring/styling functions like `ok_message`, `yellow`, `bold`, etc., do
+*not* print anything by themselves — they return a new string with ANSI
+escape codes embedded, which you can then pass to `println` (or similar)
+to actually display the styled text on stdout.
 
 ```v
 import term
+import os
 
 // returns the height and the width of the terminal
 width, height := term.get_terminal_size()
-println('width: ${width}, height: ${height}')
-// returns the string as green text to be printed on stdout
-term.ok_message('cool')
-// returns the string as red text to be printed on stdout
-term.fail_message('oh, no')
-// returns the string as yellow text to be printed on stdout
-term.warn_message('be warned')
-// clears the entire terminal and leaves a blank one
+println('terminal dimensions: width: ${width} height: ${height}')
+
+mut output := ''
+
+// returns the string as green text
+output = 'ok_message() text ' + term.ok_message('is green')
+println(output)
+
+// returns the string as red text
+output = 'fail_message() text ' + term.fail_message('is red')
+println(output)
+
+// returns the string as yellow text
+output = 'warn_message() text ' + term.warn_message('is yellow')
+println(output)
+
+os.input('hit Enter to clear the console and continue')
+
+// clears the entire terminal
 term.clear()
 
-// Set the color output of the output.
+// Set the color output of the text.
 // The available colors are:
 // black, white, blue, yellow,
 // green, red, cyan, magenta,
 // bright_black, bright_white, bright_blue, bright_yellow,
 // bright_green, bright_red, bright_cyan, bright_magenta,
-term.yellow('submarine')
+output = 'yellow() - ' + term.yellow('text')
+println(output)
 
 // transforms the given string into bold text
-term.bold('and beautiful')
+output = 'bold() - ' + term.bold('text')
+println(output)
+
 // puts a strikethrough into the given string
-term.strikethrough('the core of the problem')
+output = 'strikethrough() - ' + term.strikethrough('text')
+println(output)
+
 // underlines the given string
-term.underline('important')
+output = 'underline() - ' + term.underline('text')
+println(output)
+
 // colors the background of the output following the given color
 // the available colors are: black, blue, yellow, green, cyan, gray
-term.bg_green('field')
-// sets the position of the cursor at a given place in the terminal
+output = 'bg_green() - ' + term.bg_green('text')
+println(output)
+
+// sets the position of the cursor
 term.set_cursor_position(x: 5, y: 10)
+println('Cursor at (5,10)')
+
+// flashes (blinks) the text
+output = term.slow_blink('done')
+println(output)
+```
+
+The `term` module also provides several lower-level cursor-control
+helpers, which write directly to stdout:
+
+```v
+import term
+
 // moves the cursor up
 term.cursor_up(1)
 // moves the cursor down
-- 
2.39.5