nixos: nixos/doc/manual/configuration/subversion.xml to CommonMark

4 files changed, 225 insertions, 141 deletions

diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml
index 56574680f9c..a1d0d139aa5 100644
--- a/nixos/doc/manual/configuration/configuration.xml
+++ b/nixos/doc/manual/configuration/configuration.xml
@@ -23,7 +23,7 @@
  <xi:include href="../from_md/configuration/xfce.chapter.xml" />
  <xi:include href="networking.xml" />
  <xi:include href="../from_md/configuration/linux-kernel.chapter.xml" />
- <xi:include href="subversion.xml" />
+ <xi:include href="../from_md/configuration/subversion.chapter.xml" />
  <xi:include href="../generated/modules.xml" xpointer="xpointer(//section[@id='modules']/*)" />
  <xi:include href="profiles.xml" />
  <xi:include href="kubernetes.xml" />
diff --git a/nixos/doc/manual/configuration/subversion.chapter.md b/nixos/doc/manual/configuration/subversion.chapter.md
new file mode 100644
index 00000000000..72efdb09acb
--- /dev/null
+++ b/nixos/doc/manual/configuration/subversion.chapter.md
@@ -0,0 +1,102 @@
+# Subversion {#module-services-subversion}
+
+[Subversion](https://subversion.apache.org/) is a centralized
+version-control system. It can use a [variety of
+protocols](http://svnbook.red-bean.com/en/1.7/svn-book.html#svn.serverconfig.choosing)
+for communication between client and server.
+
+## Subversion inside Apache HTTP {#module-services-subversion-apache-httpd}
+
+This section focuses on configuring a web-based server on top of the
+Apache HTTP server, which uses
+[WebDAV](http://www.webdav.org/)/[DeltaV](http://www.webdav.org/deltav/WWW10/deltav-intro.htm)
+for communication.
+
+For more information on the general setup, please refer to the [the
+appropriate section of the Subversion
+book](http://svnbook.red-bean.com/en/1.7/svn-book.html#svn.serverconfig.httpd).
+
+To configure, include in `/etc/nixos/configuration.nix` code to activate
+Apache HTTP, setting [`services.httpd.adminAddr`](options.html#opt-services.httpd.adminAddr)
+appropriately:
+
+```nix
+services.httpd.enable = true;
+services.httpd.adminAddr = ...;
+networking.firewall.allowedTCPPorts = [ 80 443 ];
+```
+
+For a simple Subversion server with basic authentication, configure the
+Subversion module for Apache as follows, setting `hostName` and
+`documentRoot` appropriately, and `SVNParentPath` to the parent
+directory of the repositories, `AuthzSVNAccessFile` to the location of
+the `.authz` file describing access permission, and `AuthUserFile` to
+the password file.
+
+```nix
+services.httpd.extraModules = [
+    # note that order is *super* important here
+    { name = "dav_svn"; path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_dav_svn.so"; }
+    { name = "authz_svn"; path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_authz_svn.so"; }
+  ];
+  services.httpd.virtualHosts = {
+    "svn" = {
+       hostName = HOSTNAME;
+       documentRoot = DOCUMENTROOT;
+       locations."/svn".extraConfig = ''
+           DAV svn
+           SVNParentPath REPO_PARENT
+           AuthzSVNAccessFile ACCESS_FILE
+           AuthName "SVN Repositories"
+           AuthType Basic
+           AuthUserFile PASSWORD_FILE
+           Require valid-user
+      '';
+    }
+```
+
+The key `"svn"` is just a symbolic name identifying the virtual host.
+The `"/svn"` in `locations."/svn".extraConfig` is the path underneath
+which the repositories will be served.
+
+[This page](https://wiki.archlinux.org/index.php/Subversion) explains
+how to set up the Subversion configuration itself. This boils down to
+the following:
+
+Underneath `REPO_PARENT` repositories can be set up as follows:
+
+```ShellSession
+$ svn create REPO_NAME
+```
+
+Repository files need to be accessible by `wwwrun`:
+
+```ShellSession
+$ chown -R wwwrun:wwwrun REPO_PARENT
+```
+
+The password file `PASSWORD_FILE` can be created as follows:
+
+```ShellSession
+$ htpasswd -cs PASSWORD_FILE USER_NAME
+```
+
+Additional users can be set up similarly, omitting the `c` flag:
+
+```ShellSession
+$ htpasswd -s PASSWORD_FILE USER_NAME
+```
+
+The file describing access permissions `ACCESS_FILE` will look something
+like the following:
+
+```nix
+[/]
+* = r
+
+[REPO_NAME:/]
+USER_NAME = rw
+```
+
+The Subversion repositories will be accessible as
+`http://HOSTNAME/svn/REPO_NAME`.
diff --git a/nixos/doc/manual/configuration/subversion.xml b/nixos/doc/manual/configuration/subversion.xml
deleted file mode 100644
index 940d63cc4e6..00000000000
--- a/nixos/doc/manual/configuration/subversion.xml
+++ /dev/null
@@ -1,140 +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="module-services-subversion">
-  <title>Subversion</title>
-
- <para>
-  <link xlink:href="https://subversion.apache.org/">Subversion</link>
-  is a centralized version-control system.  It can use a <link
-  xlink:href="http://svnbook.red-bean.com/en/1.7/svn-book.html#svn.serverconfig.choosing">variety
-  of protocols</link> for communication between client and server.
- </para>
- <section xml:id="module-services-subversion-apache-httpd">
-  <title>Subversion inside Apache HTTP</title>
-
-   <para>
-   This section focuses on configuring a web-based server on top of
-   the Apache HTTP server, which uses
-   <link xlink:href="http://www.webdav.org/">WebDAV</link>/<link
-   xlink:href="http://www.webdav.org/deltav/WWW10/deltav-intro.htm">DeltaV</link>
-   for communication.
-   </para>
-
-   <para>For more information on the general setup, please refer to
-   the <link
-   xlink:href="http://svnbook.red-bean.com/en/1.7/svn-book.html#svn.serverconfig.httpd">the
-   appropriate section of the Subversion book</link>.
-   </para>
-
-   <para>To configure, include in
-   <literal>/etc/nixos/configuration.nix</literal> code to activate
-   Apache HTTP, setting <xref linkend="opt-services.httpd.adminAddr" />
-   appropriately:
-   </para>
-
-    <para>
-<programlisting>
-  services.httpd.enable = true;
-  services.httpd.adminAddr = ...;
-  networking.firewall.allowedTCPPorts = [ 80 443 ];
-</programlisting>
-    </para>
-
-    <para>For a simple Subversion server with basic authentication,
-    configure the Subversion module for Apache as follows, setting
-    <literal>hostName</literal> and <literal>documentRoot</literal>
-    appropriately, and <literal>SVNParentPath</literal> to the parent
-    directory of the repositories,
-    <literal>AuthzSVNAccessFile</literal> to the location of the
-    <code>.authz</code> file describing access permission, and
-    <literal>AuthUserFile</literal> to the password file.
-    </para>
-    <para>
-<programlisting>
-services.httpd.extraModules = [
-    # note that order is *super* important here
-    { name = "dav_svn"; path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_dav_svn.so"; }
-    { name = "authz_svn"; path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_authz_svn.so"; }
-  ];
-  services.httpd.virtualHosts = {
-    "svn" = {
-       hostName = HOSTNAME;
-       documentRoot = DOCUMENTROOT;
-       locations."/svn".extraConfig = ''
-           DAV svn
-           SVNParentPath REPO_PARENT
-           AuthzSVNAccessFile ACCESS_FILE
-           AuthName "SVN Repositories"
-           AuthType Basic
-           AuthUserFile PASSWORD_FILE
-           Require valid-user
-      '';
-    }
-</programlisting>
-    </para>
-
-    <para>
-    The key <code>"svn"</code> is just a symbolic name identifying the
-    virtual host.  The <code>"/svn"</code> in
-    <code>locations."/svn".extraConfig</code> is the path underneath
-    which the repositories will be served.
-    </para>
-
-    <para><link
-              xlink:href="https://wiki.archlinux.org/index.php/Subversion">This
-    page</link> explains how to set up the Subversion configuration
-    itself.  This boils down to the following:
-    </para>
-    <para>
-      Underneath <literal>REPO_PARENT</literal> repositories can be set up
-      as follows:
-    </para>
-    <para>
-<screen>
-<prompt>$ </prompt> svn create REPO_NAME
-</screen>
-    </para>
-    <para>Repository files need to be accessible by
-    <literal>wwwrun</literal>:
-    </para>
-    <para>
-<screen>
-<prompt>$ </prompt> chown -R wwwrun:wwwrun REPO_PARENT
-</screen>
-    </para>
-    <para>
-      The password file <literal>PASSWORD_FILE</literal> can be created as follows:
-    </para>
-    <para>
-<screen>
-<prompt>$ </prompt> htpasswd -cs PASSWORD_FILE USER_NAME
-</screen>
-    </para>
-    <para>
-    Additional users can be set up similarly, omitting the
-    <code>c</code> flag:
-    </para>
-    <para>
-<screen>
-<prompt>$ </prompt> htpasswd -s PASSWORD_FILE USER_NAME
-</screen>
-    </para>
-    <para>
-      The file describing access permissions
-      <literal>ACCESS_FILE</literal> will look something like
-      the following:
-    </para>
-    <para>
-<programlisting>
-[/]
-* = r
-
-[REPO_NAME:/]
-USER_NAME = rw
-</programlisting>
-    </para>
-    <para>The Subversion repositories will be accessible as <code>http://HOSTNAME/svn/REPO_NAME</code>.</para>
- </section>
-</chapter>
diff --git a/nixos/doc/manual/from_md/configuration/subversion.chapter.xml b/nixos/doc/manual/from_md/configuration/subversion.chapter.xml
new file mode 100644
index 00000000000..3bea116d498
--- /dev/null
+++ b/nixos/doc/manual/from_md/configuration/subversion.chapter.xml
@@ -0,0 +1,122 @@
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-subversion">
+  <title>Subversion</title>
+  <para>
+    <link xlink:href="https://subversion.apache.org/">Subversion</link>
+    is a centralized version-control system. It can use a
+    <link xlink:href="http://svnbook.red-bean.com/en/1.7/svn-book.html#svn.serverconfig.choosing">variety
+    of protocols</link> for communication between client and server.
+  </para>
+  <section xml:id="module-services-subversion-apache-httpd">
+    <title>Subversion inside Apache HTTP</title>
+    <para>
+      This section focuses on configuring a web-based server on top of
+      the Apache HTTP server, which uses
+      <link xlink:href="http://www.webdav.org/">WebDAV</link>/<link xlink:href="http://www.webdav.org/deltav/WWW10/deltav-intro.htm">DeltaV</link>
+      for communication.
+    </para>
+    <para>
+      For more information on the general setup, please refer to the
+      <link xlink:href="http://svnbook.red-bean.com/en/1.7/svn-book.html#svn.serverconfig.httpd">the
+      appropriate section of the Subversion book</link>.
+    </para>
+    <para>
+      To configure, include in
+      <literal>/etc/nixos/configuration.nix</literal> code to activate
+      Apache HTTP, setting
+      <link xlink:href="options.html#opt-services.httpd.adminAddr"><literal>services.httpd.adminAddr</literal></link>
+      appropriately:
+    </para>
+    <programlisting language="bash">
+services.httpd.enable = true;
+services.httpd.adminAddr = ...;
+networking.firewall.allowedTCPPorts = [ 80 443 ];
+</programlisting>
+    <para>
+      For a simple Subversion server with basic authentication,
+      configure the Subversion module for Apache as follows, setting
+      <literal>hostName</literal> and <literal>documentRoot</literal>
+      appropriately, and <literal>SVNParentPath</literal> to the parent
+      directory of the repositories,
+      <literal>AuthzSVNAccessFile</literal> to the location of the
+      <literal>.authz</literal> file describing access permission, and
+      <literal>AuthUserFile</literal> to the password file.
+    </para>
+    <programlisting language="bash">
+services.httpd.extraModules = [
+    # note that order is *super* important here
+    { name = &quot;dav_svn&quot;; path = &quot;${pkgs.apacheHttpdPackages.subversion}/modules/mod_dav_svn.so&quot;; }
+    { name = &quot;authz_svn&quot;; path = &quot;${pkgs.apacheHttpdPackages.subversion}/modules/mod_authz_svn.so&quot;; }
+  ];
+  services.httpd.virtualHosts = {
+    &quot;svn&quot; = {
+       hostName = HOSTNAME;
+       documentRoot = DOCUMENTROOT;
+       locations.&quot;/svn&quot;.extraConfig = ''
+           DAV svn
+           SVNParentPath REPO_PARENT
+           AuthzSVNAccessFile ACCESS_FILE
+           AuthName &quot;SVN Repositories&quot;
+           AuthType Basic
+           AuthUserFile PASSWORD_FILE
+           Require valid-user
+      '';
+    }
+</programlisting>
+    <para>
+      The key <literal>&quot;svn&quot;</literal> is just a symbolic name
+      identifying the virtual host. The
+      <literal>&quot;/svn&quot;</literal> in
+      <literal>locations.&quot;/svn&quot;.extraConfig</literal> is the
+      path underneath which the repositories will be served.
+    </para>
+    <para>
+      <link xlink:href="https://wiki.archlinux.org/index.php/Subversion">This
+      page</link> explains how to set up the Subversion configuration
+      itself. This boils down to the following:
+    </para>
+    <para>
+      Underneath <literal>REPO_PARENT</literal> repositories can be set
+      up as follows:
+    </para>
+    <programlisting>
+$ svn create REPO_NAME
+</programlisting>
+    <para>
+      Repository files need to be accessible by
+      <literal>wwwrun</literal>:
+    </para>
+    <programlisting>
+$ chown -R wwwrun:wwwrun REPO_PARENT
+</programlisting>
+    <para>
+      The password file <literal>PASSWORD_FILE</literal> can be created
+      as follows:
+    </para>
+    <programlisting>
+$ htpasswd -cs PASSWORD_FILE USER_NAME
+</programlisting>
+    <para>
+      Additional users can be set up similarly, omitting the
+      <literal>c</literal> flag:
+    </para>
+    <programlisting>
+$ htpasswd -s PASSWORD_FILE USER_NAME
+</programlisting>
+    <para>
+      The file describing access permissions
+      <literal>ACCESS_FILE</literal> will look something like the
+      following:
+    </para>
+    <programlisting language="bash">
+[/]
+* = r
+
+[REPO_NAME:/]
+USER_NAME = rw
+</programlisting>
+    <para>
+      The Subversion repositories will be accessible as
+      <literal>http://HOSTNAME/svn/REPO_NAME</literal>.
+    </para>
+  </section>
+</chapter>