From fb4f19eb5eb7afe828af84f81e72dfb96dbe43e6 Mon Sep 17 00:00:00 2001
From: Javier Eguiluz <javier.eguiluz@gmail.com>
Date: Mon, 14 Jan 2019 17:48:14 +0100
Subject: [PATCH] Minor rewords in the CSRF docs

---
 reference/twig_reference.rst |  8 +++++---
 security/csrf.rst            | 20 +++++++++++++-------
 2 files changed, 18 insertions(+), 10 deletions(-)

diff --git a/reference/twig_reference.rst b/reference/twig_reference.rst
index 2998741adc5..753106bd37c 100644
--- a/reference/twig_reference.rst
+++ b/reference/twig_reference.rst
@@ -277,6 +277,8 @@ form_rest
 Renders all fields that have not yet been rendered, more information in
 :ref:`the Twig Form reference <reference-forms-twig-rest>`.
 
+.. _reference-twig-function-csrf-token:
+
 csrf_token
 ~~~~~~~~~~
 
@@ -285,10 +287,10 @@ csrf_token
     {{ csrf_token(intention) }}
 
 ``intention``
-    **type**: ``string``
+    **type**: ``string`` - an arbitrary string used to generate the token value.
 
-Renders a CSRF token. Use this function if you want CSRF protection without
-creating a form.
+Renders a CSRF token. Use this function if you want :doc:`CSRF protection </security/csrf>`
+in a regular HTML form not managed by the Symfony Form component.
 
 is_granted
 ~~~~~~~~~~
diff --git a/security/csrf.rst b/security/csrf.rst
index 80f1f6c9d6b..3c6d7f230df 100644
--- a/security/csrf.rst
+++ b/security/csrf.rst
@@ -109,22 +109,28 @@ CSRF Protection in Login Forms
 See :doc:`/security/form_login_setup` for a login form that is protected from
 CSRF attacks.
 
-CSRF Protection in HTML Forms
------------------------------
+.. _csrf-protection-in-html-forms:
+
+Generating and Checking CSRF Tokens Manually
+--------------------------------------------
 
 .. versionadded:: 4.1
+
     In Symfony versions prior to 4.1, CSRF support required installing the
     Symfony Form component even if you didn't use it.
 
-It's also possible to add CSRF protection to regular HTML forms not managed by
-the Symfony Form component, for example the simple forms used to delete items.
-First, use the ``csrf_token()`` function in the Twig template to generate a CSRF
-token and store it as a hidden field of the form:
+Although Symfony Forms provide automatic CSRF protection by default, you may
+need to generate and check CSRF tokens manually for example when using regular
+HTML forms not managed by the Symfony Form component.
+
+Consider a simple HTML form created to allow deleting items. First, use the
+:ref:`csrf_token() Twig function <reference-twig-function-csrf-token>` to
+generate a CSRF token in the template and store it as a hidden form field:
 
 .. code-block:: twig
 
     <form action="{{ url('admin_post_delete', { id: post.id }) }}" method="post">
-        {# the argument of csrf_token() is an arbitrary value used to generate the token #}
+        {# the argument of csrf_token() is an arbitrary string used to generate the token #}
         <input type="hidden" name="token" value="{{ csrf_token('delete-item') }}" />
 
         <button type="submit">Delete item</button>