From 58baa3f39cf06fd82106be89a143976c28b21b55 Mon Sep 17 00:00:00 2001
From: Justus K <justus.k@protonmail.com>
Date: Wed, 2 Dec 2020 20:14:05 +0100
Subject: [PATCH] convert nginx documentation to common mark

---
 doc/builders/packages/index.xml        |  2 +-
 doc/builders/packages/nginx.section.md | 11 +++++++++++
 doc/builders/packages/nginx.xml        | 25 -------------------------
 3 files changed, 12 insertions(+), 26 deletions(-)
 create mode 100644 doc/builders/packages/nginx.section.md
 delete mode 100644 doc/builders/packages/nginx.xml

diff --git a/doc/builders/packages/index.xml b/doc/builders/packages/index.xml
index ba59ceb016b6..44e89169629d 100644
--- a/doc/builders/packages/index.xml
+++ b/doc/builders/packages/index.xml
@@ -14,7 +14,7 @@
  <xi:include href="kakoune.section.xml" />
  <xi:include href="linux.xml" />
  <xi:include href="locales.xml" />
- <xi:include href="nginx.xml" />
+ <xi:include href="nginx.section.xml" />
  <xi:include href="opengl.section.xml" />
  <xi:include href="shell-helpers.xml" />
  <xi:include href="steam.xml" />
diff --git a/doc/builders/packages/nginx.section.md b/doc/builders/packages/nginx.section.md
new file mode 100644
index 000000000000..154c21f9b369
--- /dev/null
+++ b/doc/builders/packages/nginx.section.md
@@ -0,0 +1,11 @@
+# Nginx {#sec-nginx}
+
+[Nginx](https://nginx.org) is a reverse proxy and lightweight webserver.
+
+## ETags on static files served from the Nix store {#sec-nginx-etag}
+
+HTTP has a couple different mechanisms for caching to prevent clients from having to download the same content repeatedly if a resource has not changed since the last time it was requested. When nginx is used as a server for static files, it implements the caching mechanism based on the [`Last-Modified`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Last-Modified) response header automatically; unfortunately, it works by using filesystem timestamps to determine the value of the `Last-Modified` header. This doesn't give the desired behavior when the file is in the Nix store, because all file timestamps are set to 0 (for reasons related to build reproducibility).
+
+Fortunately, HTTP supports an alternative (and more effective) caching mechanism: the [`ETag`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) response header. The value of the `ETag` header specifies some identifier for the particular content that the server is sending (e.g. a hash). When a client makes a second request for the same resource, it sends that value back in an `If-None-Match` header. If the ETag value is unchanged, then the server does not need to resend the content.
+
+As of NixOS 19.09, the nginx package in Nixpkgs is patched such that when nginx serves a file out of `/nix/store`, the hash in the store path is used as the `ETag` header in the HTTP response, thus providing proper caching functionality. This happens automatically; you do not need to do modify any configuration to get this behavior.
diff --git a/doc/builders/packages/nginx.xml b/doc/builders/packages/nginx.xml
deleted file mode 100644
index 65854ba02366..000000000000
--- a/doc/builders/packages/nginx.xml
+++ /dev/null
@@ -1,25 +0,0 @@
-<section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xml:id="sec-nginx">
- <title>Nginx</title>
-
- <para>
-  <link xlink:href="https://nginx.org/">Nginx</link> is a reverse proxy and lightweight webserver.
- </para>
-
- <section xml:id="sec-nginx-etag">
-  <title>ETags on static files served from the Nix store</title>
-
-  <para>
-   HTTP has a couple different mechanisms for caching to prevent clients from having to download the same content repeatedly if a resource has not changed since the last time it was requested. When nginx is used as a server for static files, it implements the caching mechanism based on the <link xlink:href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Last-Modified"><literal>Last-Modified</literal></link> response header automatically; unfortunately, it works by using filesystem timestamps to determine the value of the <literal>Last-Modified</literal> header. This doesn't give the desired behavior when the file is in the Nix store, because all file timestamps are set to 0 (for reasons related to build reproducibility).
-  </para>
-
-  <para>
-   Fortunately, HTTP supports an alternative (and more effective) caching mechanism: the <link xlink:href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag"><literal>ETag</literal></link> response header. The value of the <literal>ETag</literal> header specifies some identifier for the particular content that the server is sending (e.g. a hash). When a client makes a second request for the same resource, it sends that value back in an <literal>If-None-Match</literal> header. If the ETag value is unchanged, then the server does not need to resend the content.
-  </para>
-
-  <para>
-   As of NixOS 19.09, the nginx package in Nixpkgs is patched such that when nginx serves a file out of <filename>/nix/store</filename>, the hash in the store path is used as the <literal>ETag</literal> header in the HTTP response, thus providing proper caching functionality. This happens automatically; you do not need to do modify any configuration to get this behavior.
-  </para>
- </section>
-</section>