commit 730828f28e51e1c804fdb980374711a72bfc991f
parent 6bfd64e51a9b76611f5ddbf9ffcad46af1b848b6
Author: Kris Maglione <jg@suckless.org>
Date: Mon, 12 Oct 2009 22:07:51 -0400
More doc updates. Add wmiir.1.
Diffstat:
| README | | | 49 | +++++++++++++++++++++++++------------------------ |
| cmd/wmiir.c | | | 13 | ++++++------- |
| man/Makefile | | | 1 | + |
| man/wimenu.1 | | | 50 | ++++++-------------------------------------------- |
| man/wimenu.man1 | | | 72 | +++++++++++++++++++++++++++++++++++++----------------------------------- |
| man/wmii.1 | | | 63 | ++++++++++++++++++++++++++++++--------------------------------- |
| man/wmii.man1 | | | 59 | ++++++++++++++++++++++++++++++++++++++--------------------- |
| man/wmiir.1 | | | 91 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| man/wmiir.man1 | | | 77 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
9 files changed, 311 insertions(+), 164 deletions(-)
diff --git a/README b/README
@@ -1,41 +1,42 @@
Abstract
--------
-window manager improved-improved is a dynamic window manager for X11.
-It supports classic and tiled window management with extended
-keyboard, mouse, and 9P-based [1] remote control.
-It consists of the wmii(1) window manager and the wmiir(1)
-the remote access utility.
+wmii is a dynamic window manager for X11. It supports classic and
+tiled window management with extended keyboard, mouse, and 9P-based[1]
+remote control. It consists of the wmii(1) window manager and the
+wmiir(1) the remote access utility.
Requirements
------------
-In order to build wmii you need the Xlib header files and libixp. xmessage
-and dmenu are used by the default scripts. libixp and dmenu can be obtained
-from http://suckless.org/. Either plan9port[2] or 9base is recommended.
-If you have the wmii+ixp distribution, libixp is already provided.
+In order to build wmii you need the Xlib header files and libixp.
+xmessage is used by the default scripts. Libixp, if not provided, can
+be obtained from http://libs.suckless.org/. On debian, you should be
+able to obtain all dependencies by running `make deb-dep`. Python is
+recommended for more advanced configurations.
Installation
------------
-First, edit config.mk to match your local setup, or to let us guess it, run:
- make config
+First, edit config.mk to match your local setup.
To build, simply run:
make
-To install, run the following, as root, if necessary:
+To install, run the following, as root if necessary:
make install
+On debian, you should only have to run `make deb` to create a debian
+package. No further configuration should be necessary.
+
+
Running wmii
------------
Add the following line to your .xinitrc to start wmii using startx:
- until wmii; do
- true
- done
+ until wmii; do :; done
-In order to connect wmii to a specific display, make sure that
-the DISPLAY environment variable is set correctly. For example:
+In order to connect wmii to a specific display, make sure that the
+DISPLAY environment variable is set correctly. For example:
DISPLAY=:1 wmii
@@ -44,18 +45,18 @@ This will start wmii on display :1.
Configuration
-------------
-The configuration of wmii is done by customizing the rc script rc.wmii.local,
+The configuration of wmii is done by customizing the rc script wmiirc,
which remotely controls the window manager and handles various events.
-The main rc.wmii script lives in PREFIX/etc/wmii@CONFPREFIX@/, while rc.wmii.local
-goes in $HOME/.wmii@CONFPREFIX@/.
+The main wmiirc script lives in @CONFPREFIX@/wmii@CONFVERSION@/, while
+wmiirc_local goes in $HOME/.wmii@CONFVERSION@/.
-If you wish to unbind keys bound by rc.wmii in rc.wmii.local, you
-must do so inside the function Action-overridekeys. You may,
-however, define new keys or redefine keys anywhere.
+More advanced versions of wmiirc are provided in python and ruby.
+For more information on them, see alternative_wmiircs/README.
Credits
-------
-The following people have contributed especially to wmii in various ways:
+The following people have contributed especially to wmii in various
+ways:
- Christoph Wegscheider <christoph dot wegscheider at wegi dot net>
- Georg Neis <gn at suckless dot org>
diff --git a/cmd/wmiir.c b/cmd/wmiir.c
@@ -17,9 +17,9 @@ static IxpClient *client;
static void
usage(void) {
fprint(1,
- "usage: %s [-a <address>] {create | read | ls [-ld] | remove | rm | write} <file>\n"
- " %s [-a <address>] xwrite <file> <data>\n"
- " %s -v\n", argv0, argv0, argv0);
+ "usage: %s [-a <address>] {create | ls [-dlp] | read | remove | write} <file>\n"
+ " %s [-a <address>] xwrite <file> <data>\n"
+ " %s -v\n", argv0, argv0, argv0);
exit(1);
}
@@ -79,12 +79,11 @@ modestr(uint mode) {
return buf;
}
-static char *
-timestr(uint val) {
+static char*
+timestr(time_t val) {
static char buf[32];
- ctime_r((time_t*)&val, buf);
- buf[strlen(buf) - 1] = '\0';
+ strftime(buf, sizeof buf, "%Y-%m-%d %H:%M", localtime(&val));
return buf;
}
diff --git a/man/Makefile b/man/Makefile
@@ -3,6 +3,7 @@ include ${ROOT}/mk/hdr.mk
include ${ROOT}/mk/wmii.mk
TARG = wmii.1 \
+ wmiir.1 \
wimenu.1
$(TARG): Makefile $(ROOT)/mk/wmii.mk header.t2t
diff --git a/man/wimenu.1 b/man/wimenu.1
@@ -21,106 +21,68 @@ supports basic item completion and history searching.
.SH ARGUMENTS
.TP
\-a
-
-.RS
The address at which to connect to \fBwmii\fR.
-.RE
.TP
\-c
-
-.RS
Prints the contents of the input buffer each time the
user inputs a character, as such:
-.RE
-.RS
-.RS
\fI<text before caret>\fR\e0\fI<text after caret>\fR\e0
-.RE
-.RE
.TP
\-h \fI<history file>\fR
-
-.RS
Causes \fBwimenu\fR to read its command history from
\fI<history file>\fR and to append its result to that file if
\fI\-n\fR is given.
-.RE
.TP
\-i
-
-.RS
Causes matching of completion items to be performed in a
case insensitive manner.
-.RE
.TP
\-K
-
-.RS
Prevents \fBwimenu\fR from initializing its default key
bindings. WARNING: If you do this, be sure to bind a key
with the Accept or Reject action, or you will have no way
to exit \fBwimenu\fR.
-.RE
.TP
\-k \fI<key file>\fR
-
-.RS
Key bindings will be read from \fI<key file>\fR. Bindings
appear as:
-.RE
-.RS
-.RS
\fI<key>\fR \fI[action]\fR \fI[args]\fR
-.RE
-.RE
-.RS
where \fI<key>\fR is a key name, similar to the format used by
wmii. For action and args, please refer to the default
bindings, provided in the source distribution under
cmd/menu/keys.txt, or use strings(1) on the \fBwimenu\fR
executable (this level of customization is reserved for the
determined).
-.RE
.TP
\-n \fI<count>\fR
-
-.RS
Write at most \fI<count>\fR items back to the history file.
The file is never modified unless this option is
provided. Duplicates are filtered out within a 20 item
sliding window before this limit is imposed.
-.RE
.TP
\-p \fI<prompt>\fR
-
-.RS
The string \fI<prompt>\fR will be show before the input field
when the menu is opened.
-.RE
.TP
\-s \fI<screen>\fR
-
-.RS
Suggests that the menu open on Xinerama screen \fI<screen>\fR.
-.RE
+
.SH ENVIRONMENT
.TP
-WMII_ADDRESS
-Socket file of Used by wmiir(1).
+\fB$WMII_ADDRESS\fR
+The address at which to connect to wmii.
.TP
-NAMESPACE
-
-.RS
+\fB$NAMESPACE\fR
The namespace directory to use if no address is
provided.
-.RE
+
.SH SEE ALSO
.P
-dmenu(1), wmiir(1)
+wmii(1), wmiir(1), dmenu(1)
.P
\fI[1]\fR http://www.suckless.org/wiki/wmii/tips/9p_tips
diff --git a/man/wimenu.man1 b/man/wimenu.man1
@@ -24,56 +24,58 @@ supports basic item completion and history searching.
= ARGUMENTS =
: -a
- The address at which to connect to `wmii`.
+ The address at which to connect to `wmii`.
: -c
- Prints the contents of the input buffer each time the
- user inputs a character, as such:
+ Prints the contents of the input buffer each time the
+ user inputs a character, as such:
- <text before caret>\0<text after caret>\0
+ <text before caret>\0<text after caret>\0
: -h <history file>
- Causes `wimenu` to read its command history from
- <history file> and to append its result to that file if
- _-n_ is given.
+ Causes `wimenu` to read its command history from
+ <history file> and to append its result to that file if
+ _-n_ is given.
: -i
- Causes matching of completion items to be performed in a
- case insensitive manner.
+ Causes matching of completion items to be performed in a
+ case insensitive manner.
: -K
- Prevents `wimenu` from initializing its default key
- bindings. WARNING: If you do this, be sure to bind a key
- with the Accept or Reject action, or you will have no way
- to exit `wimenu`.
+ Prevents `wimenu` from initializing its default key
+ bindings. WARNING: If you do this, be sure to bind a key
+ with the Accept or Reject action, or you will have no way
+ to exit `wimenu`.
: -k <key file>
- Key bindings will be read from <key file>. Bindings
- appear as:
+ Key bindings will be read from <key file>. Bindings
+ appear as:
- <key> [action] [args]
+ <key> [action] [args]
- where <key> is a key name, similar to the format used by
- wmii. For action and args, please refer to the default
- bindings, provided in the source distribution under
- cmd/menu/keys.txt, or use strings(1) on the `wimenu`
- executable (this level of customization is reserved for the
- determined).
+ where <key> is a key name, similar to the format used by
+ wmii. For action and args, please refer to the default
+ bindings, provided in the source distribution under
+ cmd/menu/keys.txt, or use strings(1) on the `wimenu`
+ executable (this level of customization is reserved for the
+ determined).
: -n <count>
- Write at most <count> items back to the history file.
- The file is never modified unless this option is
- provided. Duplicates are filtered out within a 20 item
- sliding window before this limit is imposed.
+ Write at most <count> items back to the history file.
+ The file is never modified unless this option is
+ provided. Duplicates are filtered out within a 20 item
+ sliding window before this limit is imposed.
: -p <prompt>
- The string <prompt> will be show before the input field
- when the menu is opened.
+ The string <prompt> will be show before the input field
+ when the menu is opened.
: -s <screen>
- Suggests that the menu open on Xinerama screen <screen>.
+ Suggests that the menu open on Xinerama screen <screen>.
+:
= ENVIRONMENT =
-: WMII_ADDRESS
- Socket file of Used by wmiir(1).
-: NAMESPACE
- The namespace directory to use if no address is
- provided.
+: $WMII_ADDRESS
+ The address at which to connect to wmii.
+: $NAMESPACE
+ The namespace directory to use if no address is
+ provided.
+:
= SEE ALSO =
-dmenu(1), wmiir(1)
+wmii(1), wmiir(1), dmenu(1)
[1] http://www.suckless.org/wiki/wmii/tips/9p_tips
diff --git a/man/wmii.1 b/man/wmii.1
@@ -48,47 +48,30 @@ the bar, which are described in detail in the
.SS Command Line Arguments
.TP
\-a \fI<address>\fR
-
-.RS
Specifies the address on which \fBwmii\fR should listen for
connections. The address takes the form
\fB\fI<protocol>\fR!\fI<address>\fR\fR. The default is of the form:
-.RE
-.RS
-.RS
unix!/tmp/ns.\fB$USER\fR.\fB${DISPLAY\fR%.0\fB}\fR/wmii
-.RE
-.RE
-.RS
which opens a unix socket per Plan 9 Port conventions. To
open a TCP socket, listening at port 4332 on the loopback
interface, use:
-.RE
-.RS
-.RS
tcp!localhost!4332
-.RE
-.RE
-.RS
\fB$WMII_NAMESPACE\fR is automatically set to this value.
-.RE
.TP
\-r \fI<wmiirc>\fR
-
-.RS
Specifies which rc script to run. If \fI<wmiirc>\fR consists of a
single argument, \fB$WMII_CONFPATH\fR is searched before \fB$PATH\fR.
Otherwise, it is passed to the shell for evaluation. The
environment variables \fB$WMII_ADDRESS\fR and \fB$WMII_CONFPATH\fR are
preset for the script.
-.RE
-.SS Terminology
+== Terminology ==
+
.TP
Display
A running X server instance consisting of input
@@ -358,16 +341,11 @@ Quit \fBwmii\fR
.TP
exec \fI<prog>\fR
Replace \fBwmii\fR with \fI<prog>\fR
-
-.RS
-: spawn \fI<prog>\fR
-.RS
+.TP
+spawn \fI<prog>\fR
Spawn a new program, as if by the \fI\-r\fR flag.
-.RE
-.RE
-.P
- :
-:
+.RS -8
+
.SS The /client/ Hierarchy
.P
@@ -474,13 +452,29 @@ area
Selects a column or the floating area.
.nf
- area ::= "~" | \fI<number>\fR | "sel"
+ area_spec ::= "~" | \fI<number>\fR | "sel"
.fi
-Where represents the floating area and \fI<number>\fR represents a column
+Where "~" represents the floating area and \fI<number>\fR represents a column
index, starting at one.
+.nf
+ screen_spec ::= \fI<number>\fR
+.fi
+
+
+Where \fI<number>\fR representes the 0\-based Xinerama screen number.
+
+.nf
+ area ::= \fI<area_spec>\fR | \fI<screen_spec>\fR:\fI<area_spec>\fR
+.fi
+
+
+When \fI<screen_spec>\fR is omitted and \fI<area_spec>\fR is not "sel",
+0 is assumed. "sel" by itself represents the selected client no
+matter which screen it is on.
+
.TP
frame
Selects a client window.
@@ -543,7 +537,7 @@ User\-specific action directory. Actions are first searched here.
.SH ENVIRONMENT
.TP
-HOME, DISPLAY
+\fB$HOME\fR, \fB$DISPLAY\fR
See the section \fBFILES\fR above.
.P
@@ -551,8 +545,11 @@ The following variables are set and exported within \fBwmii\fR and
thus can be used in actions:
.TP
-WMII_ADDRESS
-Socket file of Used by wmiir(1).
+\fB$WMII_ADDRESS\fR
+The address on which \fBwmii\fR is listening.
+.TP
+\fB$NAMESPACE\fR
+The namespace directory to use if no address is provided.
.SH SEE ALSO
.P
diff --git a/man/wmii.man1 b/man/wmii.man1
@@ -49,26 +49,26 @@ the bar, which are described in detail in the
== Command Line Arguments ==
: -a <address>
- Specifies the address on which `wmii` should listen for
- connections. The address takes the form
- `<protocol>!<address>`. The default is of the form:
+ Specifies the address on which `wmii` should listen for
+ connections. The address takes the form
+ `<protocol>!<address>`. The default is of the form:
- unix!/tmp/ns.$USER.${DISPLAY%.0}/wmii
+ unix!/tmp/ns.$USER.${DISPLAY%.0}/wmii
- which opens a unix socket per Plan 9 Port conventions. To
- open a TCP socket, listening at port 4332 on the loopback
- interface, use:
+ which opens a unix socket per Plan 9 Port conventions. To
+ open a TCP socket, listening at port 4332 on the loopback
+ interface, use:
- tcp!localhost!4332
+ tcp!localhost!4332
- $WMII_NAMESPACE is automatically set to this value.
+ $WMII_NAMESPACE is automatically set to this value.
: -r <wmiirc>
- Specifies which rc script to run. If <wmiirc> consists of a
- single argument, $WMII_CONFPATH is searched before $PATH.
- Otherwise, it is passed to the shell for evaluation. The
- environment variables $WMII_ADDRESS and $WMII_CONFPATH are
- preset for the script.
+ Specifies which rc script to run. If <wmiirc> consists of a
+ single argument, $WMII_CONFPATH is searched before $PATH.
+ Otherwise, it is passed to the shell for evaluation. The
+ environment variables $WMII_ADDRESS and $WMII_CONFPATH are
+ preset for the script.
== Terminology ==
@@ -159,6 +159,10 @@ Here is a list of the default actions:
== Default Key Bindings ==
+All of the provided `wmiirc` scripts accept at least the following key
+bindings. They should also provide a `showkeys` action to open a
+key binding quick-reference.
+
=== Moving Around ===
|| Key | Action
@@ -300,9 +304,10 @@ follows.
Quit `wmii`
: exec <prog>
Replace `wmii` with <prog>
- : spawn <prog>
- Spawn a new program, as if by the _-r_ flag.
+ : spawn <prog>
+ Spawn a new program, as if by the _-r_ flag.
:
+ <<
:
== The /client/ Hierarchy ==
@@ -385,11 +390,21 @@ all of the clients with the given tag applied. The special
: area
Selects a column or the floating area.
-``` area ::= "~" | <number> | "sel"
+``` area ::= <area_spec> | <screen_spec>:<area_spec>
+
+ When <screen_spec> is omitted and <area_spec> is not "sel",
+ 0 is assumed. "sel" by itself represents the selected client no
+ matter which screen it is on.
- Where represents the floating area and <number> represents a column
+``` area_spec ::= "~" | <number> | "sel"
+
+ Where "~" represents the floating area and <number> represents a column
index, starting at one.
+``` screen_spec ::= <number>
+
+ Where <number> representes the 0-based Xinerama screen number.
+
: frame
Selects a client window.
@@ -441,14 +456,16 @@ them.
= ENVIRONMENT =
-: HOME, DISPLAY
+: $HOME, $DISPLAY
See the section **FILES** above.
:
The following variables are set and exported within `wmii` and
thus can be used in actions:
-: WMII_ADDRESS
- Socket file of Used by wmiir(1).
+: $WMII_ADDRESS
+ The address on which `wmii` is listening.
+: $NAMESPACE
+ The namespace directory to use if no address is provided.
:
= SEE ALSO =
dmenu(1), wmiir(1)
diff --git a/man/wmiir.1 b/man/wmiir.1
@@ -0,0 +1,91 @@
+.TH "wmiir" 1 "Oct, 2009" "wmii-@VERSION@"
+
+.SH NAME
+.P
+wmiir \- The wmii 9P filesystem client
+
+.SH SYNOPSIS
+.P
+wmiir \fI[\-a \fI<address>\fR]\fR {create | ls \fI[\-dlp]\fR | read | remove | write} \fI<file>\fR
+.P
+wmiir \fI[\-a \fI<address>\fR]\fR xwrite \fI<file>\fR \fI<data>\fR ...
+.P
+wmiir \-v
+
+.SH DESCRIPTION
+.P
+\fBwmiir\fR is a simple 9P filesystem client which ships with \fBwmii\fR, and connects
+to its virtual filesystem by default. \fBwmiir\fR is most often used to query and
+issue commands to \fBwmii\fR, both from the command line and from its \fBsh\fR\-based
+configuration scripts.
+
+.SH ARGUMENTS
+.TP
+\-a
+The address at which to connect to \fBwmii\fR.
+
+.SH COMMANDS
+.TP
+create \fI<file>\fR
+Creates a new file or directory in the filesystem. Permissions and
+file type are inferred by \fBwmii\fR. The contents of the standard input
+are written to the new file.
+.TP
+ls \fI[\-dlp]\fR \fI<path>\fR
+Lists the contents of \fI<path>\fR.
+
+Flags:
+.RS 8
+.TP
+\-d
+Don't list the contents of directories.
+.TP
+\-l
+Long output. For each file, list its permissions, owner,
+group, size (bytes), mtime, and name.
+.TP
+\-p
+Print the full path to each file.
+.RS -8
+.TP
+read \fI<file>\fR
+Reads the entire contents of a file from the filesystem. Blocks until
+interrupted or EOF is received.
+
+Synonyms: \fBcat\fR
+.TP
+remove \fI<path>\fR
+Removes \fI<path>\fR from the filesystem.
+
+Synonyms: rm
+.TP
+write \fI<file>\fR
+Writes the contents of the standard input to \fI<file>\fR.
+.TP
+xwrite \fI<file>\fR \fI<data>\fR ...
+Writes each argument after \fI<file>\fR to the latter.
+
+
+.SH ENVIRONMENT
+.TP
+\fB$WMII_ADDRESS\fR
+The address at which to connect to wmii.
+.TP
+\fB$NAMESPACE\fR
+The namespace directory to use if no address is
+provided.
+
+
+.SH SEE ALSO
+.P
+wmii(1), libixp\fI[2]\fR
+
+.P
+\fI[1]\fR http://www.suckless.org/wiki/wmii/tips/9p_tips
+.P
+\fI[2]\fR http://libs.suckless.org/libixp
+
+
+.\" man code generated by txt2tags 2.5 (http://txt2tags.sf.net)
+.\" cmdline: txt2tags -o- wmiir.man1
+
diff --git a/man/wmiir.man1 b/man/wmiir.man1
@@ -0,0 +1,77 @@
+wmiir
+wmii-@VERSION@
+Oct, 2009
+
+%!includeconf: header.t2t
+
+= NAME =
+
+wmiir - The wmii 9P filesystem client
+
+= SYNOPSIS =
+
+wmiir [-a <address>] {create | ls [-dlp] | read | remove | write} <file> +
+wmiir [-a <address>] xwrite <file> <data> ... +
+wmiir -v
+
+= DESCRIPTION =
+
+`wmiir` is a simple 9P filesystem client which ships with `wmii`, and connects
+to its virtual filesystem by default. `wmiir` is most often used to query and
+issue commands to `wmii`, both from the command line and from its `sh`-based
+configuration scripts.
+
+= ARGUMENTS =
+
+: -a
+ The address at which to connect to `wmii`.
+:
+= COMMANDS =
+
+: create <file>
+ Creates a new file or directory in the filesystem. Permissions and
+ file type are inferred by `wmii`. The contents of the standard input
+ are written to the new file.
+: ls [-dlp] <path>
+ Lists the contents of <path>.
+
+ Flags:
+ >>
+ : -d
+ Don't list the contents of directories.
+ : -l
+ Long output. For each file, list its permissions, owner,
+ group, size (bytes), mtime, and name.
+ : -p
+ Print the full path to each file.
+ <<
+: read <file>
+ Reads the entire contents of a file from the filesystem. Blocks until
+ interrupted or EOF is received.
+
+ Synonyms: `cat`
+: remove <path>
+ Removes <path> from the filesystem.
+
+ Synonyms: rm
+: write <file>
+ Writes the contents of the standard input to <file>.
+: xwrite <file> <data> ...
+ Writes each argument after <file> to the latter.
+:
+
+= ENVIRONMENT =
+
+: $WMII_ADDRESS
+ The address at which to connect to wmii.
+: $NAMESPACE
+ The namespace directory to use if no address is
+ provided.
+:
+
+= SEE ALSO =
+wmii(1), libixp[2]
+
+[1] http://www.suckless.org/wiki/wmii/tips/9p_tips +
+[2] http://libs.suckless.org/libixp
+
