nixos: nixos/doc/manual/development/writing-documentation.xml to CommonMark

4 files changed, 238 insertions, 151 deletions

diff --git a/nixos/doc/manual/development/development.xml b/nixos/doc/manual/development/development.xml
index 05c6a5b1134..670a391e380 100644
--- a/nixos/doc/manual/development/development.xml
+++ b/nixos/doc/manual/development/development.xml
@@ -12,7 +12,7 @@
  <xi:include href="../from_md/development/sources.chapter.xml" />
  <xi:include href="writing-modules.xml" />
  <xi:include href="../from_md/development/building-parts.chapter.xml" />
- <xi:include href="writing-documentation.xml" />
+ <xi:include href="../from_md/development/writing-documentation.chapter.xml" />
  <xi:include href="../from_md/development/building-nixos.chapter.xml" />
  <xi:include href="nixos-tests.xml" />
  <xi:include href="../from_md/development/testing-installer.chapter.xml" />
diff --git a/nixos/doc/manual/development/writing-documentation.chapter.md b/nixos/doc/manual/development/writing-documentation.chapter.md
new file mode 100644
index 00000000000..7c29f600d70
--- /dev/null
+++ b/nixos/doc/manual/development/writing-documentation.chapter.md
@@ -0,0 +1,93 @@
+# Writing NixOS Documentation {#sec-writing-documentation}
+
+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.
+
+## Building the Manual {#sec-writing-docs-building-the-manual}
+
+The DocBook sources of the [](#book-nixos-manual) are in the
+[`nixos/doc/manual`](https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual)
+subdirectory of the Nixpkgs repository.
+
+You can quickly validate your edits with `make`:
+
+```ShellSession
+$ cd /path/to/nixpkgs/nixos/doc/manual
+$ nix-shell
+nix-shell$ make
+```
+
+Once you are done making modifications to the manual, it\'s important to
+build it before committing. You can do that as follows:
+
+```ShellSession
+nix-build nixos/release.nix -A manual.x86_64-linux
+```
+
+When this command successfully finishes, it will tell you where the
+manual got generated. The HTML will be accessible through the `result`
+symlink at `./result/share/doc/nixos/index.html`.
+
+## Editing DocBook XML {#sec-writing-docs-editing-docbook-xml}
+
+For general information on how to write in DocBook, see [DocBook 5: The
+Definitive Guide](http://www.docbook.org/tdg5/en/html/docbook.html).
+
+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 [](#sec-emacs-docbook-xml).
+
+[Pandoc](http://pandoc.org) 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:
+
+```ShellSession
+pandoc -f markdown_github -t docbook5 docs.md -o my-section.md
+```
+
+Pandoc can also quickly convert a single `section.xml` to HTML, which is
+helpful when drafting.
+
+Sometimes writing valid DocBook is simply too difficult. In this case,
+submit your documentation updates in a [GitHub
+Issue](https://github.com/NixOS/nixpkgs/issues/new) and someone will
+handle the conversion to XML for you.
+
+## Creating a Topic {#sec-writing-docs-creating-a-topic}
+
+You can use an existing topic as a basis for the new topic or create a
+topic from scratch.
+
+Keep the following guidelines in mind when you create and add a topic:
+
+-   The NixOS [`book`](http://www.docbook.org/tdg5/en/html/book.html)
+    element is in `nixos/doc/manual/manual.xml`. It includes several
+    [`parts`](http://www.docbook.org/tdg5/en/html/book.html) which are in
+    subdirectories.
+
+-   Store the topic file in the same directory as the `part` to which it
+    belongs. If your topic is about configuring a NixOS module, then the
+    XML file can be stored alongside the module definition `nix` file.
+
+-   If you include multiple words in the file name, separate the words
+    with a dash. For example: `ipv6-config.xml`.
+
+-   Make sure that the `xml:id` value is unique. You can use abbreviations
+    if the ID is too long. For example: `nixos-config`.
+
+-   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.
+
+## Adding a Topic to the Book {#sec-writing-docs-adding-a-topic}
+
+Open the parent XML file and add an `xi:include` element to the list of
+chapters with the file name of the topic that you created. If you
+created a `section`, you add the file to the `chapter` file. If you created
+a `chapter`, you add the file to the `part` file.
+
+If the topic is about configuring a NixOS module, it can be
+automatically included in the manual by using the `meta.doc` attribute.
+See [](#sec-meta-attributes) for an explanation.
diff --git a/nixos/doc/manual/development/writing-documentation.xml b/nixos/doc/manual/development/writing-documentation.xml
deleted file mode 100644
index 89fab666561..00000000000
--- a/nixos/doc/manual/development/writing-documentation.xml
+++ /dev/null
@@ -1,150 +0,0 @@
-<chapter xmlns="http://docbook.org/ns/docbook"
-        xmlns:xlink="http://www.w3.org/1999/xlink"
-        xmlns:xi="http://www.w3.org/2001/XInclude"
-        version="5.0"
-        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"><filename>nixos/doc/manual</filename></link>
-   subdirectory of the Nixpkgs repository.
-  </para>
-
-  <para>
-   You can quickly validate your edits with <command>make</command>:
-  </para>
-
-<screen>
-<prompt>$ </prompt>cd /path/to/nixpkgs/nixos/doc/manual
-<prompt>$ </prompt>nix-shell
-<prompt>nix-shell$ </prompt>make
-</screen>
-
-  <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>
-
-<screen>nix-build nixos/release.nix -A manual.x86_64-linux</screen>
-
-  <para>
-   When this command successfully finishes, it will tell you where the manual
-   got generated. The HTML will be accessible through the
-   <filename>result</filename> symlink at
-   <filename>./result/share/doc/nixos/index.html</filename>.
-  </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.
-   <example xml:id="ex-pandoc-xml-conv">
-    <title>Pandoc invocation to convert GitHub-Flavoured MarkDown to DocBook 5 XML</title>
-<screen>pandoc -f markdown_github -t docbook5 docs.md -o my-section.md</screen>
-   </example>
-   Pandoc can also quickly convert a single <filename>section.xml</filename> 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:
-   <itemizedlist>
-    <listitem>
-     <para>
-      The NixOS
-      <link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><tag>book</tag></link>
-      element is in <filename>nixos/doc/manual/manual.xml</filename>. It
-      includes several
-      <link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><tag>part</tag>s</link>
-      which are in subdirectories.
-     </para>
-    </listitem>
-    <listitem>
-     <para>
-      Store the topic file in the same directory as the <tag>part</tag> to
-      which it belongs. If your topic is about configuring a NixOS module, then
-      the XML file can be stored alongside the module definition
-      <filename>nix</filename> file.
-     </para>
-    </listitem>
-    <listitem>
-     <para>
-      If you include multiple words in the file name, separate the words with a
-      dash. For example: <filename>ipv6-config.xml</filename>.
-     </para>
-    </listitem>
-    <listitem>
-     <para>
-      Make sure that the <tag>xml:id</tag> value is unique. You can use
-      abbreviations if the ID is too long. For example:
-      <varname>nixos-config</varname>.
-     </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>
-  </para>
- </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 <varname>xi:include</varname> element to
-   the list of chapters with the file name of the topic that you created. If
-   you created a <tag>section</tag>, you add the file to the <tag>chapter</tag>
-   file. If you created a <tag>chapter</tag>, you add the file to the
-   <tag>part</tag> file.
-  </para>
-
-  <para>
-   If the topic is about configuring a NixOS module, it can be automatically
-   included in the manual by using the <varname>meta.doc</varname> attribute.
-   See <xref
-  linkend="sec-meta-attributes"/> for an explanation.
-  </para>
- </section>
-</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>