From d49ed1bac7b61e737388a82ebaef4b8d873dc463 Mon Sep 17 00:00:00 2001
From: Graham Dumpleton <Graham.Dumpleton@gmail.com>
Date: Fri, 13 Sep 2024 14:24:50 +1000
Subject: [PATCH] Add docs for WSGIMapHEADToGET directive.

---
 .../WSGIMapHEADToGET.rst                      | 23 +++++++++++++++++++
 docs/configuration.rst                        |  1 +
 2 files changed, 24 insertions(+)
 create mode 100644 docs/configuration-directives/WSGIMapHEADToGET.rst

diff --git a/docs/configuration-directives/WSGIMapHEADToGET.rst b/docs/configuration-directives/WSGIMapHEADToGET.rst
new file mode 100644
index 00000000..bb218bd3
--- /dev/null
+++ b/docs/configuration-directives/WSGIMapHEADToGET.rst
@@ -0,0 +1,23 @@
+==================
+WSGIMapHEADToGET
+==================
+
+:Description: Enable/disable mapping of HEAD request to GET.
+:Syntax: ``WSGIMapHEADToGET On|Off|Auto``
+:Default: ``WSGIMapHEADToGET Auto``
+:Context: server config, virtual host, directory, .htaccess
+
+The ``WSGIMapHEADToGET`` directive controls the behaviour of automatically
+mapping any ``HEAD`` request to a ``GET`` request when an Apache output filter
+is registered that may want to see the complete response in order to generate
+correct response headers.
+
+The directive can be set to be either ``Auto`` (the default), ``On`` which
+will always map a ``HEAD`` to ``GET`` even if no output filters detected and
+``Off`` to always preserve the original request method type.
+
+The directive may be required where a WSGI application tries to optimize and
+avoid doing work for a ``HEAD`` request by not actually generating a response
+so that complete response headers can still be generated. By doing this the
+WSGI application can break Apache filters for caching, so the mapping of
+``HEAD`` to ``GET`` can be required to avoid problems.
diff --git a/docs/configuration.rst b/docs/configuration.rst
index b296210c..08b185b5 100644
--- a/docs/configuration.rst
+++ b/docs/configuration.rst
@@ -17,6 +17,7 @@ Configuration
    configuration-directives/WSGIDestroyInterpreter
    configuration-directives/WSGIImportScript
    configuration-directives/WSGILazyInitialization
+   configuration-directives/WSGIMapHEADToGET
    configuration-directives/WSGIPassAuthorization
    configuration-directives/WSGIProcessGroup
    configuration-directives/WSGIPythonEggs