From 559f976f78583bdd405ac0709378aafd2f22b58a 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: Thu, 23 Mar 2023 11:04:17 +0000
Subject: [PATCH] Add more consistent phrasing.
Related issues: #2107
---
docs/snippets/border_vs_outline_example.md | 21 +++++++++
docs/styles/_template.md | 46 +++++++++----------
docs/styles/align.md | 2 +-
docs/styles/background.md | 6 +--
docs/styles/border.md | 28 ++---------
docs/styles/border_subtitle_align.md | 4 +-
docs/styles/border_title_align.md | 4 +-
docs/styles/box_sizing.md | 2 +-
docs/styles/color.md | 4 +-
docs/styles/content_align.md | 2 +-
docs/styles/display.md | 2 +-
docs/styles/dock.md | 2 +-
docs/styles/grid/column_span.md | 2 +-
docs/styles/grid/grid_columns.md | 4 +-
docs/styles/grid/grid_gutter.md | 4 +-
docs/styles/grid/grid_rows.md | 4 +-
docs/styles/grid/grid_size.md | 4 +-
docs/styles/grid/index.md | 8 ++--
docs/styles/grid/row_span.md | 2 +-
docs/styles/height.md | 4 +-
docs/styles/index.md | 2 +-
docs/styles/layer.md | 6 +--
docs/styles/layers.md | 4 +-
docs/styles/layout.md | 4 +-
docs/styles/links/index.md | 2 +-
docs/styles/links/link_background.md | 2 +-
docs/styles/links/link_color.md | 2 +-
docs/styles/links/link_hover_background.md | 2 +-
docs/styles/links/link_hover_color.md | 2 +-
docs/styles/links/link_hover_style.md | 2 +-
docs/styles/links/link_style.md | 2 +-
docs/styles/margin.md | 9 ++--
docs/styles/max_height.md | 4 +-
docs/styles/max_width.md | 6 +--
docs/styles/min_height.md | 4 +-
docs/styles/min_width.md | 4 +-
docs/styles/offset.md | 4 +-
docs/styles/opacity.md | 4 +-
docs/styles/outline.md | 26 ++---------
docs/styles/overflow.md | 2 +-
docs/styles/padding.md | 6 +--
docs/styles/scrollbar_colors/index.md | 6 +--
.../scrollbar_colors/scrollbar_background.md | 2 +-
.../scrollbar_background_active.md | 2 +-
.../scrollbar_background_hover.md | 2 +-
.../scrollbar_colors/scrollbar_color.md | 2 +-
.../scrollbar_color_active.md | 2 +-
.../scrollbar_colors/scrollbar_color_hover.md | 2 +-
.../scrollbar_corner_color.md | 2 +-
docs/styles/scrollbar_gutter.md | 2 +-
docs/styles/scrollbar_size.md | 6 +--
docs/styles/text_align.md | 4 +-
docs/styles/text_opacity.md | 2 +-
docs/styles/text_style.md | 2 +-
docs/styles/tint.md | 4 +-
docs/styles/visibility.md | 6 +--
docs/styles/width.md | 2 +-
57 files changed, 141 insertions(+), 161 deletions(-)
create mode 100644 docs/snippets/border_vs_outline_example.md
diff --git a/docs/snippets/border_vs_outline_example.md b/docs/snippets/border_vs_outline_example.md
new file mode 100644
index 000000000..3a9f55406
--- /dev/null
+++ b/docs/snippets/border_vs_outline_example.md
@@ -0,0 +1,21 @@
+The next example makes the difference between [`border`](/styles/border) and [`outline`](/styles/outline) clearer by having three labels side-by-side.
+They contain the same text, have the same width and height, and are styled exactly the same up to their [`border`](/styles/border) and [`outline`](/styles/outline) styles.
+
+This example also shows that a widget cannot contain both a `border` and an `outline`:
+
+=== "Output"
+
+ ```{.textual path="docs/examples/styles/outline_vs_border.py"}
+ ```
+
+=== "outline_vs_border.py"
+
+ ```python
+ --8<-- "docs/examples/styles/outline_vs_border.py"
+ ```
+
+=== "outline_vs_border.css"
+
+ ```sass hl_lines="5-7 9-11"
+ --8<-- "docs/examples/styles/outline_vs_border.css"
+ ```
diff --git a/docs/styles/_template.md b/docs/styles/_template.md
index e83bd55a0..b01be7e8f 100644
--- a/docs/styles/_template.md
+++ b/docs/styles/_template.md
@@ -1,20 +1,20 @@
-
+
-# Rule-name
+# Style-name
-
## Syntax
--8<-- "docs/snippets/syntax_block_start.md"
--8<-- "docs/snippets/syntax_block_end.md"
-
+
### Values
@@ -35,19 +35,19 @@ Short description of the first example.
=== "Output"
- ```{.textual path="docs/examples/styles/rule.py"}
+ ```{.textual path="docs/examples/styles/style.py"}
```
-=== "rule.py"
+=== "style.py"
```py
- --8<-- "docs/examples/styles/rule.py"
+ --8<-- "docs/examples/styles/style.py"
```
-=== "rule.css"
+=== "style.css"
```sass
- --8<-- "docs/examples/styles/rule.css"
+ --8<-- "docs/examples/styles/style.css"
```
-->
@@ -57,19 +57,19 @@ Short description of the second example.
=== "Output"
- ```{.textual path="docs/examples/styles/rule.py"}
+ ```{.textual path="docs/examples/styles/style.py"}
```
-=== "rule.py"
+=== "style.py"
```py
- --8<-- "docs/examples/styles/rule.py"
+ --8<-- "docs/examples/styles/style.py"
```
-=== "rule.css"
+=== "style.css"
```sass
- --8<-- "docs/examples/styles/rule.css"
+ --8<-- "docs/examples/styles/style.css"
```
-->
@@ -98,18 +98,18 @@ rule-name-variant: value4
## Python
diff --git a/docs/styles/align.md b/docs/styles/align.md
index 0bbb7eddf..76835389c 100644
--- a/docs/styles/align.md
+++ b/docs/styles/align.md
@@ -11,7 +11,7 @@ align-horizontal: <horizontal>;
align-vertical: <vertical>;
--8<-- "docs/snippets/syntax_block_end.md"
-The style `align` takes a [``](../../css_types/horizontal) followed by a [``](../../css_types/vertical).
+The `align` style takes a [``](../../css_types/horizontal) followed by a [``](../../css_types/vertical).
You can specify the alignment of children on both the horizontal and vertical axes at the same time,
or on each of the axis separately.
diff --git a/docs/styles/background.md b/docs/styles/background.md
index 8bfdc3fd8..b22adca72 100644
--- a/docs/styles/background.md
+++ b/docs/styles/background.md
@@ -1,6 +1,6 @@
# Background
-The `background` rule sets the background color of a widget.
+The `background` style sets the background color of a widget.
## Syntax
@@ -8,7 +8,7 @@ The `background` rule sets the background color of a widget.
background: <color> [<percentage>];
--8<-- "docs/snippets/syntax_block_end.md"
-The style `background` needs a [``](../../css_types/color) followed by an optional [``](../../css_types/percentage) to specify the color transparency (clamped between `0%` and `100%`).
+The `background` style needs a [``](../../css_types/color) followed by an optional [``](../../css_types/percentage) to specify the color transparency (clamped between `0%` and `100%`).
## Examples
@@ -35,7 +35,7 @@ This example creates three widgets and applies a different background to each.
### Different transparency settings
-The next example creates ten widgets layed out side by side to show the effect of setting different percentages for the transparency of the background color.
+The next example creates ten widgets laid out side by side to show the effect of setting different percentages for the transparency of the background color.
=== "Output"
diff --git a/docs/styles/border.md b/docs/styles/border.md
index 5e9322909..267c16347 100644
--- a/docs/styles/border.md
+++ b/docs/styles/border.md
@@ -1,6 +1,6 @@
# Border
-The `border` rule enables the drawing of a box around a widget.
+The `border` style enables the drawing of a box around a widget.
!!! note
@@ -17,13 +17,13 @@ border-bottom: [<border>] [<border>] [<color> [<percentage>]];
--8<-- "docs/snippets/syntax_block_end.md"
-The style `border` accepts an optional [``](../../css_types/border) that sets the visual style of the widget border, an optional [``](../../css_types/color) to set the color of the border, and an optional [``](../../css_types/percentage) to specify the color transparency.
+The `border` style accepts an optional [``](../../css_types/border) that sets the visual style of the widget border, an optional [``](../../css_types/color) to set the color of the border, and an optional [``](../../css_types/percentage) to specify the color transparency.
Borders may also be set individually for the four edges of a widget with the `border-top`, `border-right`, `border-bottom` and `border-left` rules.
### Multiple edge rules
-If multiple border rules target the same edge, the last rule that targets a specific edge is the one that is applied to that edge.
+If multiple border styles target the same edge, the last style that targets a specific edge is the one that is applied to that edge.
For example, consider the CSS below:
```sass
@@ -99,27 +99,7 @@ The next example shows a grid with all the available border types.
### Borders and outlines
-The next example makes the difference between [`border`](./border.md) and [`outline`](./outline.md) clearer by having three labels side-by-side.
-They contain the same text, have the same width and height, and are styled exactly the same up to their `outline` and [`border`](./border.md) rules.
-
-This example also shows that a widget cannot contain both a `border` and an `outline`:
-
-=== "Output"
-
- ```{.textual path="docs/examples/styles/outline_vs_border.py"}
- ```
-
-=== "outline_vs_border.py"
-
- ```python
- --8<-- "docs/examples/styles/outline_vs_border.py"
- ```
-
-=== "outline_vs_border.css"
-
- ```sass hl_lines="5-7 9-11"
- --8<-- "docs/examples/styles/outline_vs_border.css"
- ```
+--8<-- "docs/snippets/border_vs_outline_example.md"
## CSS
diff --git a/docs/styles/border_subtitle_align.md b/docs/styles/border_subtitle_align.md
index 73108892d..5287cb5b9 100644
--- a/docs/styles/border_subtitle_align.md
+++ b/docs/styles/border_subtitle_align.md
@@ -1,6 +1,6 @@
# Border-subtitle-align
-The `border-subtitle-align` rule sets the horizontal alignment for the border subtitle.
+The `border-subtitle-align` style sets the horizontal alignment for the border subtitle.
## Syntax
@@ -8,7 +8,7 @@ The `border-subtitle-align` rule sets the horizontal alignment for the border su
border-subtitle-align: <horizontal>;
--8<-- "docs/snippets/syntax_block_end.md"
-The style `border-subtitle-align` takes a [``](../../css_types/horizontal) that determines where the border subtitle is aligned along the top edge of the border.
+The `border-subtitle-align` style takes a [``](../../css_types/horizontal) that determines where the border subtitle is aligned along the top edge of the border.
This means that the border corners are always visible.
### Default
diff --git a/docs/styles/border_title_align.md b/docs/styles/border_title_align.md
index 01b55bad8..3008d90b3 100644
--- a/docs/styles/border_title_align.md
+++ b/docs/styles/border_title_align.md
@@ -1,6 +1,6 @@
# Border-title-align
-The `border-title-align` rule sets the horizontal alignment for the border title.
+The `border-title-align` style sets the horizontal alignment for the border title.
## Syntax
@@ -8,7 +8,7 @@ The `border-title-align` rule sets the horizontal alignment for the border title
border-title-align: <horizontal>;
--8<-- "docs/snippets/syntax_block_end.md"
-The style `border-title-align` takes a [``](../../css_types/horizontal) that determines where the border title is aligned along the top edge of the border.
+The `border-title-align` style takes a [``](../../css_types/horizontal) that determines where the border title is aligned along the top edge of the border.
This means that the border corners are always visible.
### Default
diff --git a/docs/styles/box_sizing.md b/docs/styles/box_sizing.md
index f8c99f4cf..c6f08cdd2 100644
--- a/docs/styles/box_sizing.md
+++ b/docs/styles/box_sizing.md
@@ -1,6 +1,6 @@
# Box-sizing
-The `box-sizing` property determines how the width and height of a widget are calculated.
+The `box-sizing` style determines how the width and height of a widget are calculated.
## Syntax
diff --git a/docs/styles/color.md b/docs/styles/color.md
index 901c33b22..bb62a0235 100644
--- a/docs/styles/color.md
+++ b/docs/styles/color.md
@@ -1,6 +1,6 @@
# Color
-The `color` rule sets the text color of a widget.
+The `color` style sets the text color of a widget.
## Syntax
@@ -8,7 +8,7 @@ The `color` rule sets the text color of a widget.
color: (<color> | auto) [<percentage>];
--8<-- "docs/snippets/syntax_block_end.md"
-The style `color` needs a [``](../../css_types/color) followed by an optional [``](../../css_types/percentage) to specify the color transparency.
+The `color` style needs a [``](../../css_types/color) followed by an optional [``](../../css_types/percentage) to specify the color transparency.
Instead of a [``](../../css_types/color), one can use the special value `"auto"` to choose automatically the color with the best contrast for readability purposes.
diff --git a/docs/styles/content_align.md b/docs/styles/content_align.md
index 2902d9a84..d1a6bb905 100644
--- a/docs/styles/content_align.md
+++ b/docs/styles/content_align.md
@@ -11,7 +11,7 @@ content-align-horizontal: <horizontal>
content-align-vertical: <vertical>;
--8<-- "docs/snippets/syntax_block_end.md"
-The style `content-align` takes a [``](../../css_types/horizontal) followed by a [``](../../css_types/vertical).
+The `content-align` style takes a [``](../../css_types/horizontal) followed by a [``](../../css_types/vertical).
You can specify the alignment of content on both the horizontal and vertical axes at the same time,
or on each of the axis separately.
diff --git a/docs/styles/display.md b/docs/styles/display.md
index 8077776b1..34fbb3165 100644
--- a/docs/styles/display.md
+++ b/docs/styles/display.md
@@ -1,6 +1,6 @@
# Display
-The `display` property defines whether a widget is displayed or not.
+The `display` style defines whether a widget is displayed or not.
## Syntax
diff --git a/docs/styles/dock.md b/docs/styles/dock.md
index 51a4b8ec7..09135d300 100644
--- a/docs/styles/dock.md
+++ b/docs/styles/dock.md
@@ -1,6 +1,6 @@
# Dock
-The `dock` property is used to fix a widget to the edge of a container (which may be the entire terminal window).
+The `dock` style is used to fix a widget to the edge of a container (which may be the entire terminal window).
## Syntax
diff --git a/docs/styles/grid/column_span.md b/docs/styles/grid/column_span.md
index 2ea6261e6..2e1c0ef0a 100644
--- a/docs/styles/grid/column_span.md
+++ b/docs/styles/grid/column_span.md
@@ -12,7 +12,7 @@ The `column-span` style specifies how many columns a widget will span in a grid
column-span: <integer>;
--8<-- "docs/snippets/syntax_block_end.md"
-The style `column-span` accepts a single non-negative [``](../../../css_types/integer) that quantifies how many columns the given widget spans.
+The `column-span` style accepts a single non-negative [``](../../../css_types/integer) that quantifies how many columns the given widget spans.
## Example
diff --git a/docs/styles/grid/grid_columns.md b/docs/styles/grid/grid_columns.md
index e1d34e28d..058bc5651 100644
--- a/docs/styles/grid/grid_columns.md
+++ b/docs/styles/grid/grid_columns.md
@@ -12,7 +12,7 @@ The `grid-columns` style allows to define the width of the columns of the grid.
grid-columns: <scalar>+;
--8<-- "docs/snippets/syntax_block_end.md"
-The style `grid-columns` takes one or more [``](../../../css_types/scalar) that specify the length of the columns of the grid.
+The `grid-columns` style takes one or more [``](../../../css_types/scalar) that specify the length of the columns of the grid.
If there are more columns in the grid than scalars specified in `grid-columns`, they are reused cyclically.
If the number of [``](../../../css_types/scalar) is in excess, the excess is ignored.
@@ -22,7 +22,7 @@ If the number of [``](../../../css_types/scalar) is in excess, the exces
The example below shows a grid with 10 labels laid out in a grid with 2 rows and 5 columns.
We set `grid-columns: 1fr 16 2fr`.
-Because there are more rows than scalars in the style rule, the scalars will be reused:
+Because there are more rows than scalars in the style definition, the scalars will be reused:
- columns 1 and 4 have width `1fr`;
- columns 2 and 5 have width `16`; and
diff --git a/docs/styles/grid/grid_gutter.md b/docs/styles/grid/grid_gutter.md
index 98a6d2d1e..cbf457a4a 100644
--- a/docs/styles/grid/grid_gutter.md
+++ b/docs/styles/grid/grid_gutter.md
@@ -4,7 +4,7 @@ The `grid-gutter` style sets the size of the gutter in the grid layout.
That is, it sets the space between adjacent cells in the grid.
Gutter is only applied _between_ the edges of cells.
-No spacing is added between the edges of cells and the edges of the container.
+No spacing is added between the edges of the cells and the edges of the container.
!!! note
@@ -16,7 +16,7 @@ No spacing is added between the edges of cells and the edges of the container.
grid-gutter: <scalar> [<scalar>];
--8<-- "docs/snippets/syntax_block_end.md"
-The style `grid-gutter` takes one or two [``](../../../css_types/scalar) that set the length of the gutter along the vertical and horizontal axes.
+The `grid-gutter` style takes one or two [``](../../../css_types/scalar) that set the length of the gutter along the vertical and horizontal axes.
If only one [``](../../../css_types/scalar) is supplied, it sets the vertical and horizontal gutters.
If two are supplied, they set the vertical and horizontal gutters, respectively.
diff --git a/docs/styles/grid/grid_rows.md b/docs/styles/grid/grid_rows.md
index eb53264fa..be1e35161 100644
--- a/docs/styles/grid/grid_rows.md
+++ b/docs/styles/grid/grid_rows.md
@@ -12,7 +12,7 @@ The `grid-rows` style allows to define the height of the rows of the grid.
grid-rows: <scalar>+;
--8<-- "docs/snippets/syntax_block_end.md"
-The style `grid-rows` takes one or more [``](../../../css_types/scalar) that specify the length of the rows of the grid.
+The `grid-rows` style takes one or more [``](../../../css_types/scalar) that specify the length of the rows of the grid.
If there are more rows in the grid than scalars specified in `grid-rows`, they are reused cyclically.
If the number of [``](../../../css_types/scalar) is in excess, the excess is ignored.
@@ -22,7 +22,7 @@ If the number of [``](../../../css_types/scalar) is in excess, the exces
The example below shows a grid with 10 labels laid out in a grid with 5 rows and 2 columns.
We set `grid-rows: 1fr 6 25%`.
-Because there are more rows than scalars in the style rule, the scalars will be reused:
+Because there are more rows than scalars in the style definition, the scalars will be reused:
- rows 1 and 4 have height `1fr`;
- rows 2 and 5 have height `6`; and
diff --git a/docs/styles/grid/grid_size.md b/docs/styles/grid/grid_size.md
index d4d746bf9..1f2320bcd 100644
--- a/docs/styles/grid/grid_size.md
+++ b/docs/styles/grid/grid_size.md
@@ -14,7 +14,7 @@ The number of rows can be left unspecified and it will be computed automatically
grid-size: <integer> [<integer>];
--8<-- "docs/snippets/syntax_block_end.md"
-The style `grid-size` takes one or two non-negative [``](../../../css_types/integer).
+The `grid-size` style takes one or two non-negative [``](../../../css_types/integer).
The first defines how many columns there are in the grid.
If present, the second one sets the number of rows – regardless of the number of children of the grid –, otherwise the number of rows is computed automatically.
@@ -22,7 +22,7 @@ If present, the second one sets the number of rows – regardless of the number
### Columns and rows
-In the first example, we create a grid with 2 columns and 5 rows, regardless of the fact that we do not have enough labels to fill in the whole grid:
+In the first example, we create a grid with 2 columns and 5 rows, although we do not have enough labels to fill in the whole grid:
=== "Output"
diff --git a/docs/styles/grid/index.md b/docs/styles/grid/index.md
index 364fbaf3e..6263c88cc 100644
--- a/docs/styles/grid/index.md
+++ b/docs/styles/grid/index.md
@@ -1,6 +1,6 @@
# Grid
-There are a number of properties relating to the Textual `grid` layout.
+There are a number of styles relating to the Textual `grid` layout.
For an in-depth look at the grid layout, visit the grid [guide](../../guide/layout.md#grid).
@@ -33,10 +33,10 @@ Visit each style's reference page to learn more about how the values are used.
## Example
-The example below shows all the properties above in action.
+The example below shows all the styles above in action.
The `grid-size: 3 4;` declaration sets the grid to 3 columns and 4 rows.
The first cell of the grid, tinted magenta, shows a cell spanning multiple rows and columns.
-The spacing between grid cells is because of the `grid-gutter` declaration.
+The spacing between grid cells is defined by the `grid-gutter` style.
=== "Output"
@@ -57,7 +57,7 @@ The spacing between grid cells is because of the `grid-gutter` declaration.
!!! warning
- The properties listed on this page will only work when the layout is `grid`.
+ The styles listed on this page will only work when the layout is `grid`.
## See also
diff --git a/docs/styles/grid/row_span.md b/docs/styles/grid/row_span.md
index d55da6bfa..d7ec84e3f 100644
--- a/docs/styles/grid/row_span.md
+++ b/docs/styles/grid/row_span.md
@@ -12,7 +12,7 @@ The `row-span` style specifies how many rows a widget will span in a grid layout
row-span: <integer>;
--8<-- "docs/snippets/syntax_block_end.md"
-The style `row-span` accepts a single non-negative [``](../../../css_types/integer) that quantifies how many rows the given widget spans.
+The `row-span` style accepts a single non-negative [``](../../../css_types/integer) that quantifies how many rows the given widget spans.
## Example
diff --git a/docs/styles/height.md b/docs/styles/height.md
index bd3fe3512..6e7ecb3f5 100644
--- a/docs/styles/height.md
+++ b/docs/styles/height.md
@@ -1,6 +1,6 @@
# Height
-The `height` rule sets a widget's height.
+The `height` style sets a widget's height.
## Syntax
@@ -8,7 +8,7 @@ The `height` rule sets a widget's height.
height: <scalar>;
--8<-- "docs/snippets/syntax_block_end.md"
-The style `height` needs a [``](../../css_types/scalar) to determine the vertical length of the widget.
+The `height` style needs a [``](../../css_types/scalar) to determine the vertical length of the widget.
By default, it sets the height of the content area, but if [`box-sizing`](./box_sizing) is set to `border-box` it sets the height of the border area.
## Examples
diff --git a/docs/styles/index.md b/docs/styles/index.md
index 309f8f744..5617cf178 100644
--- a/docs/styles/index.md
+++ b/docs/styles/index.md
@@ -1,5 +1,5 @@
# Styles
-A reference to Widget [styles](../guide/styles.md).
+A reference to Widget [styles](../guide/styles.md).
See the links to the left of the page, or in the hamburger menu (three horizontal bars, top left).
diff --git a/docs/styles/layer.md b/docs/styles/layer.md
index b526fd57d..b662012ce 100644
--- a/docs/styles/layer.md
+++ b/docs/styles/layer.md
@@ -1,6 +1,6 @@
# Layer
-The `layer` property defines the layer a widget belongs to.
+The `layer` style defines the layer a widget belongs to.
## Syntax
@@ -8,8 +8,8 @@ The `layer` property defines the layer a widget belongs to.
layer: <name>;
--8<-- "docs/snippets/syntax_block_end.md"
-The `layer` rule accepts a [``](../../css_types/name) that defines the layer this widget belongs to.
-This [``](../../css_types/name) must correspond to a [``](../../css_types/name) that has been defined in a [`layers`](./layers) rule by an ancestor of this widget.
+The `layer` style accepts a [``](../../css_types/name) that defines the layer this widget belongs to.
+This [``](../../css_types/name) must correspond to a [``](../../css_types/name) that has been defined in a [`layers`](./layers) style by an ancestor of this widget.
More information on layers can be found in the [guide](../guide/layout.md#layers).
diff --git a/docs/styles/layers.md b/docs/styles/layers.md
index bab5204d7..9b9fc0cb4 100644
--- a/docs/styles/layers.md
+++ b/docs/styles/layers.md
@@ -1,6 +1,6 @@
# Layers
-The `layers` property allows you to define an ordered set of layers.
+The `layers` style allows you to define an ordered set of layers.
## Syntax
@@ -8,7 +8,7 @@ The `layers` property allows you to define an ordered set of layers.
layers: <name>+;
--8<-- "docs/snippets/syntax_block_end.md"
-The `layers` rule accepts one or more [``](../../css_types/name) that define the layers that the widget is aware of, and the order in which they will be painted on the screen.
+The `layers` style accepts one or more [``](../../css_types/name) that define the layers that the widget is aware of, and the order in which they will be painted on the screen.
The values used here can later be referenced using the [`layer`](../layer) property.
The layers defined first in the list are drawn under the layers that are defined later in the list.
diff --git a/docs/styles/layout.md b/docs/styles/layout.md
index 8de70d561..66095d63d 100644
--- a/docs/styles/layout.md
+++ b/docs/styles/layout.md
@@ -1,6 +1,6 @@
# Layout
-The `layout` property defines how a widget arranges its children.
+The `layout` style defines how a widget arranges its children.
## Syntax
@@ -22,7 +22,7 @@ See the [layout](../guide/layout.md) guide for more information.
## Example
-Note how the `layout` property affects the arrangement of widgets in the example below.
+Note how the `layout` style affects the arrangement of widgets in the example below.
To learn more about the grid layout, you can see the [layout guide](../guide/layout.md) or the [grid reference](../grid).
=== "Output"
diff --git a/docs/styles/links/index.md b/docs/styles/links/index.md
index 031af1d6e..6ae29ee04 100644
--- a/docs/styles/links/index.md
+++ b/docs/styles/links/index.md
@@ -5,7 +5,7 @@ There are a number of styles which influence the appearance of these links withi
!!! note
- These CSS rules only target Textual action links. Internet hyperlinks are not affected by these CSS rules.
+ These CSS rules only target Textual action links. Internet hyperlinks are not affected by these styles.
| Property | Description |
|-------------------------------------------------------|-------------------------------------------------------------------|
diff --git a/docs/styles/links/link_background.md b/docs/styles/links/link_background.md
index 9944682a6..9b48eae5f 100644
--- a/docs/styles/links/link_background.md
+++ b/docs/styles/links/link_background.md
@@ -1,6 +1,6 @@
# Link-background
-The `link-background` sets the background color of the link.
+The `link-background` style sets the background color of the link.
!!! note
diff --git a/docs/styles/links/link_color.md b/docs/styles/links/link_color.md
index 0d38369ed..215270b4d 100644
--- a/docs/styles/links/link_color.md
+++ b/docs/styles/links/link_color.md
@@ -1,6 +1,6 @@
# Link-color
-The `link-color` sets the color of the link text.
+The `link-color` style sets the color of the link text.
!!! note
diff --git a/docs/styles/links/link_hover_background.md b/docs/styles/links/link_hover_background.md
index 9afb7d8b6..34c9b3c0b 100644
--- a/docs/styles/links/link_hover_background.md
+++ b/docs/styles/links/link_hover_background.md
@@ -1,6 +1,6 @@
# Link-hover-background
-The `link-hover-background` sets the background color of the link when the mouse cursor is over the link.
+The `link-hover-background` style sets the background color of the link when the mouse cursor is over the link.
!!! note
diff --git a/docs/styles/links/link_hover_color.md b/docs/styles/links/link_hover_color.md
index 7a9311c6c..3dd1a4aae 100644
--- a/docs/styles/links/link_hover_color.md
+++ b/docs/styles/links/link_hover_color.md
@@ -1,6 +1,6 @@
# Link-hover-color
-The `link-hover-color` sets the color of the link text when the mouse cursor is over the link.
+The `link-hover-color` style sets the color of the link text when the mouse cursor is over the link.
!!! note
diff --git a/docs/styles/links/link_hover_style.md b/docs/styles/links/link_hover_style.md
index 989c7beae..b3c998b11 100644
--- a/docs/styles/links/link_hover_style.md
+++ b/docs/styles/links/link_hover_style.md
@@ -1,6 +1,6 @@
# Link-hover-style
-The `link-hover-style` sets the text style for the link text when the mouse cursor is over the link.
+The `link-hover-style` style sets the text style for the link text when the mouse cursor is over the link.
!!! note
diff --git a/docs/styles/links/link_style.md b/docs/styles/links/link_style.md
index f09bfb796..529ebbdbf 100644
--- a/docs/styles/links/link_style.md
+++ b/docs/styles/links/link_style.md
@@ -1,6 +1,6 @@
# Link-style
-The `link-style` sets the text style for the link text.
+The `link-style` style sets the text style for the link text.
!!! note
diff --git a/docs/styles/margin.md b/docs/styles/margin.md
index dd922de11..83d947fa2 100644
--- a/docs/styles/margin.md
+++ b/docs/styles/margin.md
@@ -1,6 +1,6 @@
# Margin
-The `margin` rule specifies spacing around a widget.
+The `margin` style specifies spacing around a widget.
## Syntax
@@ -30,7 +30,7 @@ The number of values given defines what edges get what margin:
To remember the order of the edges affected by the rule `margin` when it has 4 values, think of a clock.
Its hand starts at the top and the goes clockwise: top, right, bottom, left.
-Alternatively, margin can be set for each edge individually through the rules `margin-top`, `margin-right`, `margin-bottom`, and `margin-left`, respectively.
+Alternatively, margin can be set for each edge individually through the styles `margin-top`, `margin-right`, `margin-bottom`, and `margin-left`, respectively.
## Examples
@@ -96,9 +96,8 @@ margin-left: 4;
## Python
-In Python, you cannot set any of the individual `margin` rules `margin-top`, `margin-right`, `margin-bottom`, and `margin-left`.
-
-However, you _can_ set margin to a single integer, a tuple of 2 integers, or a tuple of 4 integers:
+Python does not provide the properties `margin-top`, `margin-right`, `margin-bottom`, and `margin-left`.
+However, you _can_ set the margin to a single integer, a tuple of 2 integers, or a tuple of 4 integers:
```python
# Set margin of 1 around all edges
diff --git a/docs/styles/max_height.md b/docs/styles/max_height.md
index aa89dbade..ec574d119 100644
--- a/docs/styles/max_height.md
+++ b/docs/styles/max_height.md
@@ -1,6 +1,6 @@
# Max-height
-The `max-height` rule sets a maximum height for a widget.
+The `max-height` style sets a maximum height for a widget.
## Syntax
@@ -8,7 +8,7 @@ The `max-height` rule sets a maximum height for a widget.
max-height: <scalar>;
--8<-- "docs/snippets/syntax_block_end.md"
-The `max-height` rule accepts a [``](../../css_types/scalar) that defines an upper bound for the [`height`](./height) of a widget.
+The `max-height` style accepts a [``](../../css_types/scalar) that defines an upper bound for the [`height`](./height) of a widget.
That is, the height of a widget is never allowed to exceed `max-height`.
## Example
diff --git a/docs/styles/max_width.md b/docs/styles/max_width.md
index 9cf7236b2..0dd626f72 100644
--- a/docs/styles/max_width.md
+++ b/docs/styles/max_width.md
@@ -1,6 +1,6 @@
# Max-width
-The `max-width` rule sets a maximum width for a widget.
+The `max-width` style sets a maximum width for a widget.
## Syntax
@@ -8,12 +8,12 @@ The `max-width` rule sets a maximum width for a widget.
max-width: <scalar>;
--8<-- "docs/snippets/syntax_block_end.md"
-The `max-width` rule accepts a [``](../../css_types/scalar) that defines an upper bound for the [`width`](./width) of a widget.
+The `max-width` style accepts a [``](../../css_types/scalar) that defines an upper bound for the [`width`](./width) of a widget.
That is, the width of a widget is never allowed to exceed `max-width`.
## Example
-The example below shows some placeholders that were defined to span horizontally from the top edge of the terminal to the bottom edge.
+The example below shows some placeholders that were defined to span horizontally from the left edge of the terminal to the right edge.
Then, we set `max-width` individually on each placeholder.
=== "Output"
diff --git a/docs/styles/min_height.md b/docs/styles/min_height.md
index a25dc9c7a..558261d1c 100644
--- a/docs/styles/min_height.md
+++ b/docs/styles/min_height.md
@@ -1,6 +1,6 @@
# Min-height
-The `min-height` rule sets a minimum height for a widget.
+The `min-height` style sets a minimum height for a widget.
## Syntax
@@ -8,7 +8,7 @@ The `min-height` rule sets a minimum height for a widget.
min-height: <scalar>;
--8<-- "docs/snippets/syntax_block_end.md"
-The `min-height` rule accepts a [``](../../css_types/scalar) that defines a lower bound for the [`height`](./height) of a widget.
+The `min-height` style accepts a [``](../../css_types/scalar) that defines a lower bound for the [`height`](./height) of a widget.
That is, the height of a widget is never allowed to be under `min-height`.
## Example
diff --git a/docs/styles/min_width.md b/docs/styles/min_width.md
index 15c32b64b..6749043b0 100644
--- a/docs/styles/min_width.md
+++ b/docs/styles/min_width.md
@@ -1,6 +1,6 @@
# Min-width
-The `min-width` rule sets a minimum width for a widget.
+The `min-width` style sets a minimum width for a widget.
## Syntax
@@ -8,7 +8,7 @@ The `min-width` rule sets a minimum width for a widget.
min-width: <scalar>;
--8<-- "docs/snippets/syntax_block_end.md"
-The `min-width` rule accepts a [``](../../css_types/scalar) that defines a lower bound for the [`width`](./width) of a widget.
+The `min-width` style accepts a [``](../../css_types/scalar) that defines a lower bound for the [`width`](./width) of a widget.
That is, the width of a widget is never allowed to be under `min-width`.
## Example
diff --git a/docs/styles/offset.md b/docs/styles/offset.md
index 2a5ffefce..02b4b3709 100644
--- a/docs/styles/offset.md
+++ b/docs/styles/offset.md
@@ -1,6 +1,6 @@
# Offset
-The `offset` rule defines an offset for the position of the widget.
+The `offset` style defines an offset for the position of the widget.
## Syntax
@@ -8,7 +8,7 @@ The `offset` rule defines an offset for the position of the widget.
offset: <scalar> <scalar>;
offset-x: <scalar>;
-offset-y: <scalar>
+offset-y: <scalar>
--8<-- "docs/snippets/syntax_block_end.md"
The two [``](../../css_types/scalar) in the `offset` define, respectively, the offsets in the horizontal and vertical axes for the widget.
diff --git a/docs/styles/opacity.md b/docs/styles/opacity.md
index 88db9ce9e..e8788962e 100644
--- a/docs/styles/opacity.md
+++ b/docs/styles/opacity.md
@@ -1,6 +1,6 @@
# Opacity
-The `opacity` property sets the opacity/transparency of a widget.
+The `opacity` style sets the opacity/transparency of a widget.
## Syntax
@@ -8,7 +8,7 @@ The `opacity` property sets the opacity/transparency of a widget.
opacity: <number> | <percentage>;
--8<-- "docs/snippets/syntax_block_end.md"
-The opacity of a widget can be set as a [``](../css_types/number.md) or a [``](../css_types/percentage.md).
+The opacity of a widget can be set as a [``](../css_types/number.md) or a [``](../css_types/percentage.md).
`0`/`0%` means no opacity, which is equivalent to full transparency.
Conversely, `1`/`100%` means full opacity, which is equivalent to no transparency.
Values outside of these ranges will be clamped.
diff --git a/docs/styles/outline.md b/docs/styles/outline.md
index 2df963f9b..5e5155f89 100644
--- a/docs/styles/outline.md
+++ b/docs/styles/outline.md
@@ -1,6 +1,6 @@
# Outline
-The `outline` rule enables the drawing of a box around the content of a widget, which means the outline is drawn _over_ the content area.
+The `outline` style enables the drawing of a box around the content of a widget, which means the outline is drawn _over_ the content area.
!!! note
@@ -20,7 +20,7 @@ outline-left: [<border>] [`](../../css_types/integer) determine how much spac
!!! 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.
+ Its hand starts at the top and then 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.
@@ -96,7 +96,7 @@ padding-left: 4;
## Python
-In Python, you cannot set any of the individual `padding` rules `padding-top`, `padding-right`, `padding-bottom`, and `padding-left`.
+In Python, you cannot set any of the individual `padding` styles `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:
diff --git a/docs/styles/scrollbar_colors/index.md b/docs/styles/scrollbar_colors/index.md
index a136e00ea..fce1aeb9a 100644
--- a/docs/styles/scrollbar_colors/index.md
+++ b/docs/styles/scrollbar_colors/index.md
@@ -1,9 +1,9 @@
# Scrollbar colors
-There are a number of rules to set the colors used in Textual scrollbars.
+There are a number of styles to set the colors used in Textual scrollbars.
You won't typically need to do this, as the default themes have carefully chosen colors, but you can if you want to.
-| Rule | Applies to |
+| Style | Applies to |
|-------------------------------------------------------------------|----------------------------------------------------------|
| [`scrollbar-background`](./scrollbar_background.md) | Scrollbar background. |
| [`scrollbar-background-active`](./scrollbar_background_active.md) | Scrollbar background when the thumb is being dragged. |
@@ -35,7 +35,7 @@ Visit each style's reference page to learn more about how the values are used.
## Example
-This example shows two planels that contain oversized text.
+This example shows two panels that contain oversized text.
The right panel sets `scrollbar-background`, `scrollbar-color`, and `scrollbar-corner-color`, and the left panel shows the default colors for comparison.
=== "Output"
diff --git a/docs/styles/scrollbar_colors/scrollbar_background.md b/docs/styles/scrollbar_colors/scrollbar_background.md
index bc4e9ebf8..8de2ef491 100644
--- a/docs/styles/scrollbar_colors/scrollbar_background.md
+++ b/docs/styles/scrollbar_colors/scrollbar_background.md
@@ -1,6 +1,6 @@
# Scrollbar-background
-The `scrollbar-background` sets the background color of the scrollbar.
+The `scrollbar-background` style sets the background color of the scrollbar.
## Syntax
--8<-- "docs/snippets/syntax_block_start.md"
diff --git a/docs/styles/scrollbar_colors/scrollbar_background_active.md b/docs/styles/scrollbar_colors/scrollbar_background_active.md
index 6561ad1bc..6c0f2722d 100644
--- a/docs/styles/scrollbar_colors/scrollbar_background_active.md
+++ b/docs/styles/scrollbar_colors/scrollbar_background_active.md
@@ -1,6 +1,6 @@
# Scrollbar-background-active
-The `scrollbar-background-active` sets the background color of the scrollbar when the thumb is being dragged.
+The `scrollbar-background-active` style sets the background color of the scrollbar when the thumb is being dragged.
## Syntax
diff --git a/docs/styles/scrollbar_colors/scrollbar_background_hover.md b/docs/styles/scrollbar_colors/scrollbar_background_hover.md
index 22628645e..bf871479f 100644
--- a/docs/styles/scrollbar_colors/scrollbar_background_hover.md
+++ b/docs/styles/scrollbar_colors/scrollbar_background_hover.md
@@ -1,6 +1,6 @@
# Scrollbar-background-hover
-The `scrollbar-background-hover` sets the background color of the scrollbar when the cursor is over it.
+The `scrollbar-background-hover` style sets the background color of the scrollbar when the cursor is over it.
## Syntax
diff --git a/docs/styles/scrollbar_colors/scrollbar_color.md b/docs/styles/scrollbar_colors/scrollbar_color.md
index 4930289d7..42df3d25a 100644
--- a/docs/styles/scrollbar_colors/scrollbar_color.md
+++ b/docs/styles/scrollbar_colors/scrollbar_color.md
@@ -1,6 +1,6 @@
# Scrollbar-color
-The `scrollbar-color` sets the color of the scrollbar.
+The `scrollbar-color` style sets the color of the scrollbar.
## Syntax
diff --git a/docs/styles/scrollbar_colors/scrollbar_color_active.md b/docs/styles/scrollbar_colors/scrollbar_color_active.md
index 7be97f8b1..1d6e521fe 100644
--- a/docs/styles/scrollbar_colors/scrollbar_color_active.md
+++ b/docs/styles/scrollbar_colors/scrollbar_color_active.md
@@ -1,6 +1,6 @@
# Scrollbar-color-active
-The `scrollbar-color-active` sets the color of the scrollbar when the thumb is being dragged.
+The `scrollbar-color-active` style sets the color of the scrollbar when the thumb is being dragged.
## Syntax
diff --git a/docs/styles/scrollbar_colors/scrollbar_color_hover.md b/docs/styles/scrollbar_colors/scrollbar_color_hover.md
index 371521b05..9e914cc11 100644
--- a/docs/styles/scrollbar_colors/scrollbar_color_hover.md
+++ b/docs/styles/scrollbar_colors/scrollbar_color_hover.md
@@ -1,6 +1,6 @@
# Scrollbar-color-hover
-The `scrollbar-color-hover` sets the color of the scrollbar when the cursor is over it.
+The `scrollbar-color-hover` style sets the color of the scrollbar when the cursor is over it.
## Syntax
diff --git a/docs/styles/scrollbar_colors/scrollbar_corner_color.md b/docs/styles/scrollbar_colors/scrollbar_corner_color.md
index 44b0e501d..b6a83671d 100644
--- a/docs/styles/scrollbar_colors/scrollbar_corner_color.md
+++ b/docs/styles/scrollbar_colors/scrollbar_corner_color.md
@@ -1,6 +1,6 @@
# Scrollbar-corner-color
-The `scrollbar-corner-color` sets the color of the gap between the horizontal and vertical scrollbars.
+The `scrollbar-corner-color` style sets the color of the gap between the horizontal and vertical scrollbars.
## Syntax
diff --git a/docs/styles/scrollbar_gutter.md b/docs/styles/scrollbar_gutter.md
index db5270303..a20db9fda 100644
--- a/docs/styles/scrollbar_gutter.md
+++ b/docs/styles/scrollbar_gutter.md
@@ -1,6 +1,6 @@
# Scrollbar-gutter
-The `scrollbar-gutter` rule allows reserving space for a vertical scrollbar.
+The `scrollbar-gutter` style allows reserving space for a vertical scrollbar.
## Syntax
diff --git a/docs/styles/scrollbar_size.md b/docs/styles/scrollbar_size.md
index 2e5a6cfff..a6bea3927 100644
--- a/docs/styles/scrollbar_size.md
+++ b/docs/styles/scrollbar_size.md
@@ -1,6 +1,6 @@
# Scrollbar-size
-The `scrollbar-size` rule defines the width of the scrollbars.
+The `scrollbar-size` style defines the width of the scrollbars.
## Syntax
@@ -12,7 +12,7 @@ scrollbar-size-horizontal: <integer>
scrollbar-size-vertical: <integer>;
--8<-- "docs/snippets/syntax_block_end.md"
-The `scrollbar-size` rule takes two [``](../css_types/integer.md) to set the horizontal and vertical scrollbar sizes, respectively.
+The `scrollbar-size` style takes two [``](../css_types/integer.md) to set the horizontal and vertical scrollbar sizes, respectively.
This customisable size is the width of the scrollbar, given that its length will always be 100% of the container.
The scrollbar widths may also be set individually with `scrollbar-size-horizontal` and `scrollbar-size-vertical`.
@@ -76,7 +76,7 @@ scrollbar-size-vertical: 4;
## Python
-The rule `scrollbar-size` has no Python equivalent.
+The style `scrollbar-size` has no Python equivalent.
The scrollbar sizes must be set independently:
```py
diff --git a/docs/styles/text_align.md b/docs/styles/text_align.md
index 37a3fc1bd..aee695091 100644
--- a/docs/styles/text_align.md
+++ b/docs/styles/text_align.md
@@ -1,6 +1,6 @@
# Text-align
-The `text-align` rule sets the text alignment in a widget.
+The `text-align` style sets the text alignment in a widget.
## Syntax
@@ -8,7 +8,7 @@ The `text-align` rule sets the text alignment in a widget.
text-align: <text-align>;
--8<-- "docs/snippets/syntax_block_end.md"
-The `text-align` rule accepts a value of the type [``](../css_types/text_align.md) that defines how text is aligned inside the widget.
+The `text-align` style accepts a value of the type [``](../css_types/text_align.md) that defines how text is aligned inside the widget.
### Defaults
diff --git a/docs/styles/text_opacity.md b/docs/styles/text_opacity.md
index ca89a3b0c..9bed3fb92 100644
--- a/docs/styles/text_opacity.md
+++ b/docs/styles/text_opacity.md
@@ -1,6 +1,6 @@
# Text-opacity
-The `text-opacity` blends the color of the content of a widget with the color of the background.
+The `text-opacity` style blends the color of the content of a widget with the color of the background.
## Syntax
diff --git a/docs/styles/text_style.md b/docs/styles/text_style.md
index aa0d4fcdd..a0ee02f90 100644
--- a/docs/styles/text_style.md
+++ b/docs/styles/text_style.md
@@ -35,7 +35,7 @@ Each of the three text panels has a different text style, respectively `bold`, `
### All text styles
-The next example shows all different styles on their own, as well as some combinations of styles in a single widget.
+The next example shows all different text styles on their own, as well as some combinations of styles in a single widget.
=== "Output"
diff --git a/docs/styles/tint.md b/docs/styles/tint.md
index 6ca08b04e..19002ff44 100644
--- a/docs/styles/tint.md
+++ b/docs/styles/tint.md
@@ -1,6 +1,6 @@
# Tint
-The `tint` rule blends a color with the whole widget.
+The `tint` style blends a color with the whole widget.
## Syntax
@@ -8,7 +8,7 @@ The `tint` rule blends a color with the whole widget.
tint: <color> [<percentage>];
--8<-- "docs/snippets/syntax_block_end.md"
-The tint rule blends a [``](../css_types/color.md) with the widget. The color should likely have an _alpha_ component (specified directly in the color used or by the optional [``](../css_types/percentage.md)), otherwise the end result will obscure the widget content.
+The tint style blends a [``](../css_types/color.md) with the widget. The color should likely have an _alpha_ component (specified directly in the color used or by the optional [``](../css_types/percentage.md)), otherwise the end result will obscure the widget content.
## Example
diff --git a/docs/styles/visibility.md b/docs/styles/visibility.md
index 2d9e07590..38d958c92 100644
--- a/docs/styles/visibility.md
+++ b/docs/styles/visibility.md
@@ -1,6 +1,6 @@
# Visibility
-The `visibility` rule determines whether a widget is visible or not.
+The `visibility` style determines whether a widget is visible or not.
## Syntax
@@ -32,7 +32,7 @@ This is shown in the second example below.
### Basic usage
-Note that the second widget is hidden, while leaving a space where it would have been rendered.
+Note that the second widget is hidden while leaving a space where it would have been rendered.
=== "Output"
@@ -53,7 +53,7 @@ Note that the second widget is hidden, while leaving a space where it would have
### Overriding container visibility
-The next example shows the interaction of the `visibility` rule with invisible containers that have visible children.
+The next example shows the interaction of the `visibility` style with invisible containers that have visible children.
The app below has three rows with a `Horizontal` container per row and three placeholders per row.
The containers all have a white background, and then:
diff --git a/docs/styles/width.md b/docs/styles/width.md
index bc1cf055b..276fde5a7 100644
--- a/docs/styles/width.md
+++ b/docs/styles/width.md
@@ -1,6 +1,6 @@
# Width
-The `width` rule sets a widget's width.
+The `width` style sets a widget's width.
## Syntax