doc: Improve code listings

By adding prompts and removing unnecessary indentation.
This commit is contained in:
Jan Tojnar 2020-09-23 00:38:04 +02:00
parent 47297487c5
commit e1af37634b
No known key found for this signature in database
GPG key ID: 7FAB2A15F7A607A4
13 changed files with 173 additions and 161 deletions

View file

@ -132,11 +132,11 @@ buildImage {
<para> <para>
By default <function>buildImage</function> will use a static date of one second past the UNIX Epoch. This allows <function>buildImage</function> to produce binary reproducible images. When listing images with <command>docker images</command>, the newly created images will be listed like this: By default <function>buildImage</function> will use a static date of one second past the UNIX Epoch. This allows <function>buildImage</function> to produce binary reproducible images. When listing images with <command>docker images</command>, the newly created images will be listed like this:
</para> </para>
<screen><![CDATA[ <screen>
$ docker images <prompt>$ </prompt>docker images
REPOSITORY TAG IMAGE ID CREATED SIZE REPOSITORY TAG IMAGE ID CREATED SIZE
hello latest 08c791c7846e 48 years ago 25.2MB hello latest 08c791c7846e 48 years ago 25.2MB
]]></screen> </screen>
<para> <para>
You can break binary reproducibility but have a sorted, meaningful <literal>CREATED</literal> column by setting <literal>created</literal> to <literal>now</literal>. You can break binary reproducibility but have a sorted, meaningful <literal>CREATED</literal> column by setting <literal>created</literal> to <literal>now</literal>.
</para> </para>
@ -152,11 +152,11 @@ pkgs.dockerTools.buildImage {
]]></programlisting> ]]></programlisting>
<para> <para>
and now the Docker CLI will display a reasonable date and sort the images as expected: and now the Docker CLI will display a reasonable date and sort the images as expected:
<screen><![CDATA[ <screen>
$ docker images <prompt>$ </prompt>docker images
REPOSITORY TAG IMAGE ID CREATED SIZE REPOSITORY TAG IMAGE ID CREATED SIZE
hello latest de2bf4786de6 About a minute ago 25.2MB hello latest de2bf4786de6 About a minute ago 25.2MB
]]></screen> </screen>
however, the produced images will not be binary reproducible. however, the produced images will not be binary reproducible.
</para> </para>
</example> </example>

View file

@ -38,7 +38,6 @@ buildContainer {
readonly = false; <co xml:id='ex-ociTools-buildContainer-3' /> readonly = false; <co xml:id='ex-ociTools-buildContainer-3' />
} }
</programlisting> </programlisting>
<calloutlist> <calloutlist>
<callout arearefs='ex-ociTools-buildContainer-1'> <callout arearefs='ex-ociTools-buildContainer-1'>

View file

@ -18,10 +18,13 @@
includes all available plugins. To make use of this functionality, use an includes all available plugins. To make use of this functionality, use an
overlay or directly install an expression that overrides its configuration, overlay or directly install an expression that overrides its configuration,
such as such as
<programlisting>rxvt-unicode.override { configure = { availablePlugins, ... }: { <programlisting>
rxvt-unicode.override {
configure = { availablePlugins, ... }: {
plugins = with availablePlugins; [ perls resize-font vtwheel ]; plugins = with availablePlugins; [ perls resize-font vtwheel ];
};
} }
}</programlisting> </programlisting>
If the <literal>configure</literal> function returns an attrset without the If the <literal>configure</literal> function returns an attrset without the
<literal>plugins</literal> attribute, <literal>availablePlugins</literal> <literal>plugins</literal> attribute, <literal>availablePlugins</literal>
will be used automatically. will be used automatically.
@ -30,18 +33,22 @@
<para> <para>
In order to add plugins but also keep all default plugins installed, it is In order to add plugins but also keep all default plugins installed, it is
possible to use the following method: possible to use the following method:
<programlisting>rxvt-unicode.override { configure = { availablePlugins, ... }: { <programlisting>
rxvt-unicode.override {
configure = { availablePlugins, ... }: {
plugins = (builtins.attrValues availablePlugins) ++ [ custom-plugin ]; plugins = (builtins.attrValues availablePlugins) ++ [ custom-plugin ];
}; };
}</programlisting> }
</programlisting>
</para> </para>
<para> <para>
To get a list of all the plugins available, open the Nix REPL and run To get a list of all the plugins available, open the Nix REPL and run
<programlisting>$ nix repl <screen>
<prompt>$ </prompt>nix repl
:l &lt;nixpkgs&gt; :l &lt;nixpkgs&gt;
map (p: p.name) pkgs.rxvt-unicode.plugins map (p: p.name) pkgs.rxvt-unicode.plugins
</programlisting> </screen>
Alternatively, if your shell is bash or zsh and have completion enabled, Alternatively, if your shell is bash or zsh and have completion enabled,
simply type <literal>nixpkgs.rxvt-unicode.plugins.&lt;tab&gt;</literal>. simply type <literal>nixpkgs.rxvt-unicode.plugins.&lt;tab&gt;</literal>.
</para> </para>
@ -53,18 +60,24 @@ map (p: p.name) pkgs.rxvt-unicode.plugins
<literal>extraDeps</literal> can be used, for example, to provide <literal>extraDeps</literal> can be used, for example, to provide
<literal>xsel</literal> (a clipboard manager) to the clipboard plugin, <literal>xsel</literal> (a clipboard manager) to the clipboard plugin,
without installing it globally: without installing it globally:
<programlisting>rxvt-unicode.override { configure = { availablePlugins, ... }: { <programlisting>
rxvt-unicode.override {
configure = { availablePlugins, ... }: {
pluginsDeps = [ xsel ]; pluginsDeps = [ xsel ];
};
} }
}</programlisting> </programlisting>
<literal>perlDeps</literal> is a handy way to provide Perl packages to <literal>perlDeps</literal> is a handy way to provide Perl packages to
your custom plugins (in <literal>$HOME/.urxvt/ext</literal>). For example, your custom plugins (in <literal>$HOME/.urxvt/ext</literal>). For example,
if you need <literal>AnyEvent</literal> you can do: if you need <literal>AnyEvent</literal> you can do:
<programlisting>rxvt-unicode.override { configure = { availablePlugins, ... }: { <programlisting>
rxvt-unicode.override {
configure = { availablePlugins, ... }: {
perlDeps = with perlPackages; [ AnyEvent ]; perlDeps = with perlPackages; [ AnyEvent ];
};
} }
}</programlisting> </programlisting>
</para> </para>
</section> </section>
@ -90,7 +103,8 @@ map (p: p.name) pkgs.rxvt-unicode.plugins
<para> <para>
If the plugin is itself a perl package that needs to be imported from If the plugin is itself a perl package that needs to be imported from
other plugins or scripts, add the following passthrough: other plugins or scripts, add the following passthrough:
<programlisting>passthru.perlPackages = [ "self" ]; <programlisting>
passthru.perlPackages = [ "self" ];
</programlisting> </programlisting>
This will make the urxvt wrapper pick up the dependency and set up the perl This will make the urxvt wrapper pick up the dependency and set up the perl
path accordingly. path accordingly.

