Draft

docs/reference/src/language/concepts/container.md

@@ -1,9 +1,10 @@
 <!-- Copyright © SixtyFPS GmbH <info@slint.dev> ; SPDX-License-Identifier: MIT -->
+
 # Container Components
 
 When creating components, it's sometimes useful to influence where child
-elements are placed when used. For example, imagine a component that draws
-a label above whatever element the user places inside:
+elements are placed when used. For example, a component that draws
+a label above an element inside:
 
 ```slint,ignore
 export component MyApp inherits Window {
@@ -19,8 +20,8 @@ export component MyApp inherits Window {
 ```
 
 You can implement such a `BoxWithLabel` using a layout. By default child elements like
-the `Text` element become direct children of the `BoxWithLabel`, but we need them to become
-children of our layout instead. For this purpose, you can change the default child placement by using
+the `Text` element become direct children of the `BoxWithLabel`, but for this example they need to become
+children of the layout instead. To do this can change the default child placement by using
 the `@children` expression inside the element hierarchy of a component:
 
 ```slint

docs/reference/src/language/concepts/file.md

@@ -1,7 +1,8 @@
 <!-- Copyright © SixtyFPS GmbH <info@slint.dev> ; SPDX-License-Identifier: MIT -->
+
 # The `.slint` File
 
-User interfaces are written in the Slint language and saved in files with the `.slint` extension.
+You write user interfaces in the Slint language and saved in files with the `.slint` extension.
 
 Each `.slint` file defines one or several components. These components declare
 a tree of elements. Components form the basis of composition in Slint. Use them
@@ -35,15 +36,14 @@ export component MyApp inherits Window {
         text: "world";
     }
 }
-
 ```
 
 Both `MyButton` and `MyApp` are components. `Window` and `Rectangle` are built-in elements
 used by `MyApp`. `MyApp` also re-uses the `MyButton` component as two separate elements.
 
-Elements have properties, which you can assign values to. Here we assign a string
+Elements have properties, which you can assign values to. The example above assigns a string
 constant "hello" to the first `MyButton`'s `text` property. You
-can also assign entire expressions. Slint will re-evaluate the expressions when any
+can also assign entire expressions. Slint re-evaluates the expressions when any
 of the properties they depend on change, which makes the user-interface reactive.
 
 You can name elements using the `:=` syntax:
@@ -69,8 +69,12 @@ export component MyApp inherits Window {
 }
 ```
 
+:::note
+
 Names have to be valid [identifiers](../syntax/identifiers.md).
 
+:::
+
 Some elements are also accessible under pre-defined names:
 
 -   `root` refers to the outermost element of a component.

docs/reference/src/language/concepts/focus.md

@@ -1,10 +1,11 @@
 <!-- Copyright © SixtyFPS GmbH <info@slint.dev> ; SPDX-License-Identifier: MIT -->
+
 # Focus Handling
 
-Certain elements such as `TextInput` accept not only input from the mouse/finger but
+Certain elements such as `TextInput` accept input from the mouse/finger and
 also key events originating from (virtual) keyboards. In order for an item to receive
-these events, it must have the focus. This is visible through the `has-focus` (out) property.
-
+these events, it must have focus. This is visible through the `has-focus` (out) property.
+<!-- (out)? -->
 You can manually activate the focus on an element by calling `focus()`:
 
 ```slint
