Skip to content

Commit

Permalink
i3blocks.1: remove configuration section
Browse files Browse the repository at this point in the history 
The man page is meant to describe the usage of the i3blocks binary,
not the syntax of the configuration file which is already detailed in
the README, and consequently on the website. Remove the configuration
section and redirect the user to the website.
  • Loading branch information
@vivien
vivien committed Aug 12, 2019
1 parent 0a35aae commit 1b180d2
Show file tree
Hide file tree
Showing 3 changed files with 5 additions and 236 deletions.
93 changes: 2 additions & 91 deletions docs/i3blocks.1
View file
Original file line number Diff line number Diff line change
Expand Up @@ -114,97 +114,8 @@ By default, i3blocks looks for a configuration file in the following order (note
\fI/etc/i3blocks.conf\fP
.RE
.sp
The configuration file uses a simplified INI format.
Each section describes a new block to be displayed in the status bar.
A line beginning with a \fI#\fP sign is a comment, and empty lines are ignored.
A property is one \fIkey=value\fP pair per line, without spaces surrounding the equal sign.
Properties declared outside a block (i.e. at the beginning of the file) describe global settings and are merged into every block definitions.
.sp
You must refer to \c
.URL "http://i3wm.org/docs/i3bar\-protocol.html" "" " "
to know what properties are understood by i3bar(1).
.sp
The following properties are interpreted by \fBi3blocks\fP to describe how the optional command must be scheduled.
.SS "command"
.sp
The command line to be invoked with \f(CRsh \-c\fP.
.sp
It can be relative to the configuration file where it is defined.
.sp
Data read from the standard output of the command is used to update the block properties.
Data is interpreted depending of the specified \fIformat\fP.
.SS "interval"
.sp
If it is a positive integer, then the block is spawned on startup and the value is used as a time interval in seconds to schedule future updates.
If undefined or 0, the block won\(cqt be executed on startup (which is useful to simulate buttons).
.sp
If \fIonce\fP (or \fI\-1\fP), the block will be scheduled only on startup (note that a click or signal will still trigger an update).
.sp
If \fIrepeat\fP (or \fI\-2\fP), the block will be scheduled on startup, and as soon as it terminates (useful to repeat blocking commands).
.sp
If \fIpersist\fP (or \fI\-3\fP), the block will be scheduled only on startup, and updated as soon as it outputs a line.
Updates are thus limited to single lines.
.SS "signal"
.sp
The signal number used to update the block.
All the real\-time (think prioritized and queueable) signals are available to the user.
The number is valid between \fI1\fP and \fIN\fP, where \fISIGRTMIN+N=SIGRTMAX\fP.
(Note that there are 31 real\-time signals in Linux.)
For instance, \fIsignal=10\fP means that this block will be updated when \fBi3blocks\fP receives the \fISIGRTMIN+10\fP signal.
.SS "format"
.sp
This property specifies the format of the output text.
.sp
When undefined, the raw format is assumed.
In this format, each non\-empty line of the output is used to update an i3bar key, in the order of definition found in the i3bar protocol:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
. sp -1
. IP " 1." 4.2
.\}
\fIfull_text\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
. sp -1
. IP " 2." 4.2
.\}
\fIshort_text\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
. sp -1
. IP " 3." 4.2
.\}
\fIcolor\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
. sp -1
. IP " 4." 4.2
.\}
\fIbackground\fP
.RE
.sp
Excess lines are considered an error.
.sp
If \fIjson\fP (or \fI1\fP) is used, the block output is read as a JSON object and will be merged into the block properties.
For the content of the configuration file, please refer to the i3blocks website: \c
.URL "https://vivien.github.io/i3blocks" "" ""
.SH "SEE ALSO"
.sp
i3(1), i3bar(1), i3status(1)
Expand Down
55 changes: 1 addition & 54 deletions docs/i3blocks.1.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -48,60 +48,7 @@ By default, {progname} looks for a configuration file in the following order (no
. _$XDG_CONFIG_DIRS/i3blocks/config_ (or _/etc/xdg/i3blocks/config_)
. _/etc/i3blocks.conf_

The configuration file uses a simplified INI format.
Each section describes a new block to be displayed in the status bar.
A line beginning with a _#_ sign is a comment, and empty lines are ignored.
A property is one _key=value_ pair per line, without spaces surrounding the equal sign.
Properties declared outside a block (i.e. at the beginning of the file) describe global settings and are merged into every block definitions.

You must refer to http://i3wm.org/docs/i3bar-protocol.html to know what properties are understood by i3bar(1).

The following properties are interpreted by **{progname}** to describe how the optional command must be scheduled.

=== command

The command line to be invoked with `sh -c`.

It can be relative to the configuration file where it is defined.

Data read from the standard output of the command is used to update the block properties.
Data is interpreted depending of the specified _format_.

=== interval

If it is a positive integer, then the block is spawned on startup and the value is used as a time interval in seconds to schedule future updates.
If undefined or 0, the block won't be executed on startup (which is useful to simulate buttons).

If _once_ (or _-1_), the block will be scheduled only on startup (note that a click or signal will still trigger an update).

If _repeat_ (or _-2_), the block will be scheduled on startup, and as soon as it terminates (useful to repeat blocking commands).

If _persist_ (or _-3_), the block will be scheduled only on startup, and updated as soon as it outputs a line.
Updates are thus limited to single lines.

=== signal

The signal number used to update the block.
All the real-time (think prioritized and queueable) signals are available to the user.
The number is valid between _1_ and _N_, where _SIGRTMIN+N=SIGRTMAX_.
(Note that there are 31 real-time signals in Linux.)
For instance, _signal=10_ means that this block will be updated when **{progname}** receives the _SIGRTMIN+10_ signal.

=== format

This property specifies the format of the output text.

When undefined, the raw format is assumed.
In this format, each non-empty line of the output is used to update an i3bar key, in the order of definition found in the i3bar protocol:

. _full_text_
. _short_text_
. _color_
. _background_

Excess lines are considered an error.

If _json_ (or _1_) is used, the block output is read as a JSON object and will be merged into the block properties.
For the content of the configuration file, please refer to the i3blocks website: https://vivien.github.io/i3blocks

== SEE ALSO

Expand Down
93 changes: 2 additions & 91 deletions docs/i3blocks.1.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -446,14 +446,7 @@ <h1>i3blocks(1)</h1>
<li><a href="#_synopsis">SYNOPSIS</a></li>
<li><a href="#_description">DESCRIPTION</a></li>
<li><a href="#_options">OPTIONS</a></li>
<li><a href="#_configuration">CONFIGURATION</a>
<ul class="sectlevel2">
<li><a href="#_command">command</a></li>
<li><a href="#_interval">interval</a></li>
<li><a href="#_signal">signal</a></li>
<li><a href="#_format">format</a></li>
</ul>
</li>
<li><a href="#_configuration">CONFIGURATION</a></li>
<li><a href="#_see_also">SEE ALSO</a></li>
<li><a href="#_authors">AUTHORS</a></li>
<li><a href="#_resources">RESOURCES</a></li>
Expand Down Expand Up @@ -545,89 +538,7 @@ <h2 id="_configuration">CONFIGURATION</h2>
</ol>
</div>
<div class="paragraph">
<p>The configuration file uses a simplified INI format.
Each section describes a new block to be displayed in the status bar.
A line beginning with a <em>#</em> sign is a comment, and empty lines are ignored.
A property is one <em>key=value</em> pair per line, without spaces surrounding the equal sign.
Properties declared outside a block (i.e. at the beginning of the file) describe global settings and are merged into every block definitions.</p>
</div>
<div class="paragraph">
<p>You must refer to <a href="http://i3wm.org/docs/i3bar-protocol.html" class="bare">http://i3wm.org/docs/i3bar-protocol.html</a> to know what properties are understood by i3bar(1).</p>
</div>
<div class="paragraph">
<p>The following properties are interpreted by <strong>i3blocks</strong> to describe how the optional command must be scheduled.</p>
</div>
<div class="sect2">
<h3 id="_command">command</h3>
<div class="paragraph">
<p>The command line to be invoked with <code>sh -c</code>.</p>
</div>
<div class="paragraph">
<p>It can be relative to the configuration file where it is defined.</p>
</div>
<div class="paragraph">
<p>Data read from the standard output of the command is used to update the block properties.
Data is interpreted depending of the specified <em>format</em>.</p>
</div>
</div>
<div class="sect2">
<h3 id="_interval">interval</h3>
<div class="paragraph">
<p>If it is a positive integer, then the block is spawned on startup and the value is used as a time interval in seconds to schedule future updates.
If undefined or 0, the block won&#8217;t be executed on startup (which is useful to simulate buttons).</p>
</div>
<div class="paragraph">
<p>If <em>once</em> (or <em>-1</em>), the block will be scheduled only on startup (note that a click or signal will still trigger an update).</p>
</div>
<div class="paragraph">
<p>If <em>repeat</em> (or <em>-2</em>), the block will be scheduled on startup, and as soon as it terminates (useful to repeat blocking commands).</p>
</div>
<div class="paragraph">
<p>If <em>persist</em> (or <em>-3</em>), the block will be scheduled only on startup, and updated as soon as it outputs a line.
Updates are thus limited to single lines.</p>
</div>
</div>
<div class="sect2">
<h3 id="_signal">signal</h3>
<div class="paragraph">
<p>The signal number used to update the block.
All the real-time (think prioritized and queueable) signals are available to the user.
The number is valid between <em>1</em> and <em>N</em>, where <em>SIGRTMIN+N=SIGRTMAX</em>.
(Note that there are 31 real-time signals in Linux.)
For instance, <em>signal=10</em> means that this block will be updated when <strong>i3blocks</strong> receives the <em>SIGRTMIN+10</em> signal.</p>
</div>
</div>
<div class="sect2">
<h3 id="_format">format</h3>
<div class="paragraph">
<p>This property specifies the format of the output text.</p>
</div>
<div class="paragraph">
<p>When undefined, the raw format is assumed.
In this format, each non-empty line of the output is used to update an i3bar key, in the order of definition found in the i3bar protocol:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p><em>full_text</em></p>
</li>
<li>
<p><em>short_text</em></p>
</li>
<li>
<p><em>color</em></p>
</li>
<li>
<p><em>background</em></p>
</li>
</ol>
</div>
<div class="paragraph">
<p>Excess lines are considered an error.</p>
</div>
<div class="paragraph">
<p>If <em>json</em> (or <em>1</em>) is used, the block output is read as a JSON object and will be merged into the block properties.</p>
</div>
<p>For the content of the configuration file, please refer to the i3blocks website: <a href="https://vivien.github.io/i3blocks" class="bare">https://vivien.github.io/i3blocks</a></p>
</div>
</div>
</div>
Expand Down

0 comments on commit 1b180d2

Please sign in to comment.