[doc] Fix some typos, modify a few descriptions

Before awesome 2.3 release, I've decided to look for typos in the
awesome* manpages, here is the result. I've also modified some options'
descriptions that I didn't find very clear, I hope I have not
added/missed too many mistakes as I'm not a native English speaker...

Signed-off-by: Julien Danjou <julien@danjou.info>

awesome-client.1.txt

@@ -19,8 +19,8 @@ via a socket located in the users's HOME directory.
 
 USAGE
 -----
-To determine which socket is to be used, it read the DISPLAY environment variable.
+To determine which socket is to be used, it reads the DISPLAY environment variable.
-awesome-client read commands from standard input.
+awesome-client reads commands from standard input.
 
 When you pipe multiple lines into awesome-client, an empty line will flush already
 collected lines into awesome with an according immediate execution.

awesome-menu.1.txt

@@ -20,14 +20,14 @@ using your files as completion.
 
 USAGE
 -----
-By default, awesome-menu read completion from standard input. If nothing is
+By default, awesome-menu reads completion from standard input. If nothing is
 read, the completion list is built from the current working directory files.
 
-To build a menu with executable program:
+To build a menu with all the executable files of /usr/bin:
 
     ls /usr/bin | awesome-menu -e 'exec ' 'Execute'
 
-To build the same menu with executable run in a terminal window:
+To build the same menu and run the programs in a terminal window:
 
     ls /usr/bin | awesome-menu -e 'xterm -e exec ' 'Execute in terminal'
 
@@ -35,7 +35,7 @@ To build an ssh connection prompt:
 
     cut -d' ' -f1 ~/.ssh/known_hosts | cut -d, -f1 | awesome-menu -e 'xterm -e ssh ' 'ssh to:'
 
-If you do not specify the -e option, result will be printed to standard output.
+If you do not specify the -e option, the result will be sent to standard output.
 You can do things like that:
 
     gzip "$(awesome-menu '"File to gzip')"

awesome-message.1.txt

@@ -15,7 +15,7 @@ DESCRIPTION
 -----------
 
 awesome-message is a tool which will pop up a simple X window with a message
-and optionnaly an icon in front of it.
+and optionally an icon in front of it.
 
 USAGE
 -----

awesome.1.txt

@@ -19,7 +19,7 @@ floating or tiled. Either layout can be applied dynamically, optimizing the
 environment for the application in use and the task performed.
 
 In tiled layout windows are managed in a master and stacking area. The master
-area contains windows which currently need most attention, whereas the
+area contains the windows which currently need most attention, whereas the
 stacking area contains all other windows. In floating layout windows can be
 resized and moved freely. Dialog windows are always managed floating,
 regardless of the layout applied. The spiral and dwindle layout are special cases
@@ -42,9 +42,9 @@ awesome can draw a small border around windows to indicate the focus state.
 OPTIONS
 -------
 -v | --version::
-    Prints version information to standard output, then exits.
+    Print version information to standard output, then exit.
 -h | --help::
-    Prints help information, then exits.
+    Print help information, then exit.
 --config | -c::
     Use an alternate configuration file instead of $HOME/.awesomerc.
 --check | -k::
@@ -113,9 +113,9 @@ DEFAULTS KEY BINDINGS
 *Mod4 \+ Shift \+ l*::
     Decrease number of master windows by 1.
 *Mod4 \+ Control \+ h*::
-    Increase number of column for non-master windows by 1.
+    Increase number of columns for non-master windows by 1.
 *Mod4 \+ Control \+ l*::
-    Decrease number of column for non-master windows by 1.
+    Decrease number of columns for non-master windows by 1.
 *Mod4 + Escape*::
     View previously selected tag.
 *Mod4 + Left*::

awesome.c

@@ -103,7 +103,7 @@ xerrorstart(Display * disp __attribute__ ((unused)),
     eprint("another window manager is already running\n");
 }
 
