From c7b3863a1dc22e4117a8930f3fa785714ffe3f82 Mon Sep 17 00:00:00 2001
From: Natalia <124304+nessita@users.noreply.github.com>
Date: Tue, 16 Jul 2024 17:20:05 -0300
Subject: [PATCH] Refs #10941 -- Reorganized querystring template tag docs.

---
 docs/ref/templates/builtins.txt | 86 +++++++++++++++++++++++----------
 1 file changed, 60 insertions(+), 26 deletions(-)

diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt
index b920478700259..f429322478e7a 100644
--- a/docs/ref/templates/builtins.txt
+++ b/docs/ref/templates/builtins.txt
@@ -959,66 +959,100 @@ output (as a string) inside a variable. This is useful if you want to use
 
 .. versionadded:: 5.1
 
-Outputs the query string from a given :class:`~django.http.QueryDict` instance,
-if provided, or ``request.GET`` if not and the
-``django.template.context_processors.request`` context processor is enabled.
-If the ``QueryDict`` is empty, then the output will be an empty string.
-Otherwise, the query string will be returned with a leading ``"?"``.
+Outputs a URL-encoded formatted query string based on the provided parameters.
 
-If not using the ``django.template.context_processors.request`` context
-processor, you must pass either the ``request`` into the template context or a
-``QueryDict`` instance into this tag.
+This tag requires a :class:`~django.http.QueryDict` instance, which defaults to
+:attr:`request.GET <django.http.HttpRequest.GET>` if none is provided, to
+generate the resulting query string from the passed key-value pairs.
 
-The following example outputs the current query string verbatim. So if the
-query string is ``?color=green&size=M``, the output would be
-``?color=green&size=M``:
+If the :class:`~django.http.QueryDict` is empty and no additional parameters
+are provided, an empty string is returned. A non-empty result includes a
+leading ``"?"``.
+
+.. admonition:: Using ``request.GET`` as default
+
+    To use ``request.GET`` as the default ``QueryDict`` instance, the
+    ``django.template.context_processors.request`` context processor should be
+    enabled. If it's not enabled, you must either explicitly pass the
+    ``request`` object into the template context, or provide a ``QueryDict``
+    instance to this tag.
+
+Basic usage
+~~~~~~~~~~~
 
 .. code-block:: html+django
 
     {% querystring %}
 
-You can also pass in a custom ``QueryDict`` that will be used instead of
-``request.GET``:
+Outputs the current query string verbatim. So if the query string is
+``?color=green``, the output would be ``?color=green``.
+
+.. code-block:: html+django
+
+    {% querystring size="M" %}
+
+Outputs the current query string with the addition of the ``size`` parameter.
+Following the previous example, the output would be ``?color=green&size=M``.
+
+Custom QueryDict
+~~~~~~~~~~~~~~~~
 
 .. code-block:: html+django
 
     {% querystring my_query_dict %}
 
-Each keyword argument will be added to the query string, replacing any existing
-value for that key. With the query string ``?color=blue``, the following would
-result in ``?color=red&size=S``:
+You can provide a custom ``QueryDict`` to be used instead of ``request.GET``.
+So if ``my_query_dict`` is ``<QueryDict: {'color': ['green']}>``, this outputs
+``?color=green``.
+
+Setting items
+~~~~~~~~~~~~~
 
 .. code-block:: html+django
 
     {% querystring color="red" size="S" %}
 
-It is possible to remove parameters by passing ``None`` as a value. With the
-query string ``?color=blue&size=M``, the following would result in ``?size=M``:
+Adds or modifies parameters in the query string. For instance, if the current
+query string is ``?color=green``, the output will be ``?color=red&size=S``.
+
+Removing items
+~~~~~~~~~~~~~~
 
 .. code-block:: html+django
 
     {% querystring color=None %}
 
-If the given parameter is a list, the value will remain as a list. For example,
-if ``my_list`` is set to ``["red", "blue"]``, the following would result in
-``?color=red&color=blue``:
+Passing ``None`` as the value removes the parameter from the query string. For
+example, if the current query string is ``?color=green&size=M``, the output
+will be ``?size=M``.
+
+Handling lists
+~~~~~~~~~~~~~~
 
 .. code-block:: html+django
 
     {% querystring color=my_list %}
 
+If ``my_list`` is ``["red", "blue"]``, the output will be
+``?color=red&color=blue``, preserving the list structure in the query string.
+Please note that if the current query string already defines the ``color``
+parameter, this will overwrite it with the given values.
+
+Dynamic usage
+~~~~~~~~~~~~~
+
 A common example of using this tag is to preserve the current query string when
 displaying a page of results, while adding a link to the next and previous
-pages of results. For example, if the paginator is currently on page 3, and
-the current query string is ``?color=blue&size=M&page=3``, the following code
-would output ``?color=blue&size=M&page=4``:
+pages. For example, if the paginator is currently on page 3, and the current
+query string is ``?color=blue&size=M&page=3``, the following code would output
+``?color=blue&size=M&page=4``:
 
 .. code-block:: html+django
 
     {% querystring page=page.next_page_number %}
 
-You can also store the value in a variable, for example, if you need multiple
-links to the same page with syntax such as:
+You can also store the value in a variable. For example, if you need multiple
+links to the same page, define it as:
 
 .. code-block:: html+django