From 86ca5281f489c5183069722961c88f275e534a8a Mon Sep 17 00:00:00 2001 From: Uli Schlachter Date: Sat, 30 Apr 2016 11:54:16 +0200 Subject: [PATCH 1/2] Import some FAQ This is the current version of the FAQ in the wiki converted to markdown, but some IMO bogus content was stripped (e.g. references to awesome being a non-reparenting WM). Signed-off-by: Uli Schlachter --- docs/90-FAQ.md | 392 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/config.ld | 1 + 2 files changed, 393 insertions(+) create mode 100644 docs/90-FAQ.md diff --git a/docs/90-FAQ.md b/docs/90-FAQ.md new file mode 100644 index 000000000..9f2a40606 --- /dev/null +++ b/docs/90-FAQ.md @@ -0,0 +1,392 @@ +# FAQ + +## General + +### Why call it awesome? + +The name *awesome* comes from the English word *awesome* often used by the +character [Barney Stinson](http://en.wikipedia.org/wiki/Barney_Stinson) +from the TV series HIMYM. + + +## Configuration + +### How to change the default window management layout? + +In the default configuration file one layout is set for all tags, it happens to +be the `floating` layout. You can change that by editing your tag creation +loop in the `rc.lua`: + + -- Each screen has its own tag table. + awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, s, awful.layout.layouts[1]) + +Notice that all tags will use the 1st layout from your layouts table, which is +defined right before tags are created. Just change the layout number in order to +use another window management layout. + +#### How to change the name and layout per tag? + +You can modify your tag section, there are many possible implementations, here +is a simple one: + +At the beginning of `rc.lua`: + + layouts = awful.layout.layouts + tags = { + names = { "www", "editor", "mail", "im", "rss", 6, 7, "rss", "media"}, + layout = { layouts[2], layouts[1], layouts[1], layouts[4], layouts[1], + layouts[6], layouts[6], layouts[5], layouts[6] + }} + +Then later to create tags: + + tags[s] = awful.tag(tags.names, s, tags.layout) + +#### How to setup different tags and layouts per screen? + +Another demonstration for your tag section: + +At the beginning of `rc.lua`: + + layouts = awful.layout.layouts + tags = { + settings = { + { names = { "www", "editor", "mail", "im" }, + layout = { layouts[2], layouts[1], layouts[1], layouts[4] } + }, + { names = { "rss", 6, 7, "media" }, + layout = { layouts[3], layouts[2], layouts[2], layouts[5] } + }}} + +Then later to create tags: + + tags[s] = awful.tag(tags.settings[s.index].names, s, tags.settings[s.index].layout) + +#### How to show only non-empty tags? + +You can use a filter when creating taglist. + +Possible filters: + +* `awful.widget.taglist.filter.all` - default, show all tags in taglist +* `awful.widget.taglist.filter.noempty` - show only non-empty tags in taglist (like dynamic tags) +* `awful.widget.taglist.filter.selected` - show only selected tags in taglist + +To show only non-empty tags on taglist: + + mytaglist[s] = awful.widget.taglist(s, awful.widget.taglist.filter.noempty, mytaglist.buttons) + +### How to autostart applications? + +The traditional way is to use the `~/.xinitrc` file. + +### How to lock the screen when I am away? + +You can use any screen locking utility: `xlock`, `xscreensaver`, `slock`, `kscreenlocker`... + +Example key binding for your `globalkeys`: + + awful.key({ modkey }, "F12", function () awful.spawn{ "xlock" } end) + +### How to execute a shell command? + +If you want to execute a shell command or need to execute a command that uses +redirection, pipes and so on, do not use the `awful.spawn` function but +`awful.util.spawn_with_shell`. Here is an example: + + awful.key({ modkey }, "F10", function () awful.util.spawn_with_shell("cal -m | xmessage -timeout 10 -file -") end) + +On zsh, any changes to $PATH you do in `~/.zshrc` will not be picked up (because +this is only run for interactive shells). Use `~/.zshenv` instead to make +additions to the path you want to use in awesome. + +### How to remove gaps between windows? + +You can add `size_hints_honor = false` to the `properties` section in your +`awful.rules.rules` table in your `rc.lua'. It will match and apply this rule to +all clients. + +If you want to know what are size hints it has been debated many times on the +mailing list, so you can read the explanation: +[http://www.mail-archive.com/awesome@naquadah.org/msg01767.html](http://www.mail-archive.com/awesome@naquadah.org/msg01767.html) + +This might cause flickering with some non-ICCCM conforming applications (e.g. +Lilyterm) which try to override the size that the window manager assigned them. + +### How to add an application switcher? + +You can use the Clients Menu as an application switcher. By default it will open +if you right-click on your taskbar, but you may also bind it to a key +combination. Here is an example, toggled by "Alt + Esc", that you can add to +your `globalkeys`: + + awful.key({ "Mod1" }, "Escape", function () + -- If you want to always position the menu on the same place set coordinates + awful.menu.menu_keys.down = { "Down", "Alt_L" } + awful.menu.clients({theme = { width = 250 }}, { keygrabber=true, coords={x=525, y=330} }) + end), + + +### How to control titlebars? + +To disable titlebars on all clients remove the `titlebars_enabled=true` from the +`awful.rules.rules` table in your config. If you want a titlebar only on +certain clients, you can use `awful.rules` to set this property only for certain +clients. + +### How to toggle titlebar visibility? + +You can use a `clientkeys` binding.: + + awful.key({ modkey, "Shift" }, "t", awful.titlebar.toggle), + +### How to toggle wibox visibility? + +Add the following key binding to your `globalkeys`: + + awful.key({ modkey }, "b", function () + mywibox[mouse.screen].visible = not mywibox[mouse.screen].visible + end), + +### How to toggle clients floating state? + +The default `rc.lua` already has a key binding for this, it is "Mod4 + Control + +Space". You can easily change it to something easier like "Mod4 + f" or "Mod4 + +Shift + f". + + awful.key({ modkey, "Shift" }, "f", awful.client.floating.toggle ), + +#### Why some floating clients can not be tiled? + +If some of your applications (i.e. Firefox, Opera...) are floating but you can't +tile them, and they behave weird (can not be tagged, are always on top...) do +not panic. They are merely maximized from your last window manager, or from +their last invocation. The default key binding to toggle maximized state is +"Mod4 + m". + +You can ensure no application ever starts maximized in the first rule of your +`awful.rules.rules` table, which applies to all clients, by adding: + + -- Search for this rule, + keys = clientkeys, + + -- add the following two: + maximized_vertical = false, + maximized_horizontal = false, + +### How to move and resize floaters with the keyboard? + +You can use the `awful.client.moveresize` function. The following `clientkeys` +example will move floaters with "Mod4 + Arrow keys" and resize them with "Mod4 + +PgUP/DN" keys: + + awful.key({ modkey }, "Next", function () awful.client.moveresize( 20, 20, -40, -40) end), + awful.key({ modkey }, "Prior", function () awful.client.moveresize(-20, -20, 40, 40) end), + awful.key({ modkey }, "Down", function () awful.client.moveresize( 0, 20, 0, 0) end), + awful.key({ modkey }, "Up", function () awful.client.moveresize( 0, -20, 0, 0) end), + awful.key({ modkey }, "Left", function () awful.client.moveresize(-20, 0, 0, 0) end), + awful.key({ modkey }, "Right", function () awful.client.moveresize( 20, 0, 0, 0) end), + +#### How to resize tiled clients? + +You can use the `awful.tag.incmwfact` function to resize master clients and +`awful.client.incwfact` function to resize slave clients. The following +`globalkeys` example demonstrates this: + + awful.key({ modkey }, "l", function () awful.tag.incmwfact( 0.05) end), + awful.key({ modkey }, "h", function () awful.tag.incmwfact(-0.05) end), + awful.key({ modkey, "Shift" }, "l", function () awful.client.incwfact(-0.05) end), + awful.key({ modkey, "Shift" }, "h", function () awful.client.incwfact( 0.05) end), + +### How to change awesome configuration while it's running? + +You can modify `rc.lua`, but you have to restart awesome for changes to take +effect. The default keybinding for restarting awesome is "Mod4 + Control + r". + +### How to find window's class and other identifiers? + +You can use the `xprop` utility, you are interested in `WM_CLASS` and `WM_NAME` +from its output: + + $ xprop WM_CLASS WM_NAME + +When the cursor changes to "+" click on the client of interest. From the +terminal output you can use the following to match clients in awesome: + + WM_CLASS(STRING) = "smplayer", "Smplayer" + | | + | |--- class + | + |--- instance + + WM_NAME(STRING) = "SMPlayer" + | + |--- name + +You can use the above identifiers (instance, class and name) in your +`awful.rules.rules` table to do matching, tagging and other client manipulation. +See the next FAQ answer for some examples. + +### How to start clients on specific tags and others as floating? + +You can add matching rules to your `awful.rules.rules` table. The default +`rc.lua` already has several examples, but some more can be found in the +@{awful.rules.rules|documentation}. + +### How to start clients as slave windows instead of master? + +You can set windows to open as slave windows by setting rule to match all +clients: + + -- Start windows as slave + { rule = { }, properties = { }, callback = awful.client.setslave } + +### How to use a keycode in a keybinding? + +You can use the format `#XYZ` for keycodes in your bindings. The following +example shows a mapped multimedia/extra key, that's why the modifier is not +present (but it could be): + + awful.key({}, "#160", function () awful.util.spawn("kscreenlocker --forcelock") end), + +### How to add a keyboard layout switcher? + +The `wibox.widget.keyboardlayout` is a widget that shows the current keyboard +layout and allows to change it by clicking on it. + +### How to make windows spawn under the mouse cursor? + +In the default `awful.rules`-rule, the following placement is specified: + + placement = awful.placement.no_overlap+awful.placement.no_offscreen + +You can prepend `awful.placement.under_mouse` to this: + + placement = awful.placement.under_mouse+awful.placement.no_overlap+awful.placement.no_offscreen + +### How to switch to a specific layout in a keybinding? + +You can call the `awful.layout.set()` function, here's an example: + + awful.key({ modkey }, "q", function () awful.layout.set(awful.layout.suit.tile) end), + +### Why are new clients urgent by default? + +You can change this by redefining `awful.ewmh.activate(c)` in your rc.lua. If +you don't want new clients to be urgent by default put this in your rc.lua: + + client.disconnect_signal("request::activate", awful.ewmh.activate) + function awful.ewmh.activate(c) + if c:isvisible() then + client.focus = c + c:raise() + end + end + client.connect_signal("request::activate", awful.ewmh.activate) + +## Usage + +### How to use this thing? + +Default binding to open a terminal is "Mod4 + Enter" (where Mod4 is usually the +"Windows" key). You can also click on the desktop background with the right +button, to open the awesome menu. + +From there you can proceed to open `man awesome` which has a good guide, +including the list of default keybindings. + +### Layouts + +With the default config, you can cycle through window layouts by pressing +"mod4+space" ("mod4+shift+space" to go back) or clicking the layout button in +the upper right corner of the screen. + +### How to restart or quit awesome? + +You can use the keybinding "Mod4+Ctrl+r" or by selecting restart in the menu. +You could call `awesome.restart` either from the Lua prompt widget, or by +passing it to `awesome-client`: + + $ echo 'awesome.restart()' | awesome-client + +You can also send the `SIGHUP` signal to the awesome process. Find the PID using +`ps`, `pgrep` or use `pkill`: + + $ pkill -HUP awesome + +You can quit awesome by using "Mod4+Shift+q" keybinding or by selecting quit in +the menu. You could call `awesome.quit` either from the Lua prompt widget, +or by passing it to `awesome-client`. + + $ echo 'awesome.quit()' | awesome-client + +You can also send the `SIGINT` signal to the awesome process. Find the PID using `ps`, `pgrep` or use `pkill`: + + $ pkill -INT awesome + +### Why awesome doesn't use my own brand new config? + +If awesome cannot find `$XDG_CONFIG_HOME/awesome/rc.lua`, or fails to load it, +it falls back to using `/etc/xdg/awesome/rc.lua` (you haven't edited it, I hope, +have you?). Even if `awesome --check` hasn't reported any error, it only means +that your `rc.lua` is syntactically correct, but absence of runtime errors is +not guaranteed. Moreover, awesome could apply half of your config then encounter +an error and load stock one, and that could lead to bizzare result, like two +sets of tags. See the next entry on how to find out where the problem lurks. + +### Where are logs, error messages or something? + +When hacking your own configuration, something inevitably would go wrong. +awesome prints error messages to its `stderr` stream. When run with usual `$ +startx`, it'd be printed right in tty. If you use something more complicated +(some kind of DM, like kdm or gdm), stderr is usually redirected somewhere else. +To see where, run the following command: + + $ ls -l /proc/$(pidof awesome)/fd/2 + +There's handy way to run awesome and redirect both its standard output and error streams to files: + + exec /usr/bin/awesome >> ~/.cache/awesome/stdout 2>> ~/.cache/awesome/stderr + +If you put it into `.xinitrc` (for `startx`) or `~/.xsession`, you'll be able to +watch (with `tail -f`) everything right from awesome. + +### Why does Mod4 "swallow" succeeding key presses? + +On some systems xkb by default maps the left windows key to "Multi_key" (at +least in `us` and `de` layouts). Multi_key is an xkb feature which may be used +to access uncommon symbols by pressing Multi_key and then (consecutively) two +"normal" keys. The solution is to remap your windows key to mod4 and remove the +Multi_key mapping. This can be done by including "altwin(left_meta_win)" in the +xkb keyboard description xkb_symbols line. + + #!/bin/bash + xkbcomp - $DISPLAY< Date: Sat, 30 Apr 2016 11:57:32 +0200 Subject: [PATCH 2/2] Import DoingARelease from the wiki This was only partly converted to markdown. It still refers to wiki pages with wiki syntax, because we first have to decide on what happens with the wiki before this can be updated. Signed-off-by: Uli Schlachter --- docs/doing_a_release.md | 65 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 docs/doing_a_release.md diff --git a/docs/doing_a_release.md b/docs/doing_a_release.md new file mode 100644 index 000000000..800598f14 --- /dev/null +++ b/docs/doing_a_release.md @@ -0,0 +1,65 @@ +## How to do a release + +* Edit `awesomeConfig.cmake` and choose a codename that is not already listed in [[Releases]]. jd always picked a song title, you should do the same. +* Commit this changes to `awesomeConfig.cmake` +* Add the release version and date to [[Releases]] +* Change the version in [[Template:Stable-version]] +* Git sign with `git tag -s vX.Y.Z -m 'awesome vX.Y.Z`' +* Push with `git push` and push tag with `git push origin vX.Y.Z` +* Run `make dist` to create tarballs. +* Copy tarballs inside `awesome.naquadah.org:/var/www/awesome.naquadah.org/download/` +* Edit `download.mdwn` from [http://git.naquadah.org/?p=awesome-www.git;a=summary the awesome www repository] to change the version information, links, etc +* Go into the 'src' submodule, and update it to vX.Y.Z with `git checkout vX.Y.Z`. This will be used to build and publish the documentation online. +* Commit `download.mdwn` and `src`. +* `git push` this +* Type `make push` in `awesome-www` to push changes to the website. Be careful to have `ikiwiki`, `asciidoc` and imagemagick for Perl (`perlmagick`, otherwise images get broken) +* Send a mail to `awesome@naquadah.org` with any amount of information and jokes inside. +* Change the topic on IRC + +For the announcement mail, the following shell script might be handy: + + #!/bin/sh + VER=$1 + PREV_VER=$2 + TAG="v$VER" + PTAG="v$PREV_VER" + REVS="$PTAG..$TAG" + + echo "awesome version $VER has been released. It is available from:" + + print_file() + { + EXT="$1" + URL="http://awesome.naquadah.org/download/awesome-$VER.$EXT" + FILE="/var/www/awesome.naquadah.org/download/awesome-$VER.$EXT" + MD5=$(ssh prometheus.naquadah.org "md5sum $FILE" 2>/dev/null | cut -f1 -d ' ') + SHA1=$(ssh prometheus.naquadah.org "sha1sum $FILE" 2>/dev/null | cut -f 1 -d ' ') + + echo + echo "$EXT: $URL" + echo "md5: $MD5" + echo "sha1: $SHA1" + } + + print_headline() + { + HEAD="$@" + echo + echo "$HEAD" + echo "$HEAD" | sed -e 's/./-/g' + } + + print_file "tar.xz" + print_file "tar.bz2" + + print_headline "number of changes" + git rev-list "$REVS" | wc -l + + print_headline "number of commiters" + git log --format=format:%an "$REVS" | sort -u | wc -l + + print_headline "shortlog" + git log "$REVS" | git shortlog --numbered | cat + + print_headline "diffstat" + git diff --stat "$REVS" | cat