-/** Quits awesome.
+/** Quit awesome.
  * \param screen Screen ID
  * \param arg nothing
  * \ingroup ui_callback

awesomerc.5.txt

@@ -39,7 +39,8 @@ OPTIONS
 *awesomerc* contains 5 global sections: *screen*, *rules*, *keys*, *mouse* and *menu* which
 are described here.
 
-All this sections contain options which may be string, integer, float, or even sections again.
+All these sections contain options which may be strings, integers, floats, or
+even sections again.
 
 include::optsdocgen.txt[]
 
@@ -100,7 +101,7 @@ Simple textbox example
         fi
     done
 
-    Note: What we're saying is "awesome-client, tell the bottom status bar's
+    Note: What we are saying is "awesome-client, tell the bottom status bar's
     widget named 'clock' to set it's 'text' property to date's output".
 
 5. Make your ~/bin/awesome-clock executable
@@ -114,7 +115,7 @@ Simple textbox example
 
 7. Restart awesome
 
-8. If your didn't get what you were expecting, take a look at
+8. If you did not get what you were expecting, take a look at
    ~/.xsession-errors or the terminal where X got started.
 ..............................................
 
@@ -174,7 +175,7 @@ Simple progressbar example
     done
 
 
-    Note: What we're saying is "awesome-client, tell the bottom status bar's
+    Note: What we are saying is "awesome-client, tell the bottom status bar's
     widget named 'diskusage' to set it's 'data' property named 'disk' to
     ${usage}."
 
@@ -189,13 +190,13 @@ $ chmod a+x ~/bin/awesome-diskusage
 
 7. Restart awesome
 
-8. If your didn't get what you were expecting, take a look at
+8. If you did not get what you were expecting, take a look at
    ~/.xsession-errors or the terminal where X got started.
 ..............................................
 
 AWESOMERC SKELETON
 ------------------
-Following skeleton lists all available configuration options in *awesomerc*.
+The following skeleton lists all available configuration options in *awesomerc*.
 
 ..........................
 include::rcskeletongen.txt[]

client.c

@@ -772,7 +772,7 @@ client_isvisible(Client *c, int screen)
     return False;
 }
 
-/** Set selected client transparency.
+/** Set the transparency of the selected client.
  * Argument should be a floating between 0 and 100, -1 to disable.
  * \param screen Screen ID
  * \param arg unused arg
@@ -848,7 +848,7 @@ client_find_visible(Client *sel, Bool reverse)
     return next;
 }
 
-/** Swap currently focused client with previous visible.
+/** Swap the currently focused client with the previous visible one.
  * \param screen Screen ID
  * \param arg nothing
  * \ingroup ui_callback
@@ -865,7 +865,7 @@ uicb_client_swapprev(int screen __attribute__ ((unused)), char *arg __attribute_
     }
 }
 
-/** Swap currently focused client with next visible.
+/** Swap the currently focused client with the next visible one.
  * \param screen Screen ID
  * \param arg nothing
  * \ingroup ui_callback
@@ -883,7 +883,7 @@ uicb_client_swapnext(int screen __attribute__ ((unused)), char *arg __attribute_
 }
 
 /** Move and resize a client. Argument should be in format "x y w h" with
- * absolute (1, 20, 300, ...) or relatives (+10, -200, ...) values.
+ * absolute (1, 20, 300, ...) or relative (+10, -200, ...) values.
  * \param screen Screen ID
  * \param arg x y w h
  * \ingroup ui_callback
@@ -1081,7 +1081,7 @@ uicb_client_togglehorizontalmax(int screen, char *arg __attribute__ ((unused)))
     }
 }
 
-/** Set the client the master window.
+/** Move the client to the master area.
  * \param screen Screen ID
  * \param arg Unused
  * \ingroup ui_callback
@@ -1106,7 +1106,7 @@ uicb_client_zoom(int screen, char *arg __attribute__ ((unused)))
     }
 }
 
-/** Setfocus to the next visible client in the stack.
+/** Give focus to the next visible client in the stack.
  * \param screen Screen ID
  * \param arg Unused
  * \ingroup ui_callback
@@ -1120,7 +1120,7 @@ uicb_client_focusnext(int screen, char *arg __attribute__ ((unused)))
         client_focus(next, screen, True);
 }
 
-/** Setfocus to the previous visible client in the stack.
+/** Give focus to the previous visible client in the stack.
  * \param screen Screen ID
  * \param arg Unused
  * \ingroup ui_callback
@@ -1166,7 +1166,7 @@ uicb_client_setscratch(int screen, char *arg __attribute__ ((unused)))
     globalconf.screens[screen].need_arrange = True;
 }
 
-/** Toggle scratch client visibility.
+/** Toggle the scratch client's visibility.
  * \param screen screen number
  * \param arg unused argument
  * \ingroup ui_callback

common/configopts.c

@@ -166,9 +166,9 @@ cfg_opt_t style_opts[] =
     CFG_STR((char *) "fg", NULL, CFGF_NONE),
     /** Shadow color. */
     CFG_STR((char *) "shadow", NULL, CFGF_NONE),
