doc: convert urxvt to CommonMark

* convert urxvt documentation to common mark

* format urxvt documentation

* use ShellSession instead of nix
This commit is contained in:
Stu 2020-12-03 15:46:29 +01:00 committed by GitHub
parent 990aa39e31
commit 177023d3f1
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 72 additions and 116 deletions

View file

@ -20,7 +20,7 @@
<xi:include href="shell-helpers.xml" />
<xi:include href="steam.xml" />
<xi:include href="cataclysm-dda.section.xml" />
<xi:include href="urxvt.xml" />
<xi:include href="urxvt.section.xml" />
<xi:include href="weechat.section.xml" />
<xi:include href="xorg.section.xml" />
</chapter>

View file

@ -0,0 +1,71 @@
# Urxvt {#sec-urxvt}
Urxvt, also known as rxvt-unicode, is a highly customizable terminal emulator.
## Configuring urxvt {#sec-urxvt-conf}
In `nixpkgs`, urxvt is provided by the package `rxvt-unicode`. It can be configured to include your choice of plugins, reducing its closure size from the default configuration which includes all available plugins. To make use of this functionality, use an overlay or directly install an expression that overrides its configuration, such as
```nix
rxvt-unicode.override {
configure = { availablePlugins, ... }: {
plugins = with availablePlugins; [ perls resize-font vtwheel ];
};
}
```
If the `configure` function returns an attrset without the `plugins` attribute, `availablePlugins` will be used automatically.
In order to add plugins but also keep all default plugins installed, it is possible to use the following method:
```nix
rxvt-unicode.override {
configure = { availablePlugins, ... }: {
plugins = (builtins.attrValues availablePlugins) ++ [ custom-plugin ];
};
}
```
To get a list of all the plugins available, open the Nix REPL and run
```ShellSession
$ nix repl
:l <nixpkgs>
map (p: p.name) pkgs.rxvt-unicode.plugins
```
Alternatively, if your shell is bash or zsh and have completion enabled, simply type `nixpkgs.rxvt-unicode.plugins.<tab>`.
In addition to `plugins` the options `extraDeps` and `perlDeps` can be used to install extra packages. `extraDeps` can be used, for example, to provide `xsel` (a clipboard manager) to the clipboard plugin, without installing it globally:
```nix
rxvt-unicode.override {
configure = { availablePlugins, ... }: {
pluginsDeps = [ xsel ];
};
}
```
`perlDeps` is a handy way to provide Perl packages to your custom plugins (in `$HOME/.urxvt/ext`). For example, if you need `AnyEvent` you can do:
```nix
rxvt-unicode.override {
configure = { availablePlugins, ... }: {
perlDeps = with perlPackages; [ AnyEvent ];
};
}
```
## Packaging urxvt plugins {#sec-urxvt-pkg}
Urxvt plugins resides in `pkgs/applications/misc/rxvt-unicode-plugins`. To add a new plugin create an expression in a subdirectory and add the package to the set in `pkgs/applications/misc/rxvt-unicode-plugins/default.nix`.
A plugin can be any kind of derivation, the only requirement is that it should always install perl scripts in `$out/lib/urxvt/perl`. Look for existing plugins for examples.
If the plugin is itself a perl package that needs to be imported from other plugins or scripts, add the following passthrough:
```nix
passthru.perlPackages = [ "self" ];
```
This will make the urxvt wrapper pick up the dependency and set up the perl path accordingly.

View file

@ -1,115 +0,0 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xml:id="sec-urxvt">
<title>Urxvt</title>
<para>
Urxvt, also known as rxvt-unicode, is a highly customizable terminal emulator.
</para>
<section xml:id="sec-urxvt-conf">
<title>Configuring urxvt</title>
<para>
In <literal>nixpkgs</literal>, urxvt is provided by the package
<literal>rxvt-unicode</literal>. It can be configured to include your choice
of plugins, reducing its closure size from the default configuration which
includes all available plugins. To make use of this functionality, use an
overlay or directly install an expression that overrides its configuration,
such as
<programlisting>
rxvt-unicode.override {
configure = { availablePlugins, ... }: {
plugins = with availablePlugins; [ perls resize-font vtwheel ];
};
}
</programlisting>
If the <literal>configure</literal> function returns an attrset without the
<literal>plugins</literal> attribute, <literal>availablePlugins</literal>
will be used automatically.
</para>
<para>
In order to add plugins but also keep all default plugins installed, it is
possible to use the following method:
<programlisting>
rxvt-unicode.override {
configure = { availablePlugins, ... }: {
plugins = (builtins.attrValues availablePlugins) ++ [ custom-plugin ];
};
}
</programlisting>
</para>
<para>
To get a list of all the plugins available, open the Nix REPL and run
<screen>
<prompt>$ </prompt>nix repl
:l &lt;nixpkgs&gt;
map (p: p.name) pkgs.rxvt-unicode.plugins
</screen>
Alternatively, if your shell is bash or zsh and have completion enabled,
simply type <literal>nixpkgs.rxvt-unicode.plugins.&lt;tab&gt;</literal>.
</para>
<para>
In addition to <literal>plugins</literal> the options
<literal>extraDeps</literal> and <literal>perlDeps</literal> can be used
to install extra packages.
<literal>extraDeps</literal> can be used, for example, to provide
<literal>xsel</literal> (a clipboard manager) to the clipboard plugin,
without installing it globally:
<programlisting>
rxvt-unicode.override {
configure = { availablePlugins, ... }: {
pluginsDeps = [ xsel ];
};
}
</programlisting>
<literal>perlDeps</literal> is a handy way to provide Perl packages to
your custom plugins (in <literal>$HOME/.urxvt/ext</literal>). For example,
if you need <literal>AnyEvent</literal> you can do:
<programlisting>
rxvt-unicode.override {
configure = { availablePlugins, ... }: {
perlDeps = with perlPackages; [ AnyEvent ];
};
}
</programlisting>
</para>
</section>
<section xml:id="sec-urxvt-pkg">
<title>Packaging urxvt plugins</title>
<para>
Urxvt plugins resides in
<literal>pkgs/applications/misc/rxvt-unicode-plugins</literal>.
To add a new plugin create an expression in a subdirectory and add the
package to the set in
<literal>pkgs/applications/misc/rxvt-unicode-plugins/default.nix</literal>.
</para>
<para>
A plugin can be any kind of derivation, the only requirement is that it
should always install perl scripts in <literal>$out/lib/urxvt/perl</literal>.
Look for existing plugins for examples.
</para>
<para>
If the plugin is itself a perl package that needs to be imported from
other plugins or scripts, add the following passthrough:
<programlisting>
passthru.perlPackages = [ "self" ];
</programlisting>
This will make the urxvt wrapper pick up the dependency and set up the perl
path accordingly.
</para>
</section>
</section>