@@ -43,7 +44,7 @@ export component App inherits Window {
 }
 ```
 
-After the focus is cleared, keyboard input to the window is discarded, until another element is explicitly
+After clearing the focus, keyboard input to the window is discarded until another element is explicitly
 focused. For example by calling `focus()`, an element acquiring focus when the user clicks on it, or when
 pressing tab and the first focusable element is found.
 

docs/reference/src/language/concepts/fonts.md

@@ -1,12 +1,13 @@
 <!-- Copyright © SixtyFPS GmbH <info@slint.dev> ; SPDX-License-Identifier: MIT -->
+
 # Font Handling
 
 Elements such as `Text` and `TextInput` can render text and allow customizing the appearance of the text through
 different properties. The properties prefixed with `font-`, such as `font-family`, `font-size` and `font-weight`
 affect the choice of font used for rendering to the screen. If any of these properties isn't specified, the `default-font-`
 values in the surrounding `Window` element apply, such as `default-font-family`.
 
-The fonts chosen for rendering are automatically picked up from the system. It's also possible to include custom
+The fonts chosen for rendering are automatically picked up from the system running the application. It's also possible to include custom
 fonts in your design. A custom font must be a TrueType font (`.ttf`), a TrueType font collection (`.ttc`) or an OpenType font (`.otf`).
 You can select a custom font with the `import` statement: `import "./my_custom_font.ttf"` in a .slint file. This
 instructions the Slint compiler to include the font and makes the font families globally available for use with

docs/reference/src/language/concepts/layouting.md

@@ -1,4 +1,5 @@
 <!-- Copyright © SixtyFPS GmbH <info@slint.dev> ; SPDX-License-Identifier: MIT -->
+
 # Positioning and Layout of Elements
 
 All visual elements are shown in a window. The `x` and `y` properties store
@@ -64,11 +65,11 @@ configured with. For example, on a modern High-DPI display the device pixel rati
 so every logical pixel occupies 2 physical pixels. On an older screen the user
 interface scales without any adaptations.
 
-Additionally, the `width` and `height` properties can also be specified as a `%` percentage
+You can also specify the `width` and `height` properties as a `%` percentage
 unit, which applies relative to the parent element. For example a `width: 50%` means half
 of the parent's `width`.
 
-The default values for `x` and `y` properties are such that elements are centered within their
+The default values for `x` and `y` properties center elements within their
 parent.
 
 The default values for `width` and `height` depend on the type of element. Some elements are sized
@@ -81,19 +82,19 @@ don't have content and default to fill their parent element when they do not hav
 -   `Flickable`
 
 Layouts are also defaulting to fill the parent, regardless of their own preferred size.
-
+<!-- Without base? -->
 Other elements (including custom ones without base) default to using their preferred size.
 
 ### Preferred size
 
-The preferred size of elements can be specified with the `preferred-width` and `preferred-height` properties.
+You can specify the preferred size of elements with the `preferred-width` and `preferred-height` properties.
 
 When not explicitly set, the preferred size depends on the children, and is the preferred size of the
 child that has the bigger preferred size, whose `x` and `y` property are not set.
 The preferred size is therefore computed from the child to the parent, just like other constraints (maximum and minimum size), unless explicitly overwritten.
 
 A special case is to set the preferred size to be the size of the parent using `100%` as value.
-For example,this component will use the size of the parent by default:
+For example, this component uses the size of the parent by default:
 
 ```slint
 export component MyComponent {
@@ -146,7 +147,7 @@ All layout elements have the following properties in common:
 -   `padding`: This specifies the padding within the layout, the space between the elements and the border of the
     layout.
 
-For more fine grained control, the `padding` property can be split into properties for each side of the layout:
+For more fine grained control, you can split the `padding` property into properties for each side of the layout:
 
 -   `padding-left`
 -   `padding-right`
@@ -174,7 +175,7 @@ export component Example inherits Window {
 }
 ```
 
-The example below, on the other hand, specifies that the rectangles shall align
+The example below, on the other hand, specifies that the rectangles align
 to the start of the layout (the visual left). That results in no stretching but instead
 the rectangles retain their specified minimum width:
 
@@ -234,7 +235,7 @@ the minimum size of an inner layout, whatever is bigger.
 The elements are placed according to the alignment. The size of elements
 is bigger than the minimum size only if the `alignment` property of the layout is `LayoutAlignment.stretch` (the default)
 
-This example show the different alignment possibilities
+This example show the different alignment possibilities:
 
 ```slint
 export component Example inherits Window {
@@ -294,7 +295,7 @@ then the extra space is shared amongst element proportional to their stretch fac
 `horizontal-stretch` and `vertical-stretch` properties. The stretched size won't exceed the maximum size.
 The stretch factor is a floating point number. The elements that have a default content size usually defaults to 0
 while elements that default to the size of their parents defaults to 1.
-An element of a stretch factor of 0 will keep its minimum size, unless all the other elements also have a stretch
+An element of a stretch factor of 0 keep its minimum size, unless all the other elements also have a stretch
 factor of 0 or reached their maximum size.
 
 Examples:
@@ -333,7 +334,7 @@ export component Example inherits Window {
 
 ### `for`
 
-The VerticalLayout and Horizontal layout may also contain `for` or `if` expressions:
+The VerticalLayout and HorizontalLayout can also contain `for` or `if` expressions:
 
 ```slint
 export component Example inherits Window {
@@ -353,7 +354,7 @@ export component Example inherits Window {
 
 The GridLayout lays the element in a grid.
 Each element gains the properties `row`, `col`, `rowspan`, and `colspan`.
-One can either use a `Row` sub-element, or set the `row` property explicitly.
+You can either use a `Row` sub-element, or set the `row` property explicitly.
 These properties must be statically known at compile time, so it's impossible
 to use arithmetic or depend on properties. As of now, the use of `for` or `if`
 isn't allowed in a grid layout.
@@ -378,7 +379,7 @@ export component Foo inherits Window {
 }
 ```
 
-This example use the `col` and `row` property
+This example use the `col` and `row` property:
 
 ```slint
 export component Foo inherits Window {

docs/reference/src/language/index.rst

@@ -1,29 +1,31 @@
 .. Copyright © SixtyFPS GmbH <info@slint.dev>
 .. SPDX-License-Identifier: MIT
 
+.. A lot of repitition
+
 Introduction
 ============
 
-`Slint <https://slint.dev>`_ comes with an easy to learn and use language for you to describe user
-interfaces with. It is readable to both humans and machines.
+Slint is an easy to learn and use language to describe user
+interfaces. It is readable to both humans and machines.
 
+.. ???
 This way, we have excellent tooling on one side, while also enabling
 designers and developers to know exactly what happens, by reading the code
 their machine uses to display the user interfaces.
 
-This Slint language is either interpreted at run-time or compiled to native
-code, which gets built into your application together with the code in the same
+This Slint code is either interpreted at run-time or compiled to native
+code, which gets built into your application together with the code in the
 programming language providing the business logic. The Slint compiler can
 optimize the user interface and any resources it uses at compile time, so
 that user interfaces written in Slint use few resources, with regards to
 performance and storage.
 
 The Slint language enforces a separation of user interface from business logic,
-using interfaces you can define for your project. This enables a fearless
+using interfaces you can define for your project. This enables
 cooperation between design-focused team members and those concentrating on the programming
 side of the project.
 
-
 The Slint language describes extensible graphical user interfaces using the
 `Slint framework <https://slint.dev>`_
 
@@ -38,5 +40,7 @@ The Slint language describes extensible graphical user interfaces using the
 - Build highly customized user interfaces with the :ref:`builtin elements <Builtin Elements>`
   and pre-built :ref:`widgets <Widgets>` provided.
 
-It only describes the user interface and it is not a programming language. The business
+.. Again, repitition
+
+Slint only describes the user interface and is not a programming language. The business
 logic is written in a different programming language using the Slint API.