Update padding reference.

docs/styles/padding.md

@@ -1,26 +1,44 @@
 # Padding
 
-The padding rule adds space around the content of a widget. You can specify padding with 1, 2 or 4 numbers.
+The `padding` rule specifies spacing around the content of a widget.
-
-| example             |                                                                     |
-| ------------------- | ------------------------------------------------------------------- |
-| `padding: 1;`       | A single value sets a padding of 1 around all 4 edges               |
-| `padding: 1 2;`     | Two values sets the padding for the top/bottom and left/right edges |
-| `padding: 1 2 3 4;` | Four values sets top, right, bottom, and left padding independently |
-
-Padding may also be set individually by setting `padding-top`, `padding-right`, `padding-bottom`, or `padding-left` to a single value.
 
 ## Syntax
 
-```
+--8<-- "docs/snippets/syntax_block_start.md"
-padding: <INTEGER>;
+padding: <a href="../../css_types/integer">&lt;integer&gt;</a> # one value for all edges
-padding: <INTEGER> <INTEGER>;
+       | <a href="../../css_types/integer">&lt;integer&gt;</a> <a href="../../css_types/integer">&lt;integer&gt;</a>
-padding: <INTEGER> <INTEGER> <INTEGER> <INTEGER>;
+       # top/bot   left/right
-```
+       | <a href="../../css_types/integer">&lt;integer&gt;</a> <a href="../../css_types/integer">&lt;integer&gt;</a> <a href="../../css_types/integer">&lt;integer&gt;</a> <a href="../../css_types/integer">&lt;integer&gt;</a>;
+       # top       right     bot       left
+
+padding-top: <a href="../../css_types/integer">&lt;integer&gt;</a>;
+padding-right: <a href="../../css_types/integer">&lt;integer&gt;</a>;
+padding-bottom: <a href="../../css_types/integer">&lt;integer&gt;</a>;
+padding-left: <a href="../../css_types/integer">&lt;integer&gt;</a>;
+--8<-- "docs/snippets/syntax_block_end.md"
+
+The `padding` specifies spacing around the _content_ of a widget, thus this spacing is added _inside_ the widget.
+The values of the [`<integer>`](../../css_types/integer) determine how much spacing is added and the number of values define what edges get what padding:
+
+ - 1 [`<integer>`](../../css_types/integer) sets the same padding for the four edges of the widget;
+ - 2 [`<integer>`](../../css_types/integer) set padding for top/bottom and left/right edges, respectively.
+ - 4 [`<integer>`](../../css_types/integer) set padding for the top, right, bottom, and left edges, respectively.
+
+!!! tip
+
+    To remember the order of the edges affected by the rule `padding` when it has 4 values, think of a clock.
+    Its hand starts at the top and the goes clockwise: top, right, bottom, left.
+
+Alternatively, padding can be set for each edge individually through the rules `padding-top`, `padding-right`, `padding-bottom`, and `padding-left`, respectively.
 
 ## Example
 
-This example adds padding around static text.
+This example adds padding around some text.
+
+=== "Output"
+
+    ```{.textual path="docs/examples/styles/padding.py"}
+    ```
 
 === "padding.py"
 
@@ -34,21 +52,34 @@ This example adds padding around static text.
     --8<-- "docs/examples/styles/padding.css"
     ```
 
-=== "Output"
-
-    ```{.textual path="docs/examples/styles/padding.py"}
-    ```
-
 ## CSS
 
 ```sass
+/* Set padding of 1 around all edges */
+padding: 1
 /* Set padding of 2 on the top and bottom edges, and 4 on the left and right */
 padding: 2 4;
+/* Set padding of 1 on the top, 2 on the right,
+                 3 on the bottom, and 4 on the left */
+padding: 1 2 3 4;
+
+padding-top: 1;
+padding-right: 2;
+padding-bottom: 3;
+padding-left: 4;
 ```
 
 ## Python
 
+In Python, you cannot set any of the individual `padding` rules `padding-top`, `padding-right`, `padding-bottom`, and `padding-left`.
+
+However, you _can_ set padding to a single integer, a tuple of 2 integers, or a tuple of 4 integers:
+
 ```python
-# In Python you can set the padding as a tuple of integers
+# Set padding of 1 around all edges
-widget.styles.padding = (2, 3)
+widget.styles.padding = 1
+# Set padding of 2 on the top and bottom edges, and 4 on the left and right
+widget.styles.padding = (2, 4)
+# Set padding of 1 on top, 2 on the right, 3 on the bottom, and 4 on the left
+widget.styles.padding = (1, 2, 3, 4)
 ```