Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
Soft committed Sep 7, 2021
1 parent f40d2b1 commit a7c06fb
Show file tree
Hide file tree
Showing 2 changed files with 18 additions and 31 deletions.
29 changes: 12 additions & 17 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,6 @@
[![Latest Version](https://img.shields.io/crates/v/run-or-raise.svg)](https://crates.io/crates/run-or-raise)
[![GitHub release](https://img.shields.io/github/release/Soft/run-or-raise.svg)](https://github.com/Soft/run-or-raise/releases)
[![dependency status](https://deps.rs/repo/github/soft/run-or-raise/status.svg)](https://deps.rs/repo/github/soft/run-or-raise)
[![Rust Documentation](https://img.shields.io/badge/api-rustdoc-blue.svg)](https://docs.rs/crate/run-or-raise)
[![AUR version](https://img.shields.io/aur/version/run-or-raise.svg)](https://aur.archlinux.org/packages/run-or-raise/)
[![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)

Expand All @@ -17,36 +16,32 @@ This can be useful when combined with a tiling window manager such as
[i3](https://i3wm.org) or a general purpose keyboard shortcut manager such as
[xbindkeys](http://www.nongnu.org/xbindkeys/) that allow binding arbitrary
commands to keybindings. In such setup, one might use `run-or-raise` to, for
example, launch or focus a web browser with a single key.
example, launch or focus a web browser with a single key press.

`run-or-raise` is designed to work with X11 based Linux systems.

## Installation

The easiest way to obtain the latest version of `run-or-raise` is to download a
precompiled, statically-linked, program binary from [GitHub releases
page](https://github.com/Soft/run-or-raise/releases). These binaries should work
on most recent Linux systems without any additional dependencies.

Alternatively, `run-or-raise` can be easily installed from the source using
`run-or-raise` can be installed using
[cargo](https://doc.rust-lang.org/cargo/index.html):

``` shell
$ cargo install run-or-raise
cargo install run-or-raise
```

Compiling and running `run-or-raise` requires [libxcb](https://xcb.freedesktop.org)
library to be installed. To get the latest development version of
`run-or-raise`, you can direct cargo to install from the git repository:
library to be installed.

To get the latest development version of `run-or-raise`, you can direct cargo to
install from the git repository:

``` shell
$ cargo install --git 'https://github.com/Soft/run-or-raise.git'
cargo install --git 'https://github.com/Soft/run-or-raise.git'
```

However, just downloading the application binary or installing with cargo will
not install program’s man page. To also get the manual pages installed, invoke
`make install` in the project directory. By default, the install script will
place the files under `/usr/local/` hierarchy.
Note that cargo will not install man pages. To install `run-or-raise` along with
its manual invoke `make install` in the project directory. By default, the
installation script will place the files under `/usr/local/` hierarchy.

## Usage

Expand All @@ -55,7 +50,7 @@ run-or-raise CONDITION PROGRAM [ARGS...]
```

When invoked, `run-or-raise` matches existing windows against `CONDITION`. If a
matching window is found, it is focused. If none of the windows fulfill the
matching window is found, it is focused. If none of the windows match the
criteria, `run-or-raise` executes `PROGRAM` passing any `ARGS` to it as
arguments.

Expand Down
20 changes: 6 additions & 14 deletions man/run-or-raise.1
Original file line number Diff line number Diff line change
@@ -1,27 +1,20 @@
.TH RUN-OR-RAISE 1 2018

.TH RUN-OR-RAISE 1 2021
.SH NAME
run\-or\-raise \- utility for launching applications or focusing their windows

.SH SYNOPSIS

.B run\-or\-raise
\fICONDITION PROGRAM\fR [\fIARGS\fR...]

.SH DESCRIPTION

\fBrun\-or\-raise\fR is a utility for launching applications or focusing their
windows. When invoked, \fBrun\-or\-raise\fR matches existing windows against
\fICONDITION\fR. If a matching window is found, it is focused. If none of the
windows fulfill the criteria, \fBrun\-or\-raise\fR executes \fIPROGRAM\fR
passing any \fIARGS\fR to it as arguments.

windows match the criteria, \fBrun\-or\-raise\fR executes \fIPROGRAM\fR passing
any \fIARGS\fR to it as arguments.
.SH CONDITIONS

Conditions select windows based on their properties. Conditions support two
comparison operators: \fB=\fR for exact equality comparison with a string
literal and \fB~\fR work comparing with a regular expression.

.P
Comparisons can be combined using logical operators: \fB&&\fR for logical
\fIAND\fR, \fB||\fR for logical \fIOR\fR, and \fB!\fR for logical \fINOT\fR.
Operators in matching expressions are left-associative and \fB!\fR (not) binds
Expand All @@ -30,10 +23,10 @@ Possible properties are \fBclass\fR, \fBname\fR, and \fBrole\fR. Additionally,
parentheses can be used to alter evaluation order. Strings and regular
expressions are written inside double quotes. If multiple windows match the
criteria, the first matching window is selected.

.P
Bellow are some examples of how conditions can be used to select windows in
various ways:

.P
.nf
.RS
# Launch or focus emacs
Expand All @@ -48,6 +41,5 @@ run-or-raise 'name ~ ".*Firefox$"' firefox
run-or-raise 'role = "browser" && ! class = "Chromium"' firefox
.RE
.fi

.SH AUTHORS
Samuel Laurén <samuel.lauren@iki.fi>

0 comments on commit a7c06fb

Please sign in to comment.