View file

@ -12,14 +12,14 @@
</para> </para>
<screen> <screen>
<![CDATA[$ cd pkgs/servers/monitoring <prompt>$ </prompt>cd pkgs/servers/monitoring
$ mkdir sensu <prompt>$ </prompt>mkdir sensu
$ cd sensu <prompt>$ </prompt>cd sensu
$ cat > Gemfile <prompt>$ </prompt>cat > Gemfile
source 'https://rubygems.org' source 'https://rubygems.org'
gem 'sensu' gem 'sensu'
$ $(nix-build '<nixpkgs>' -A bundix --no-out-link)/bin/bundix --magic <prompt>$ </prompt>$(nix-build '&lt;nixpkgs>' -A bundix --no-out-link)/bin/bundix --magic
$ cat > default.nix <prompt>$ </prompt>cat > default.nix
{ lib, bundlerEnv, ruby }: { lib, bundlerEnv, ruby }:
bundlerEnv rec { bundlerEnv rec {
@ -37,7 +37,7 @@ bundlerEnv rec {
maintainers = with maintainers; [ theuni ]; maintainers = with maintainers; [ theuni ];
platforms = platforms.unix; platforms = platforms.unix;
}; };
}]]> }
</screen> </screen>
<para> <para>
@ -49,17 +49,16 @@ bundlerEnv rec {
</para> </para>
<screen> <screen>
<![CDATA[$ cd pkgs/servers/monitoring/sensu <prompt>$ </prompt>cd pkgs/servers/monitoring/sensu
$ nix-shell -p bundler --run 'bundle lock --update' <prompt>$ </prompt>nix-shell -p bundler --run 'bundle lock --update'
$ nix-shell -p bundix --run 'bundix' <prompt>$ </prompt>nix-shell -p bundix --run 'bundix'
]]>
</screen> </screen>
<para> <para>
For tools written in Ruby - i.e. where the desire is to install a package and then execute e.g. <command>rake</command> at the command line, there is an alternative builder called <literal>bundlerApp</literal>. Set up the <filename>gemset.nix</filename> the same way, and then, for example: For tools written in Ruby - i.e. where the desire is to install a package and then execute e.g. <command>rake</command> at the command line, there is an alternative builder called <literal>bundlerApp</literal>. Set up the <filename>gemset.nix</filename> the same way, and then, for example:
</para> </para>
<screen> <programlisting>
<![CDATA[{ lib, bundlerApp }: <![CDATA[{ lib, bundlerApp }:
bundlerApp { bundlerApp {
@ -75,7 +74,7 @@ bundlerApp {
platforms = platforms.unix; platforms = platforms.unix;
}; };
}]]> }]]>
</screen> </programlisting>
<para> <para>
The chief advantage of <literal>bundlerApp</literal> over <literal>bundlerEnv</literal> is the executables introduced in the environment are precisely those selected in the <literal>exes</literal> list, as opposed to <literal>bundlerEnv</literal> which adds all the executables made available by gems in the gemset, which can mean e.g. <command>rspec</command> or <command>rake</command> in unpredictable versions available from various packages. The chief advantage of <literal>bundlerApp</literal> over <literal>bundlerEnv</literal> is the executables introduced in the environment are precisely those selected in the <literal>exes</literal> list, as opposed to <literal>bundlerEnv</literal> which adds all the executables made available by gems in the gemset, which can mean e.g. <command>rspec</command> or <command>rake</command> in unpredictable versions available from various packages.

