From a63920da3911950dca83a0b64371b16e59153e56 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rodrigo=20Gir=C3=A3o=20Serr=C3=A3o?=
 <5621605+rodrigogiraoserrao@users.noreply.github.com>
Date: Tue, 20 Dec 2022 10:40:59 +0000
Subject: [PATCH] Complete height reference.

[skip ci]
---
 docs/styles/height.md | 41 +++++++++++++++++++++++++++++++++++++++--
 1 file changed, 39 insertions(+), 2 deletions(-)

diff --git a/docs/styles/height.md b/docs/styles/height.md
index 18622615d..d3ce3b8f0 100644
--- a/docs/styles/height.md
+++ b/docs/styles/height.md
@@ -8,7 +8,9 @@ The `height` rule sets a widget's height. By default, it sets the height of the
 height: <SCALAR>;
 ```
 
-## Example
+--8<-- "docs/styles/snippets/scalar_syntax.md"
+
+## Examples
 
 This examples creates a widget with a height of 50% of the screen.
 
@@ -29,6 +31,41 @@ This examples creates a widget with a height of 50% of the screen.
     ```{.textual path="docs/examples/styles/height.py"}
     ```
 
+The next example creates a series of wide widgets with heights set with different units.
+Open the CSS file tab to see the comments that explain how each height is computed.
+(The output includes a vertical ruler on the right to make it easier to check the height of each widget.)
+
+=== "Output"
+
+    ```{.textual path="docs/examples/styles/height_comparison.py" lines=24 columns=80}
+    ```
+
+=== "height_comparison.py"
+
+    ```py hl_lines="15-23"
+    --8<-- "docs/examples/styles/height_comparison.py"
+    ```
+
+    1. The id of the placeholder identifies which unit will be used to set the height of the widget.
+
+=== "height_comparison.css"
+
+    ```css hl_lines="2 5 8 11 14 17 20 23 26"
+    --8<-- "docs/examples/styles/height_comparison.css"
+    ```
+
+    1. This sets the height to 2 lines.
+    2. This sets the height to 12.5% of the space made available by the container. The container is 24 lines tall, so 12.5% of 24 is 3.
+    3. This sets the height to 5% of the width of the direct container, which is the `Vertical` container. Because it expands to fit all of the terminal, the width of the `Vertical` is 80 and 5% of 80 is 4.
+    4. This sets the height to 12.5% of the height of the direct container, which is the `Vertical` container. Because it expands to fit all of the terminal, the height of the `Vertical` is 24 and 12.5% of 24 is 3.
+    5. This sets the height to 7.5% of the viewport width, which is 80. 7.5% of 80 is 5.6 which gets truncated to 5.
+    6. This sets the height to 12.5% of the viewport height, which is 24. 12.5% of 24 is 3.
+    7. This sets the height of the placeholder to be the optimal size that fits the content without scrolling.
+    Because the content only spans one line, the placeholder has its height set to 1.
+    8. This sets the height to `1fr`, which means this placeholder will have half the height of a placeholder with `2fr`.
+    9. This sets the height to `2fr`, which means this placeholder will have twice the height of a placeholder with `1fr`.
+
+
 ## CSS
 
 ```sass
@@ -45,7 +82,7 @@ height: auto
 ## Python
 
 ```python
-self.styles.height = 10
+self.styles.height = 10  # Explicit cell height can be an int
 self.styles.height = "50%"
 self.styles.height = "auto"
 ```