Merge pull request #1272 from kiike/fix-docs-grammar

Fix typos, grammar in docs

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:
 

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:
 
 <table class='widget_list' border=1>
   <tr><td>`gears`</td><td>Utilities such as color parsing and objects</td></tr>
@@ -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`.
 
 
 ]]

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)

docs/89-NEWS.md

@@ -5,15 +5,15 @@
 <center> <img src="../images/AUTOGEN_wibox_logo_logo_and_name.svg" /> </center>
 
 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: