Merge pull request #3307 from sclu1034/feature/docs

Various docs improvements

docs/07-my-first-awesome.md

@@ -25,10 +25,10 @@ have not opened any programs. On the top right you see the time/date and a
 symbol showing the current layout. You can also click on the symbol to change
 the active layout.
 
-One of the big advantages of Awesome over other tiling window managers is its good
+One of the big advantages of Awesome over other tiling window managers is its
-mouse support. Awesome can act as a full floating window manager (almost like
+good mouse support. Awesome can act as a full floating window manager (almost
-openbox) if you want. For this basic tutorial we will mainly focus on keyboard
+like openbox) if you want. For this basic tutorial we will mainly focus on
-control, so let's learn some key bindings now.
+keyboard control, so let's learn some key bindings now.
 
 Let's open a terminal: press *Mod4+Enter*. Mod4 is your "Windows key", the key
 between Ctrl and Alt. You can change the modkey if you want, but we'll get to
@@ -65,20 +65,18 @@ overview now also provides a cheat sheet for controlling Vim.
 
 ## Change the theme
 
-Awesome has four themes you can choose from: *default*, *sky*, *xresources*, and
+Awesome has four builtin themes you can choose from: *default*, *sky*,
-*zenburn*.
+*xresources*, and *zenburn*.
 
-To change the theme, open your rc.lua and edit this line near the beginning of
+To change the theme, open your `rc.lua`, find this line near the beginning of
-the file:
+the file, and change `default` to one of the other values mentioned:
 
     beautiful.init(gears.filesystem.get_themes_dir() .. "default/theme.lua")
 
-For this tutorial we will stick with the default theme.
+However, for this tutorial we will copy and customize the default theme.
-
+Copy `/usr/share/awesome/themes/default/theme.lua` to `~/.config/awesome/`
-Now we will customize the theme. Copy
+and change the line shown above in `rc.lua` like this. Make sure to replace
-`/usr/share/awesome/themes/default/theme.lua` to `~/.config/awesome/` and change
+`USER` with your user name.
-the above line in your theme like this (remember to replace `USER` with your
-user name):
 
     beautiful.init("/home/USER/.config/awesome/theme.lua")
 
@@ -89,7 +87,9 @@ this line in your theme file:
 
     theme.wallpaper = themes_path.."default/background.png"
 
-The default uses a path relative to `themes_path` by using the `..` operator to join two strings together. To just set it to an absolute path for example, you could do:
+The default uses a path relative to `themes_path` by using the `..` operator to
+join two strings together. To just set it to an absolute path for example,
+you could do:
 
     theme.wallpaper = "/usr/share/backgrounds/my-awesome-wallpaper.png"
 

lib/gears/table.lua

@@ -230,14 +230,16 @@ end
 -- `first_index` has to be specified.
 --
 -- @tparam table t The input table.
--- @param value A value from the table.
+-- @param value The start value. Must be an element of the input table `t`.
--- @tparam[opt=1] number step_size How many element forward (or backward) to pick.
+-- @tparam[opt=1] number step_size The amount to increment the index by.
--- @tparam[opt=nil] function filter An optional function. When it returns
+--   When this is negative, the function will cycle through the table backwards.
---  `false`, the element are skipped until a match if found. It takes the value
+-- @tparam[opt=nil] function filter An optional filter function. It receives a
---  as its sole parameter.
+--   value from the table as parameter and should return a boolean. If it
+--   returns `false`, the value is skipped and `cycle_value` tries the next one.
 -- @tparam[opt=1] number start_at Where to start the lookup from.
--- @return The value. If no element match, then `nil` is returned.
+-- @return The next eligible value. If no value matches, `nil` is returned.
--- @treturn number|nil The element (if any) key.
+-- @treturn number|nil If a value is found, this is its index within the input
+--   table.
 -- @staticfct gears.table.cycle_value
 function gtable.cycle_value(t, value, step_size, filter, start_at)
     local k = gtable.hasitem(t, value, true, start_at)
@@ -400,3 +402,5 @@ function gtable.map(f, tbl)
 end
 
 return gtable
+
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80