Commit 0c601b12 authored by pennae's avatar pennae Committed by pennae
Browse files

nixos/manual: translate manpages to mdoc 

since we want to move away from docbook and having docbook manpages
around is going to block further progress we have to translate the
current nixos manpages from docbook it *something* else. mdoc seems the
most appropriate choice since markdown can't represent all the things
manpages can differentiate with even more extensions. if we ever need
html manpages we can render them using troff, like many of the online
manpage viewers, or rewrite them again. since we haven't had html
manpages for any of these in many years that seems unlikely to happen.

unlike most of the recent markdown conversions this comes with a lot of
minor rendering changes, mostly in spacing. docbook-xslt creates manual
pages in a very different dialect than mdoc (which is used here).
parent b73b082c

nixos/doc/manual/default.nix

+7 −2
Original line number Diff line number Diff line
@@ -254,12 +254,17 @@ in rec { 
  # Generate the NixOS manpages.

  manpages = runCommand "nixos-manpages"

    { inherit sources;

      nativeBuildInputs = [ buildPackages.libxml2.bin buildPackages.libxslt.bin ];

      nativeBuildInputs = [

        buildPackages.libxml2.bin

        buildPackages.libxslt.bin

        buildPackages.installShellFiles

      ];

      allowedReferences = ["out"];

    }

    ''

      # Generate manpages.

      mkdir -p $out/share/man

      mkdir -p $out/share/man/man8

      installManPage ${./manpages}/*

      xsltproc --nonet \

        --maxdepth 6000 \

        --param man.output.in.separate.dir 1 \

nixos/doc/manual/man-nixos-build-vms.xml

deleted100644 → 0
+0 −138
Original line number Diff line number Diff line 
<refentry xmlns="http://docbook.org/ns/docbook"

          xmlns:xlink="http://www.w3.org/1999/xlink"

          xmlns:xi="http://www.w3.org/2001/XInclude">

 <refmeta>

  <refentrytitle><command>nixos-build-vms</command>

  </refentrytitle><manvolnum>8</manvolnum>

  <refmiscinfo class="source">NixOS</refmiscinfo>

<!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> -->

 </refmeta>

 <refnamediv>

  <refname><command>nixos-build-vms</command></refname>

  <refpurpose>build a network of virtual machines from a network of NixOS configurations</refpurpose>

 </refnamediv>

 <refsynopsisdiv>

  <cmdsynopsis>

   <command>nixos-build-vms</command>

   <arg>

    <option>--show-trace</option>

   </arg>



   <arg>

    <option>--no-out-link</option>

   </arg>



   <arg>

    <option>--help</option>

  </arg>



  <arg>

    <option>--option</option>

    <replaceable>name</replaceable>

    <replaceable>value</replaceable>

  </arg>



   <arg choice="plain">

    <replaceable>network.nix</replaceable>

   </arg>

  </cmdsynopsis>

 </refsynopsisdiv>

 <refsection>

  <title>Description</title>

  <para>

   This command builds a network of QEMU-KVM virtual machines of a Nix

   expression specifying a network of NixOS machines. The virtual network can

   be started by executing the <filename>bin/run-vms</filename> shell script

   that is generated by this command. By default, a <filename>result</filename>

   symlink is produced that points to the generated virtual network.

  </para>

  <para>

   A network Nix expression has the following structure:

<screen>

{

  test1 = {pkgs, config, ...}:

    {

      services.openssh.enable = true;

      nixpkgs.localSystem.system = "i686-linux";

      deployment.targetHost = "test1.example.net";



      # Other NixOS options

    };



  test2 = {pkgs, config, ...}:

    {

      services.openssh.enable = true;

      services.httpd.enable = true;

      environment.systemPackages = [ pkgs.lynx ];

      nixpkgs.localSystem.system = "x86_64-linux";

      deployment.targetHost = "test2.example.net";



      # Other NixOS options

    };

}

</screen>

   Each attribute in the expression represents a machine in the network (e.g.

   <varname>test1</varname> and <varname>test2</varname>) referring to a

   function defining a NixOS configuration. In each NixOS configuration, two

   attributes have a special meaning. The

   <varname>deployment.targetHost</varname> specifies the address (domain name

   or IP address) of the system which is used by <command>ssh</command> to

   perform remote deployment operations. The

   <varname>nixpkgs.localSystem.system</varname> attribute can be used to

   specify an architecture for the target machine, such as

   <varname>i686-linux</varname> which builds a 32-bit NixOS configuration.

   Omitting this property will build the configuration for the same

   architecture as the host system.

  </para>

 </refsection>

 <refsection>

  <title>Options</title>

  <para>

   This command accepts the following options:

  </para>

  <variablelist>

   <varlistentry>

    <term>

     <option>--show-trace</option>

    </term>

    <listitem>

     <para>

      Shows a trace of the output.

     </para>

    </listitem>

   </varlistentry>

   <varlistentry>

    <term>

     <option>--no-out-link</option>

    </term>

    <listitem>

     <para>

      Do not create a 'result' symlink.

     </para>

    </listitem>

   </varlistentry>

   <varlistentry>

    <term>

     <option>-h</option>, <option>--help</option>

    </term>

    <listitem>

     <para>

      Shows the usage of this command to the user.

     </para>

    </listitem>

   </varlistentry>

   <varlistentry>

    <term>

     <option>--option</option> <replaceable>name</replaceable> <replaceable>value</replaceable>

    </term>

    <listitem>

     <para>Set the Nix configuration option

      <replaceable>name</replaceable> to <replaceable>value</replaceable>.

      This overrides settings in the Nix configuration file (see

      <citerefentry><refentrytitle>nix.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).

     </para>

    </listitem>

   </varlistentry>

  </variablelist>

 </refsection>

</refentry>

nixos/doc/manual/man-nixos-enter.xml

deleted100644 → 0
+0 −154
Original line number Diff line number Diff line 
<refentry xmlns="http://docbook.org/ns/docbook"

          xmlns:xlink="http://www.w3.org/1999/xlink"

          xmlns:xi="http://www.w3.org/2001/XInclude">

 <refmeta>

  <refentrytitle><command>nixos-enter</command>

  </refentrytitle><manvolnum>8</manvolnum>

  <refmiscinfo class="source">NixOS</refmiscinfo>

<!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> -->

 </refmeta>

 <refnamediv>

  <refname><command>nixos-enter</command></refname>

  <refpurpose>run a command in a NixOS chroot environment</refpurpose>

 </refnamediv>

 <refsynopsisdiv>

  <cmdsynopsis>

   <command>nixos-enter</command>

   <arg>

    <arg choice='plain'>

     <option>--root</option>

    </arg>

     <replaceable>root</replaceable>

   </arg>



   <arg>

    <arg choice='plain'>

     <option>--system</option>

    </arg>

     <replaceable>system</replaceable>

   </arg>



   <arg>

    <arg choice='plain'>

     <option>-c</option>

    </arg>

     <replaceable>shell-command</replaceable>

   </arg>



   <arg>

    <arg choice='plain'>

     <option>--silent</option>

    </arg>

   </arg>



   <arg>

    <arg choice='plain'>

     <option>--help</option>

    </arg>

   </arg>



   <arg>

    <arg choice='plain'>

     <option>--</option>

    </arg>

     <replaceable>arguments</replaceable>

   </arg>

  </cmdsynopsis>

 </refsynopsisdiv>

 <refsection>

  <title>Description</title>

  <para>

   This command runs a command in a NixOS chroot environment, that is, in a

   filesystem hierarchy previously prepared using

   <command>nixos-install</command>.

  </para>

 </refsection>

 <refsection>

  <title>Options</title>

  <para>

   This command accepts the following options:

  </para>

  <variablelist>

   <varlistentry>

    <term>

     <option>--root</option>

    </term>

    <listitem>

     <para>

      The path to the NixOS system you want to enter. It defaults to

      <filename>/mnt</filename>.

     </para>

    </listitem>

   </varlistentry>

   <varlistentry>

    <term>

     <option>--system</option>

    </term>

    <listitem>

     <para>

      The NixOS system configuration to use. It defaults to

      <filename>/nix/var/nix/profiles/system</filename>. You can enter a

      previous NixOS configuration by specifying a path such as

      <filename>/nix/var/nix/profiles/system-106-link</filename>.

     </para>

    </listitem>

   </varlistentry>

   <varlistentry>

    <term>

     <option>--command</option>

    </term>

    <term>

     <option>-c</option>

    </term>

    <listitem>

     <para>

      The bash command to execute.

     </para>

    </listitem>

   </varlistentry>

   <varlistentry>

    <term>

     <option>--silent</option>

    </term>

    <listitem>

     <para>

       Suppresses all output from the activation script of the target system.

     </para>

    </listitem>

   </varlistentry>

   <varlistentry>

    <term>

     <option>--</option>

    </term>

    <listitem>

     <para>

      Interpret the remaining arguments as the program name and arguments to be

      invoked. The program is not executed in a shell.

     </para>

    </listitem>

   </varlistentry>

  </variablelist>

 </refsection>

 <refsection>

  <title>Examples</title>

  <para>

   Start an interactive shell in the NixOS installation in

   <filename>/mnt</filename>:

  </para>

<screen>

<prompt># </prompt>nixos-enter --root /mnt

</screen>

  <para>

   Run a shell command:

  </para>

<screen>

<prompt># </prompt>nixos-enter -c 'ls -l /; cat /proc/mounts'

</screen>

  <para>

   Run a non-shell command:

  </para>

<screen>

# nixos-enter -- cat /proc/mounts

</screen>

 </refsection>

</refentry>

nixos/doc/manual/man-nixos-generate-config.xml

deleted100644 → 0
+0 −214
Original line number Diff line number Diff line 
<refentry xmlns="http://docbook.org/ns/docbook"

          xmlns:xlink="http://www.w3.org/1999/xlink"

          xmlns:xi="http://www.w3.org/2001/XInclude">

 <refmeta>

  <refentrytitle><command>nixos-generate-config</command>

  </refentrytitle><manvolnum>8</manvolnum>

  <refmiscinfo class="source">NixOS</refmiscinfo>

<!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> -->

 </refmeta>

 <refnamediv>

  <refname><command>nixos-generate-config</command></refname>

  <refpurpose>generate NixOS configuration modules</refpurpose>

 </refnamediv>

 <refsynopsisdiv>

  <cmdsynopsis>

   <command>nixos-generate-config</command>

   <arg>

    <option>--force</option>

   </arg>



   <arg>

    <arg choice='plain'>

     <option>--root</option>

    </arg>

     <replaceable>root</replaceable>

   </arg>



   <arg>

    <arg choice='plain'>

     <option>--dir</option>

    </arg>

     <replaceable>dir</replaceable>

   </arg>

  </cmdsynopsis>

 </refsynopsisdiv>

 <refsection>

  <title>Description</title>

  <para>

   This command writes two NixOS configuration modules:

   <variablelist>

    <varlistentry>

     <term>

      <option>/etc/nixos/hardware-configuration.nix</option>

     </term>

     <listitem>

      <para>

       This module sets NixOS configuration options based on your current

       hardware configuration. In particular, it sets the

       <option>fileSystem</option> option to reflect all currently mounted file

       systems, the <option>swapDevices</option> option to reflect active swap

       devices, and the <option>boot.initrd.*</option> options to ensure that

       the initial ramdisk contains any kernel modules necessary for mounting

       the root file system.

      </para>

      <para>

       If this file already exists, it is overwritten. Thus, you should not

       modify it manually. Rather, you should include it from your

       <filename>/etc/nixos/configuration.nix</filename>, and re-run

       <command>nixos-generate-config</command> to update it whenever your

       hardware configuration changes.

      </para>

     </listitem>

    </varlistentry>

    <varlistentry>

     <term>

      <option>/etc/nixos/configuration.nix</option>

     </term>

     <listitem>

      <para>

       This is the main NixOS system configuration module. If it already

       exists, it’s left unchanged. Otherwise,

       <command>nixos-generate-config</command> will write a template for you

       to customise.

      </para>

     </listitem>

    </varlistentry>

   </variablelist>

  </para>

 </refsection>

 <refsection>

  <title>Options</title>

  <para>

   This command accepts the following options:

  </para>

  <variablelist>

   <varlistentry>

    <term>

     <option>--root</option>

    </term>

    <listitem>

     <para>

      If this option is given, treat the directory

      <replaceable>root</replaceable> as the root of the file system. This

      means that configuration files will be written to

      <filename><replaceable>root</replaceable>/etc/nixos</filename>, and that

      any file systems outside of <replaceable>root</replaceable> are ignored

      for the purpose of generating the <option>fileSystems</option> option.

     </para>

    </listitem>

   </varlistentry>

   <varlistentry>

    <term>

     <option>--dir</option>

    </term>

    <listitem>

     <para>

      If this option is given, write the configuration files to the directory

      <replaceable>dir</replaceable> instead of

      <filename>/etc/nixos</filename>.

     </para>

    </listitem>

   </varlistentry>

   <varlistentry>

    <term>

     <option>--force</option>

    </term>

    <listitem>

     <para>

      Overwrite <filename>/etc/nixos/configuration.nix</filename> if it already

      exists.

     </para>

    </listitem>

   </varlistentry>

   <varlistentry>

    <term>

     <option>--no-filesystems</option>

    </term>

    <listitem>

     <para>

      Omit everything concerning file systems and swap devices from the

      hardware configuration.

     </para>

    </listitem>

   </varlistentry>

   <varlistentry>

    <term>

     <option>--show-hardware-config</option>

    </term>

    <listitem>

     <para>

      Don't generate <filename>configuration.nix</filename> or

      <filename>hardware-configuration.nix</filename> and print the hardware

      configuration to stdout only.

     </para>

    </listitem>

   </varlistentry>

  </variablelist>

 </refsection>

 <refsection>

  <title>Examples</title>

  <para>

   This command is typically used during NixOS installation to write initial

   configuration modules. For example, if you created and mounted the target

   file systems on <filename>/mnt</filename> and

   <filename>/mnt/boot</filename>, you would run:

<screen>

<prompt>$ </prompt>nixos-generate-config --root /mnt

</screen>

   The resulting file

   <filename>/mnt/etc/nixos/hardware-configuration.nix</filename> might look

   like this:

<programlisting>

# Do not modify this file!  It was generated by ‘nixos-generate-config’

# and may be overwritten by future invocations.  Please make changes

# to /etc/nixos/configuration.nix instead.

{ config, pkgs, ... }:



{

  imports =

    [ &lt;nixos/modules/installer/scan/not-detected.nix&gt;

    ];



  boot.initrd.availableKernelModules = [ "ehci_hcd" "ahci" ];

  boot.kernelModules = [ "kvm-intel" ];

  boot.extraModulePackages = [ ];



  fileSystems."/" =

    { device = "/dev/disk/by-label/nixos";

      fsType = "ext3";

      options = [ "rw" "data=ordered" "relatime" ];

    };



  fileSystems."/boot" =

    { device = "/dev/sda1";

      fsType = "ext3";

      options = [ "rw" "errors=continue" "user_xattr" "acl" "barrier=1" "data=writeback" "relatime" ];

    };



  swapDevices =

    [ { device = "/dev/sda2"; }

    ];



  nix.maxJobs = 8;

}

</programlisting>

   It will also create a basic

   <filename>/mnt/etc/nixos/configuration.nix</filename>, which you should edit

   to customise the logical configuration of your system. This file includes

   the result of the hardware scan as follows:

<programlisting>

  imports = [ ./hardware-configuration.nix ];

</programlisting>

  </para>

  <para>

   After installation, if your hardware configuration changes, you can run:

<screen>

<prompt>$ </prompt>nixos-generate-config

</screen>

   to update <filename>/etc/nixos/hardware-configuration.nix</filename>. Your

   <filename>/etc/nixos/configuration.nix</filename> will

   <emphasis>not</emphasis> be overwritten.

  </para>

 </refsection>

</refentry>

nixos/doc/manual/man-nixos-install.xml

deleted100644 → 0
+0 −357

File deleted.

Preview size limit exceeded, changes collapsed.