From 8bd0da53159338b5a446ceccc812feef14e3279c Mon Sep 17 00:00:00 2001 From: Enric Morales Date: Tue, 13 Dec 2016 23:31:25 +0100 Subject: [PATCH 1/6] Fix typos in declarative layout docs --- docs/03-declarative-layout.md | 46 +++++++++++++++++------------------ 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/docs/03-declarative-layout.md b/docs/03-declarative-layout.md index c43dee18..2e49f207 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 widgets 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,9 +106,9 @@ 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` +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,23 +177,23 @@ 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 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 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 +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: From d7a0486da9a142aa6439136268adc2aa796114a7 Mon Sep 17 00:00:00 2001 From: Enric Morales Date: Wed, 14 Dec 2016 15:37:34 +0100 Subject: [PATCH 2/6] `awesomerc.md.lua` typos and grammar --- docs/05-awesomerc.md.lua | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/docs/05-awesomerc.md.lua b/docs/05-awesomerc.md.lua index 9e41f88b..c0268a12 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-extensive 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 doesn't 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`. ]] From c2b265f3bada91d6521226e22386946a3e1d63e1 Mon Sep 17 00:00:00 2001 From: Enric Morales Date: Wed, 14 Dec 2016 15:41:01 +0100 Subject: [PATCH 3/6] Correct minor typos in 16-using-cairo.md --- docs/16-using-cairo.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/16-using-cairo.md b/docs/16-using-cairo.md index 227e40ea..dbccd648 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 interface is mostly based on a library called LGI. It provides +access 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) From 2338f84369a35cfb4d39012da7ca07546ca42320 Mon Sep 17 00:00:00 2001 From: Enric Morales Date: Wed, 14 Dec 2016 15:53:13 +0100 Subject: [PATCH 4/6] Should be non-exhaustive instead of non-extensive --- docs/05-awesomerc.md.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/05-awesomerc.md.lua b/docs/05-awesomerc.md.lua index c0268a12..ee9ec896 100644 --- a/docs/05-awesomerc.md.lua +++ b/docs/05-awesomerc.md.lua @@ -31,7 +31,7 @@ Here are the modules that we import: 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. Here's a -non-extensive list of possible errors: +non-exhaustive list of possible errors: * Syntax: There is an `awesome -k` option available in the command line to check the configuration file. Awesome cannot start with an invalid `rc.lua` From 4bed437d50b14746014bb460d5ef89758d7ff52c Mon Sep 17 00:00:00 2001 From: Enric Morales Date: Wed, 14 Dec 2016 16:26:00 +0100 Subject: [PATCH 5/6] Fix some minor typos in 89-NEWS.md --- docs/89-NEWS.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/89-NEWS.md b/docs/89-NEWS.md index a270f005..cdaeda4e 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: From 530e64e9ec9755af34c3fd7d24ef7a287fe0dd5a Mon Sep 17 00:00:00 2001 From: Enric Morales Date: Fri, 16 Dec 2016 22:02:35 +0100 Subject: [PATCH 6/6] Fix more typos --- docs/03-declarative-layout.md | 10 +++++----- docs/05-awesomerc.md.lua | 2 +- docs/16-using-cairo.md | 4 ++-- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/03-declarative-layout.md b/docs/03-declarative-layout.md index 2e49f207..c0b34e5b 100644 --- a/docs/03-declarative-layout.md +++ b/docs/03-declarative-layout.md @@ -17,7 +17,7 @@ Awesome provides 2 collections of widgets: ### Containers -A container is a widgets that wraps another widget. It can be used to add +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@ @@ -109,7 +109,7 @@ Result: ### 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 relies on them so `left`, `middle` -and `right` can be defined +and `right` can be defined. Code: @@ -177,7 +177,7 @@ Code: ### Accessing widgets For each widget or container, it is possible to add an `identifier` attribute -so that it accessed later. +so that it can be accessed later. Widgets defined using `setup` can be accessed using these methods: @@ -191,10 +191,10 @@ 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 reserved name. This includes 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 conventions (case-sensitive, alphanumeric, -underscore characters and non-numeric first character) +underscore characters and non-numeric first character). Code: diff --git a/docs/05-awesomerc.md.lua b/docs/05-awesomerc.md.lua index ee9ec896..139dfb81 100644 --- a/docs/05-awesomerc.md.lua +++ b/docs/05-awesomerc.md.lua @@ -46,7 +46,7 @@ non-exhaustive list of possible errors: 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: The Awesome API is not frozen for eternity. After a decade - of development and recent changes to enforce consistency, it doesn't hasn't + 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 diff --git a/docs/16-using-cairo.md b/docs/16-using-cairo.md index dbccd648..e2f5329b 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 provides -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
`gears`Utilities such as color parsing and objects