Merge pull request #129074 from bobby285271/pr11

nixos/doc: convert Chapter 57, 59, 60, 63 to CommonMark

4 files changed, 380 insertions, 0 deletions

diff --git a/nixos/doc/manual/from_md/development/building-parts.chapter.xml b/nixos/doc/manual/from_md/development/building-parts.chapter.xml
new file mode 100644
index 00000000000..4df24cc9565
--- /dev/null
+++ b/nixos/doc/manual/from_md/development/building-parts.chapter.xml
@@ -0,0 +1,124 @@
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-building-parts">
+  <title>Building Specific Parts of NixOS</title>
+  <para>
+    With the command <literal>nix-build</literal>, you can build
+    specific parts of your NixOS configuration. This is done as follows:
+  </para>
+  <programlisting>
+$ cd /path/to/nixpkgs/nixos
+$ nix-build -A config.option
+</programlisting>
+  <para>
+    where <literal>option</literal> is a NixOS option with type
+    <quote>derivation</quote> (i.e. something that can be built).
+    Attributes of interest include:
+  </para>
+  <variablelist>
+    <varlistentry>
+      <term>
+        <literal>system.build.toplevel</literal>
+      </term>
+      <listitem>
+        <para>
+          The top-level option that builds the entire NixOS system.
+          Everything else in your configuration is indirectly pulled in
+          by this option. This is what <literal>nixos-rebuild</literal>
+          builds and what <literal>/run/current-system</literal> points
+          to afterwards.
+        </para>
+        <para>
+          A shortcut to build this is:
+        </para>
+        <programlisting>
+$ nix-build -A system
+</programlisting>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>
+        <literal>system.build.manual.manualHTML</literal>
+      </term>
+      <listitem>
+        <para>
+          The NixOS manual.
+        </para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>
+        <literal>system.build.etc</literal>
+      </term>
+      <listitem>
+        <para>
+          A tree of symlinks that form the static parts of
+          <literal>/etc</literal>.
+        </para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>
+        <literal>system.build.initialRamdisk</literal> ,
+        <literal>system.build.kernel</literal>
+      </term>
+      <listitem>
+        <para>
+          The initial ramdisk and kernel of the system. This allows a
+          quick way to test whether the kernel and the initial ramdisk
+          boot correctly, by using QEMU’s <literal>-kernel</literal> and
+          <literal>-initrd</literal> options:
+        </para>
+        <programlisting>
+$ nix-build -A config.system.build.initialRamdisk -o initrd
+$ nix-build -A config.system.build.kernel -o kernel
+$ qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/null
+</programlisting>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>
+        <literal>system.build.nixos-rebuild</literal> ,
+        <literal>system.build.nixos-install</literal> ,
+        <literal>system.build.nixos-generate-config</literal>
+      </term>
+      <listitem>
+        <para>
+          These build the corresponding NixOS commands.
+        </para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>
+        <literal>systemd.units.unit-name.unit</literal>
+      </term>
+      <listitem>
+        <para>
+          This builds the unit with the specified name. Note that since
+          unit names contain dots (e.g.
+          <literal>httpd.service</literal>), you need to put them
+          between quotes, like this:
+        </para>
+        <programlisting>
+$ nix-build -A 'config.systemd.units.&quot;httpd.service&quot;.unit'
+</programlisting>
+        <para>
+          You can also test individual units, without rebuilding the
+          whole system, by putting them in
+          <literal>/run/systemd/system</literal>:
+        </para>
+        <programlisting>
+$ cp $(nix-build -A 'config.systemd.units.&quot;httpd.service&quot;.unit')/httpd.service \
+    /run/systemd/system/tmp-httpd.service
+# systemctl daemon-reload
+# systemctl start tmp-httpd.service
+</programlisting>
+        <para>
+          Note that the unit must not have the same name as any unit in
+          <literal>/etc/systemd/system</literal> since those take
+          precedence over <literal>/run/systemd/system</literal>. That’s
+          why the unit is installed as
+          <literal>tmp-httpd.service</literal> here.
+        </para>
+      </listitem>
+    </varlistentry>
+  </variablelist>
+</chapter>
diff --git a/nixos/doc/manual/from_md/development/sources.chapter.xml b/nixos/doc/manual/from_md/development/sources.chapter.xml
new file mode 100644
index 00000000000..aac18c9d06c
--- /dev/null
+++ b/nixos/doc/manual/from_md/development/sources.chapter.xml
@@ -0,0 +1,90 @@
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-getting-sources">
+  <title>Getting the Sources</title>
+  <para>
+    By default, NixOS’s <literal>nixos-rebuild</literal> command uses
+    the NixOS and Nixpkgs sources provided by the
+    <literal>nixos</literal> channel (kept in
+    <literal>/nix/var/nix/profiles/per-user/root/channels/nixos</literal>).
+    To modify NixOS, however, you should check out the latest sources
+    from Git. This is as follows:
+  </para>
+  <programlisting>
+$ git clone https://github.com/NixOS/nixpkgs
+$ cd nixpkgs
+$ git remote update origin
+</programlisting>
+  <para>
+    This will check out the latest Nixpkgs sources to
+    <literal>./nixpkgs</literal> the NixOS sources to
+    <literal>./nixpkgs/nixos</literal>. (The NixOS source tree lives in
+    a subdirectory of the Nixpkgs repository.) The
+    <literal>nixpkgs</literal> repository has branches that correspond
+    to each Nixpkgs/NixOS channel (see <xref linkend="sec-upgrading" />
+    for more information about channels). Thus, the Git branch
+    <literal>origin/nixos-17.03</literal> will contain the latest built
+    and tested version available in the <literal>nixos-17.03</literal>
+    channel.
+  </para>
+  <para>
+    It’s often inconvenient to develop directly on the master branch,
+    since if somebody has just committed (say) a change to GCC, then the
+    binary cache may not have caught up yet and you’ll have to rebuild
+    everything from source. So you may want to create a local branch
+    based on your current NixOS version:
+  </para>
+  <programlisting>
+$ nixos-version
+17.09pre104379.6e0b727 (Hummingbird)
+
+$ git checkout -b local 6e0b727
+</programlisting>
+  <para>
+    Or, to base your local branch on the latest version available in a
+    NixOS channel:
+  </para>
+  <programlisting>
+$ git remote update origin
+$ git checkout -b local origin/nixos-17.03
+</programlisting>
+  <para>
+    (Replace <literal>nixos-17.03</literal> with the name of the channel
+    you want to use.) You can use <literal>git merge</literal> or
+    <literal>git rebase</literal> to keep your local branch in sync with
+    the channel, e.g.
+  </para>
+  <programlisting>
+$ git remote update origin
+$ git merge origin/nixos-17.03
+</programlisting>
+  <para>
+    You can use <literal>git cherry-pick</literal> to copy commits from
+    your local branch to the upstream branch.
+  </para>
+  <para>
+    If you want to rebuild your system using your (modified) sources,
+    you need to tell <literal>nixos-rebuild</literal> about them using
+    the <literal>-I</literal> flag:
+  </para>
+  <programlisting>
+# nixos-rebuild switch -I nixpkgs=/my/sources/nixpkgs
+</programlisting>
+  <para>
+    If you want <literal>nix-env</literal> to use the expressions in
+    <literal>/my/sources</literal>, use
+    <literal>nix-env -f /my/sources/nixpkgs</literal>, or change the
+    default by adding a symlink in <literal>~/.nix-defexpr</literal>:
+  </para>
+  <programlisting>
+$ ln -s /my/sources/nixpkgs ~/.nix-defexpr/nixpkgs
+</programlisting>
+  <para>
+    You may want to delete the symlink
+    <literal>~/.nix-defexpr/channels_root</literal> to prevent root’s
+    NixOS channel from clashing with your own tree (this may break the
+    command-not-found utility though). If you want to go back to the
+    default state, you may just remove the
+    <literal>~/.nix-defexpr</literal> directory completely, log out and
+    log in again and it should have been recreated with a link to the
+    root channels.
+  </para>
+</chapter>
diff --git a/nixos/doc/manual/from_md/development/testing-installer.chapter.xml b/nixos/doc/manual/from_md/development/testing-installer.chapter.xml
new file mode 100644
index 00000000000..286d49f3c29
--- /dev/null
+++ b/nixos/doc/manual/from_md/development/testing-installer.chapter.xml
@@ -0,0 +1,22 @@
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="ch-testing-installer">
+  <title>Testing the Installer</title>
+  <para>
+    Building, burning, and booting from an installation CD is rather
+    tedious, so here is a quick way to see if the installer works
+    properly:
+  </para>
+  <programlisting>
+# mount -t tmpfs none /mnt
+# nixos-generate-config --root /mnt
+$ nix-build '&lt;nixpkgs/nixos&gt;' -A config.system.build.nixos-install
+# ./result/bin/nixos-install
+</programlisting>
+  <para>
+    To start a login shell in the new NixOS installation in
+    <literal>/mnt</literal>:
+  </para>
+  <programlisting>
+$ nix-build '&lt;nixpkgs/nixos&gt;' -A config.system.build.nixos-enter
+# ./result/bin/nixos-enter
+</programlisting>
+</chapter>
diff --git a/nixos/doc/manual/from_md/development/writing-documentation.chapter.xml b/nixos/doc/manual/from_md/development/writing-documentation.chapter.xml
new file mode 100644
index 00000000000..a42067f4e99
--- /dev/null
+++ b/nixos/doc/manual/from_md/development/writing-documentation.chapter.xml
@@ -0,0 +1,144 @@
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-writing-documentation">
+  <title>Writing NixOS Documentation</title>
+  <para>
+    As NixOS grows, so too does the need for a catalogue and explanation
+    of its extensive functionality. Collecting pertinent information
+    from disparate sources and presenting it in an accessible style
+    would be a worthy contribution to the project.
+  </para>
+  <section xml:id="sec-writing-docs-building-the-manual">
+    <title>Building the Manual</title>
+    <para>
+      The DocBook sources of the <xref linkend="book-nixos-manual" />
+      are in the
+      <link xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual"><literal>nixos/doc/manual</literal></link>
+      subdirectory of the Nixpkgs repository.
+    </para>
+    <para>
+      You can quickly validate your edits with <literal>make</literal>:
+    </para>
+    <programlisting>
+$ cd /path/to/nixpkgs/nixos/doc/manual
+$ nix-shell
+nix-shell$ make
+</programlisting>
+    <para>
+      Once you are done making modifications to the manual, it's
+      important to build it before committing. You can do that as
+      follows:
+    </para>
+    <programlisting>
+nix-build nixos/release.nix -A manual.x86_64-linux
+</programlisting>
+    <para>
+      When this command successfully finishes, it will tell you where
+      the manual got generated. The HTML will be accessible through the
+      <literal>result</literal> symlink at
+      <literal>./result/share/doc/nixos/index.html</literal>.
+    </para>
+  </section>
+  <section xml:id="sec-writing-docs-editing-docbook-xml">
+    <title>Editing DocBook XML</title>
+    <para>
+      For general information on how to write in DocBook, see
+      <link xlink:href="http://www.docbook.org/tdg5/en/html/docbook.html">DocBook
+      5: The Definitive Guide</link>.
+    </para>
+    <para>
+      Emacs nXML Mode is very helpful for editing DocBook XML because it
+      validates the document as you write, and precisely locates errors.
+      To use it, see <xref linkend="sec-emacs-docbook-xml" />.
+    </para>
+    <para>
+      <link xlink:href="http://pandoc.org">Pandoc</link> can generate
+      DocBook XML from a multitude of formats, which makes a good
+      starting point. Here is an example of Pandoc invocation to convert
+      GitHub-Flavoured MarkDown to DocBook 5 XML:
+    </para>
+    <programlisting>
+pandoc -f markdown_github -t docbook5 docs.md -o my-section.md
+</programlisting>
+    <para>
+      Pandoc can also quickly convert a single
+      <literal>section.xml</literal> to HTML, which is helpful when
+      drafting.
+    </para>
+    <para>
+      Sometimes writing valid DocBook is simply too difficult. In this
+      case, submit your documentation updates in a
+      <link xlink:href="https://github.com/NixOS/nixpkgs/issues/new">GitHub
+      Issue</link> and someone will handle the conversion to XML for
+      you.
+    </para>
+  </section>
+  <section xml:id="sec-writing-docs-creating-a-topic">
+    <title>Creating a Topic</title>
+    <para>
+      You can use an existing topic as a basis for the new topic or
+      create a topic from scratch.
+    </para>
+    <para>
+      Keep the following guidelines in mind when you create and add a
+      topic:
+    </para>
+    <itemizedlist>
+      <listitem>
+        <para>
+          The NixOS
+          <link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><literal>book</literal></link>
+          element is in <literal>nixos/doc/manual/manual.xml</literal>.
+          It includes several
+          <link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><literal>parts</literal></link>
+          which are in subdirectories.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Store the topic file in the same directory as the
+          <literal>part</literal> to which it belongs. If your topic is
+          about configuring a NixOS module, then the XML file can be
+          stored alongside the module definition <literal>nix</literal>
+          file.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          If you include multiple words in the file name, separate the
+          words with a dash. For example:
+          <literal>ipv6-config.xml</literal>.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Make sure that the <literal>xml:id</literal> value is unique.
+          You can use abbreviations if the ID is too long. For example:
+          <literal>nixos-config</literal>.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Determine whether your topic is a chapter or a section. If you
+          are unsure, open an existing topic file and check whether the
+          main element is chapter or section.
+        </para>
+      </listitem>
+    </itemizedlist>
+  </section>
+  <section xml:id="sec-writing-docs-adding-a-topic">
+    <title>Adding a Topic to the Book</title>
+    <para>
+      Open the parent XML file and add an <literal>xi:include</literal>
+      element to the list of chapters with the file name of the topic
+      that you created. If you created a <literal>section</literal>, you
+      add the file to the <literal>chapter</literal> file. If you
+      created a <literal>chapter</literal>, you add the file to the
+      <literal>part</literal> file.
+    </para>
+    <para>
+      If the topic is about configuring a NixOS module, it can be
+      automatically included in the manual by using the
+      <literal>meta.doc</literal> attribute. See
+      <xref linkend="sec-meta-attributes" /> for an explanation.
+    </para>
+  </section>
+</chapter>