-    /** Shadow offset in pixel. */
+    /** Shadow offset in pixels. */
     CFG_INT((char *) "shadow_offset", 0xffffffff, CFGF_NONE),
-    /** Font being used */
+    /** Font to use. */
     CFG_STR((char *) "font", NULL, CFGF_NONE),
     CFG_AWESOME_END()
 };
@@ -177,7 +177,7 @@ cfg_opt_t styles_opts[] =
 {
     /** Normal style. */
     CFG_SEC((char *) "normal", style_opts, CFGF_NONE),
-    /** Style used for window which has focus. */
+    /** Style used for the focused window. */
     CFG_SEC((char *) "focus", style_opts, CFGF_NONE),
     /** Style used for windows with urgency hint. */
     CFG_SEC((char *) "urgent", style_opts, CFGF_NONE),
@@ -203,15 +203,15 @@ cfg_opt_t titlebar_opts[] =
 /** This section defines general options. */
 cfg_opt_t general_opts[] =
 {
-    /** The border size of windows in pixel. */
+    /** The border size of windows in pixels. */
     CFG_INT((char *) "border", 1, CFGF_NONE),
-    /** The number of pixel to snap when moving floating windows. */
+    /** The number of pixels to snap when moving floating windows. */
     CFG_INT((char *) "snap", 8, CFGF_NONE),
     /** Use resize hints when resizing tiled windows. Can produce gaps between windows. */
     CFG_BOOL((char *) "resize_hints", cfg_true, CFGF_NONE),
-    /** Enable sloppy focus, also known as focus follow mouse. */
+    /** Enable sloppy focus, also known as focus follows mouse. */
     CFG_BOOL((char *) "sloppy_focus", cfg_true, CFGF_NONE),
-    /** Enable raise if mouse give focus. */
+    /** Raise the window if it is given focus with the mouse. */
     CFG_BOOL((char *) "sloppy_focus_raise", cfg_false, CFGF_NONE),
     /** New windows become master windows. */
     CFG_BOOL((char *) "new_become_master", cfg_true, CFGF_NONE),
@@ -358,7 +358,7 @@ cfg_opt_t widget_graph_data_opts[] =
 {
     /** Value of a full graph. */
     CFG_FLOAT((char *) "max", 100.0f, CFGF_NONE),
-    /** Scale graph when values are bigger than 'max' */
+    /** Scale graph when values are bigger than 'max'. */
     CFG_BOOL((char *) "scale", cfg_false, CFGF_NONE),
     /** Foreground color. */
     CFG_STR((char *) "fg", NULL, CFGF_NONE),
@@ -366,7 +366,7 @@ cfg_opt_t widget_graph_data_opts[] =
     CFG_STR((char *) "fg_center", NULL, CFGF_NONE),
     /** Foreground color at the end of a bar (as gradient). */
     CFG_STR((char *) "fg_end", NULL, CFGF_NONE),
-    /** fg, fg_center and fg_end defines a vertical gradient */
+    /** fg, fg_center and fg_end define a vertical gradient. */
     CFG_BOOL((char *) "vertical_gradient", cfg_false, CFGF_NONE),
     /**  Draw style. */
     CFG_STR((char *) "draw_style", (char *) "bottom", CFGF_NONE),
@@ -452,9 +452,9 @@ cfg_opt_t statusbar_opts[] =
 {
     /** Statusbar position. */
     CFG_POSITION((char *) "position", (char *) "top", CFGF_NONE),
-    /** Statusbar height. Set 0 for auto. */
+    /** Statusbar height. Set to 0 for auto. */
     CFG_INT((char *) "height", 0, CFGF_NONE),
-    /** Statusbar width. Set 0 for auto. */
+    /** Statusbar width. Set to 0 for auto. */
     CFG_INT((char *) "width", 0, CFGF_NONE),
     /** Textbox widget(s). */
     CFG_SEC((char *) "textbox", widget_textbox_opts, CFGF_TITLE | CFGF_MULTI | CFGF_NO_TITLE_DUPES),
@@ -483,13 +483,13 @@ cfg_opt_t tag_opts[] =
     CFG_STR((char *) "layout", (char *) "tile", CFGF_NONE),
     /** Default master width factor for this tag. */
     CFG_FLOAT((char *) "mwfact", 0.5, CFGF_NONE),
-    /** Default number of master window for this tag. */
+    /** Default number of master windows for this tag. */
     CFG_INT((char *) "nmaster", 1, CFGF_NONE),
-    /** Default number of window column for this tag. */
+    /** Default number of window columns for this tag. */
     CFG_INT((char *) "ncol", 1, CFGF_NONE),
     CFG_AWESOME_END()
 };
-/** This section define tags options. */
+/** This section defines tags options. */
 cfg_opt_t tags_opts[] =
 {
     /** Available tag(s). */
@@ -614,18 +614,18 @@ cfg_opt_t mouse_opts[] =
 {
     /** Mouse bindings for the root window. */
     CFG_SEC((char *) "root", mouse_generic_opts, CFGF_MULTI),
-    /** Mouse bindings for the clients window. */
+    /** Mouse bindings for the clients' window. */
     CFG_SEC((char *) "client", mouse_generic_opts, CFGF_MULTI),
-    /** Mouse bindings for the clients titlebar. */
+    /** Mouse bindings for the clients' titlebar. */
     CFG_SEC((char *) "titlebar", mouse_generic_opts, CFGF_MULTI),
     CFG_AWESOME_END()
 };
 /** This section defines menu options. */
 cfg_opt_t menu_opts[] =
 {
-    /** Width of the menu. Set 0 for auto. */
+    /** Width of the menu. Set to 0 for auto. */
     CFG_INT((char *) "width", 0, CFGF_NONE),
-    /** Height of the menu. Set 0 for auto. */
+    /** Height of the menu. Set to 0 for auto. */
     CFG_INT((char *) "height", 0, CFGF_NONE),
     /** X coordinate, do not set for auto. */
     CFG_INT((char *) "x", 0xffffffff, CFGF_NONE),
@@ -638,7 +638,7 @@ cfg_opt_t menu_opts[] =
 /** This section defines global awesome options. */
 cfg_opt_t awesome_opts[] =
 {
-    /** The screens section. Make one for each of your screen. */
+    /** The screens section. Make one for each of your screens. */
     CFG_SEC((char *) "screen", screen_opts, CFGF_TITLE | CFGF_MULTI | CFGF_NO_TITLE_DUPES),
     /** The rules section. This allows specific options for specific windows. */
     CFG_SEC((char *) "rules", rules_opts, CFGF_NONE),

focus.c

@@ -99,7 +99,7 @@ focus_get_current_client(int screen)
     return sel;
 }
 
-/** Jump back in focus history stack.
+/** Jump back in the focus history stack.
  * Set arg to 0 for previous, -1 for previous of previous, etc.
  * \param screen Screen ID
  * \param arg Integer argument
@@ -127,7 +127,7 @@ uicb_focus_history(int screen, char *arg)
     }
 }
 
-/** Focus visible client by its name.
+/** Focus one of the visible clients by its name.
  * \param screen screen id
  * \param arg client's name
  * \ingroup ui_callback

layout.c

@@ -122,7 +122,7 @@ layout_get_current(int screen)
     return l;
 }
 
-/** Set layout for current tag.
+/** Set the layout of the current tag.
  * Argument must be a relative or absolute integer of available layouts.
  * \param screen Screen ID
  * \param arg Layout specifier

mouse.c

@@ -125,7 +125,7 @@ mouse_resizebar_draw(DrawCtx *ctx, style_t style, SimpleWindow *sw, area_t geome
     simplewindow_refresh_drawable(sw, sw->phys_screen);
 }
 
-/** Move client with the mouse.
+/** Move the focused window with the mouse.
  * \param screen Screen ID
  * \param arg Unused
  * \ingroup ui_callback
@@ -244,7 +244,7 @@ uicb_client_movemouse(int screen, char *arg __attribute__ ((unused)))
     }
 }
 
-/** Resize client with the mouse.
+/** Resize the focused window with the mouse.
  * \param screen Screen ID
  * \param arg Unused
  * \ingroup ui_callback

statusbar.c

@@ -300,7 +300,7 @@ statusbar_toggle(Statusbar *statusbar)
     globalconf.screens[statusbar->screen].need_arrange = True;
 }
 
-/** Toggle statusbar on or off.
+/** Toggle the statusbar on or off.
  * Argument must be a statusbar name, or no argument for all statusbars.
  * \param screen Screen ID
  * \param arg statusbar name

tag.c

@@ -222,7 +222,7 @@ tags_get_current(int screen)
     return tags;
 }
 
-/** Tag focused client with tag.
+/** Tag the focused client with the given tag.
  * \param screen Screen ID
  * \param arg Tag name
  * \ingroup ui_callback
@@ -257,7 +257,7 @@ uicb_client_tag(int screen, char *arg)
             tag_client(sel, tag);
 }
 
-/** Toggle a tag on focused client.
+/** Toggle a tag on the focused client.
  * \param screen virtual screen id
  * \param arg tag number
  * \ingroup ui_callback
@@ -306,7 +306,7 @@ uicb_client_toggletag(int screen, char *arg)
     }
 }
 
-/** Add a tag to the list of viewed tags.
+/** Toggle the visibility of a tag.
  * \param screen Screen ID
  * \param arg Tag name
  * \ingroup ui_callback
@@ -403,7 +403,7 @@ tag_view(Tag *tag, Bool view)
     globalconf.screens[tag->screen].need_arrange = True;
 }
 
-/** View tag.
+/** View only this tag.
  * \param screen Screen ID
  * \param arg tag to view
  * \ingroup ui_callback
@@ -420,7 +420,7 @@ uicb_tag_view(int screen, char *arg)
             tag_view(tag, True);
 }
 
-/** View previously selected tags
+/** View the previously selected tags.
  * \param screen Screen ID
  * \param arg unused
  * \ingroup ui_callback
@@ -434,7 +434,7 @@ uicb_tag_prev_selected(int screen, char *arg __attribute__ ((unused)))
         tag_view(tag, tag->was_selected);
 }
 
-/** View next tag.
+/** View the next tag.
  * \param screen Screen ID
  * \param arg unused
  * \ingroup ui_callback
@@ -452,7 +452,7 @@ uicb_tag_viewnext(int screen, char *arg __attribute__ ((unused)))
     p_delete(&curtags);
 }
 
-/** View previous tag.
+/** View the previous tag.
  * \param screen Screen ID
  * \param arg unused
  * \ingroup ui_callback

titlebar.c

@@ -443,7 +443,7 @@ titlebar_update_geometry(Client *c, area_t geometry)
     titlebar_draw(c);
 }
 
-/** Toggle window titlebar visibility.
+/** Toggle the visibility of the focused window's titlebar.
  * \param screen screen number (unused)
  * \param arg unused argument
  * \ingroup ui_callback

uicb.c

@@ -46,7 +46,7 @@ extern AwesomeConf globalconf;
 
 #include "uicbgen.h"
 
-/** Restart awesome with the current command line
+/** Restart awesome with the current command line.
  * \param screen ID
  * \param arg arg (unused)
  * \ingroup ui_callback
@@ -57,7 +57,7 @@ uicb_restart(int screen, char *arg __attribute__ ((unused)))
     uicb_exec(screen, globalconf.argv);
 }
 
-/** Execute another process, replacing the current instance of Awesome
+/** Execute another process, replacing the current instance of awesome.
  * \param screen Screen ID
  * \param cmd Command
  * \ingroup ui_callback
@@ -92,7 +92,7 @@ uicb_exec(int screen __attribute__ ((unused)), char *cmd)
     p_delete(&path);
 }
 
-/** Spawn another process
+/** Spawn another process.
  * \param screen Screen ID
  * \param arg Command
  * \ingroup ui_callback

widget.c

@@ -174,7 +174,7 @@ widget_invalidate_cache(int screen, int flags)
                 widget->cache.needs_update = True;
 }
 
-/** Send command to widgets.
+/** Send commands to widgets.
  * \param screen Screen ID
  * \param arg Widget command. Syntax depends on specific widget.
  * \ingroup ui_callback