diff --git a/docs/03-declarative-layout.md b/docs/03-declarative-layout.md index c43dee185..c0b34e5b9 100644 --- a/docs/03-declarative-layout.md +++ b/docs/03-declarative-layout.md @@ -1,13 +1,13 @@ # The declarative layout system -This system provide an alternative to the system used in Awesome 3.5 and is -inspired by the one once used by Awesome 3.2-3.4 and Qt QML system. +The declarative layout system provides an alternative to the imperative system. +It is inspired by the one used by Awesome 3.2-3.4 and the Qt QML style. ## The default widgets ### Widgets -Awesome provide 2 collections of widgets: +Awesome provides 2 collections of widgets: * `wibox.widget`: Generic widgets, containers and layouts * `awful.widget`: The Awesome specific widgets @@ -17,15 +17,15 @@ Awesome provide 2 collections of widgets: ### Containers -Containers are widget wrapping another widget. It can be used to add decorations -or to modify the content of the child widget. +A container is a widget that wraps another widget. It can be used to add +decorations or to modify the content of the child widget. @DOC_container_WIDGET_LIST@ ### Layouts -Layouts are collection of children widgets. They place them according to rules -and usually provide some options. +Layouts are collections of children widgets. They are placed according to +configurable rules. @DOC_layout_WIDGET_LIST@ @@ -52,8 +52,8 @@ Code: In this example `s == 1` is an inline expression. In the default `rc.lua`, -there is an `s` variable represent to define the current screen. Any lua -logic expression can be used as long as it return a valid widget, or a +there is an `s` variable represent to define the current screen. Any Lua +logic expression can be used as long as it returns a valid widget or a declarative layout, or `nil`. @@ -106,10 +106,10 @@ Result: ![Example2 screenshot](../images/widgetlayout1.png) -### Use an `wibox.layout.align` layout +### Use a `wibox.layout.align` layout The `wibox.layout.align` is a little different. While most layouts will -ignore any `nil` lines, the `align` layout rely on them so `left`, `middle` -and `right` can be defined +ignore any `nil` lines, the `align` layout relies on them so `left`, `middle` +and `right` can be defined. Code: @@ -144,7 +144,7 @@ Code: Result: ![Example4 screenshot](../images/widgetlayout2.png) -For more information about how to draw widgets, refer to the `Cairo` api: +For more information about how to draw widgets, refer to the `Cairo` API: * [Path](http://cairographics.org/manual/cairo-Paths.html) * [Context](http://cairographics.org/manual/cairo-cairo-t.html) @@ -177,24 +177,24 @@ Code: ### Accessing widgets For each widget or container, it is possible to add an `identifier` attribute -so the widget can be accessed later. +so that it can be accessed later. -Widgets defined using `setup` can be access by 3 means: +Widgets defined using `setup` can be accessed using these methods: -* Avoid the issue by using externally created widgets -* Use `my_wibox.my_first_widget.my_second_widget` style access -* Use JavaScript like `my_wibox:get_children_by_id("my_second_widget")[1]` +* Avoiding the issue by using externally created widgets +* Using `my_wibox.my_first_widget.my_second_widget` style access +* Using JavaScript like `my_wibox:get_children_by_id("my_second_widget")[1]` -The first method mixes the imperative and declarative syntax, but makes the code +The first method mixes the imperative and declarative syntax, and makes the code less readable. The second is a little verbose and only works if every node in -the chain have a valid identifier. The last one doesn't require long paths, +the chain has a valid identifier. The last one doesn't require long paths, but it is not easy to get a specific instance if multiple widgets have the same identifier. -WARNING: The widget identifier must not use reseved name. This include all +WARNING: The widget identifier must not use a reserved name. This includes all method names, existing widget attributes, `layout` and `widget`. Names should -also respect the lua variable name policies (case sensitive, alphanumeric and -underscore characters and non-numeric first character) +also respect the Lua variable conventions (case-sensitive, alphanumeric, +underscore characters and non-numeric first character). Code: @@ -220,10 +220,10 @@ Code: This system is very flexible. Each section attribute (the entries with string keys) is directly linked to the layout or widget API. When setting the -imaginary `myproperty`, it will first check if `set_myproperty` exist. If it +imaginary `myproperty`, it will first check if `set_myproperty` exists. If it doesn't, it will check if there is a `myproperty` method. Finally, it will just set the `mywidget.myproperty` directly in case it is used later or -catched by a lua `metatable` (operator overload). +caught by a Lua `metatable` (operator overload). Code: diff --git a/docs/05-awesomerc.md.lua b/docs/05-awesomerc.md.lua index 9e41f88b6..139dfb817 100644 --- a/docs/05-awesomerc.md.lua +++ b/docs/05-awesomerc.md.lua @@ -4,7 +4,7 @@ local f = io.open(filename, "w") f:write[[# Default configuration file documentation -This document explain the default `rc.lua` file provided by Awesome. +This document explains the default `rc.lua` file provided by Awesome. ]] @@ -13,9 +13,9 @@ This document explain the default `rc.lua` file provided by Awesome. local sections = {} sections.DOC_REQUIRE_SECTION = [[ -Awesome API is distributed across many libraries (also called modules). +The Awesome API is distributed across many libraries (also called modules). -Here is the modules being imported: +Here are the modules that we import: @@ -30,27 +30,28 @@ Here is the modules being imported: sections.DOC_ERROR_HANDLING = [[ Awesome is a window managing framework. It allows its users great (ultimate?) -flexibility. However, it also allows the user to write invalid code. There is -multiple "levels" of problems: +flexibility. However, it also allows the user to write invalid code. Here's a +non-exhaustive list of possible errors: * Syntax: There is an `awesome -k` option available in the command line to - check this. Awesome cannot start with an invalid `rc.lua` + check the configuration file. Awesome cannot start with an invalid `rc.lua` * Invalid APIs and type errors: Lua is a dynamic language. It doesn't have much support for static/compile time checks. There is the `luacheck` utility to help find some categories of errors. Those errors will cause Awesome to - "drop" the current call stack and start over. Note that if the config cannot - reach the end of the `rc.lua` without errors, it will fallback to the + "drop" the current call stack and start over. Note that if it cannot + reach the end of the `rc.lua` without errors, it will fall back to the original file. - * Invalid logic: It is possible to write fully valid code that will leave + * Invalid logic: It is possible to write fully valid code that will render Awesome unusable (like an infinite loop or blocking commands). In that case, the best way to debug this is either using `print()` or using `gdb`. For this, see the [Debugging tips Readme section](../documentation/01-readme.md.html) - * Deprecated APIs: Awesome API is not frozen for eternity. While after a - decade and recent changes to enforce consistency, it doesn't change as much, - it will likely be changed in the future. When possible, changes wont cause - errors but will instead print a deprecation message in Awesome logs. Those - logs are placed in various places depending on the distribution. By default, - Awesome will print this on stderr and stdout. + * Deprecated APIs: The Awesome API is not frozen for eternity. After a decade + of development and recent changes to enforce consistency, it hasn't + changed much. This doesn't mean it won't change in the future. Whenever + possible, changes won't cause errors but will instead print a deprecation + message in the Awesome logs. These logs are placed in various places + depending on the distribution. By default, Awesome will print errors on + `stderr` and `stdout`. ]] diff --git a/docs/16-using-cairo.md b/docs/16-using-cairo.md index 227e40ea7..e2f5329b1 100644 --- a/docs/16-using-cairo.md +++ b/docs/16-using-cairo.md @@ -1,7 +1,7 @@ # Using Cairo and LGI -These days, Awesome interface is mostly based on a library called LGI. It allows -to access C libraries such as GTK, GLib, Cairo, Pango, PangoCairo and RSVG using +These days, Awesome's interface is mostly based on a library called LGI. It provides +access to C libraries such as GTK, GLib, Cairo, Pango, PangoCairo and RSVG using Lua code without having to write actual "glue" C code. This is done using the GObject-introspection framework. The main advantage is @@ -130,7 +130,7 @@ applying operations. ### Cairo in Awesome All of Awesome's `wibox`es, `awful.wibar`s, `gears.wallpaper`s and -`awful.titlebar`s contain a Cairo surfaces, which can be accessed through the +`awful.titlebar`s contain Cairo surfaces, which can be accessed through the `drawin` API. This allows widgets to use the Cairo context directly. See the [declarative layout system](../documentation/03-declarative-layout.md.html) diff --git a/docs/89-NEWS.md b/docs/89-NEWS.md index a270f0051..cdaeda4e1 100644 --- a/docs/89-NEWS.md +++ b/docs/89-NEWS.md @@ -5,15 +5,15 @@
Awesome 4.0 is the first release of the v4 API level, breaking the proven -v3.5 API level after 4 years. This requires to port existing user +v3.5 API level after 4 years. This requires to port the existing user configuration and extensions to the new API. -This document offer an overview of the new features and required changes for +This document offers an overview of the new features and required changes for existing users. ## New features -### Inputs related +### Input #### Mouse move and resize handlers @@ -823,7 +823,7 @@ website, repository and continuous integration system. This move increased our development velocity, number of contributor, visibility count and reduced our infrastructure maintenance cost. -### Test driven development +### Test-driven development Awesome went from 0% to 75% unit test coverage. We now have 4 testing systems:
`gears`Utilities such as color parsing and objects