View file

@ -44,11 +44,11 @@ texlive.combine {
<listitem> <listitem>
<para> <para>
You can list packages e.g. by <command>nix repl</command>. You can list packages e.g. by <command>nix repl</command>.
<programlisting><![CDATA[ <programlisting>
$ nix repl <prompt>$ </prompt>nix repl
nix-repl> :l <nixpkgs> <prompt>nix-repl> </prompt>:l &lt;nixpkgs>
nix-repl> texlive.collection-<TAB> <prompt>nix-repl> </prompt>texlive.collection-<keycap function="tab" />
]]></programlisting> </programlisting>
</para> </para>
</listitem> </listitem>
<listitem> <listitem>

View file

@ -67,7 +67,7 @@
<para> <para>
<command>nix-env</command> silenty disregards the outputs selected by the user, and instead installs the outputs from <varname>meta.outputsToInstall</varname>. For example, <command>nix-env</command> silenty disregards the outputs selected by the user, and instead installs the outputs from <varname>meta.outputsToInstall</varname>. For example,
</para> </para>
<programlisting>$ nix-env -iA nixpkgs.coreutils.info</programlisting> <screen><prompt>$ </prompt>nix-env -iA nixpkgs.coreutils.info</screen>
<para> <para>
installs the <literal>"out"</literal> output (<varname>coreutils.meta.outputsToInstall</varname> is <literal>[ "out" ]</literal>) instead of the requested <literal>"info"</literal>. installs the <literal>"out"</literal> output (<varname>coreutils.meta.outputsToInstall</varname> is <literal>[ "out" ]</literal>) instead of the requested <literal>"info"</literal>.
</para> </para>

View file

@ -66,7 +66,7 @@
<listitem> <listitem>
<para> <para>
For allowing the build of a broken package once, you can use an environment variable for a single invocation of the nix tools: For allowing the build of a broken package once, you can use an environment variable for a single invocation of the nix tools:
<programlisting>$ export NIXPKGS_ALLOW_BROKEN=1</programlisting> <screen><prompt>$ </prompt>export NIXPKGS_ALLOW_BROKEN=1</screen>
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
@ -92,7 +92,7 @@
<listitem> <listitem>
<para> <para>
For allowing the build of an unsupported package once, you can use an environment variable for a single invocation of the nix tools: For allowing the build of an unsupported package once, you can use an environment variable for a single invocation of the nix tools:
<programlisting>$ export NIXPKGS_ALLOW_UNSUPPORTED_SYSTEM=1</programlisting> <screen><prompt>$ </prompt>export NIXPKGS_ALLOW_UNSUPPORTED_SYSTEM=1</screen>
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
@ -122,7 +122,7 @@
<listitem> <listitem>
<para> <para>
To temporarily allow all unfree packages, you can use an environment variable for a single invocation of the nix tools: To temporarily allow all unfree packages, you can use an environment variable for a single invocation of the nix tools:
<programlisting>$ export NIXPKGS_ALLOW_UNFREE=1</programlisting> <screen><prompt>$ </prompt>export NIXPKGS_ALLOW_UNFREE=1</screen>
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
@ -187,7 +187,7 @@
<listitem> <listitem>
<para> <para>
To temporarily allow all insecure packages, you can use an environment variable for a single invocation of the nix tools: To temporarily allow all insecure packages, you can use an environment variable for a single invocation of the nix tools:
<programlisting>$ export NIXPKGS_ALLOW_INSECURE=1</programlisting> <screen><prompt>$ </prompt>export NIXPKGS_ALLOW_INSECURE=1</screen>
</para> </para>
</listitem> </listitem>
<listitem> <listitem>

View file

@ -248,9 +248,9 @@ self: super:
<literal>libblas.so.3</literal> and <literal>libblas.so.3</literal> and
<literal>liblapack.so.3</literal>. For instance: <literal>liblapack.so.3</literal>. For instance:
</para> </para>
<programlisting> <screen>
$ LD_LIBRARY_PATH=$(nix-build -A mkl)/lib:$LD_LIBRARY_PATH nix-shell -p octave --run octave <prompt>$ </prompt>LD_LIBRARY_PATH=$(nix-build -A mkl)/lib:$LD_LIBRARY_PATH nix-shell -p octave --run octave
</programlisting> </screen>
<para> <para>
Intel MKL requires an <literal>openmp</literal> implementation Intel MKL requires an <literal>openmp</literal> implementation
when running with multiple processors. By default, when running with multiple processors. By default,