From ea424f1da649a5c1bb54d7e51953fece239a31bf Mon Sep 17 00:00:00 2001
From: Mohammad Nejati <ashtumashtum@gmail.com>
Date: Wed, 10 Jan 2024 14:54:39 +0000
Subject: [PATCH] Fix the issue of paragraph separation in the documentation

Fixes #2792
---
 doc/xsl/custom-overrides.xsl             |  2 ++
 include/boost/beast/http/read.hpp        | 28 ++++++++-----------
 include/boost/beast/http/write.hpp       | 35 ++++++++++--------------
 include/boost/beast/websocket/stream.hpp | 18 +++++++++++-
 4 files changed, 46 insertions(+), 37 deletions(-)

diff --git a/doc/xsl/custom-overrides.xsl b/doc/xsl/custom-overrides.xsl
index f9c6d78d..65ffeb20 100644
--- a/doc/xsl/custom-overrides.xsl
+++ b/doc/xsl/custom-overrides.xsl
@@ -15,6 +15,8 @@
   <xsl:template mode="convenience-header" match="@file[contains(., 'boost/beast/zlib')]"     >zlib.hpp</xsl:template>
   <xsl:template mode="convenience-header" match="@file"/>
 
+  <xsl:template mode="before" match="para">{$nl}{$nl}</xsl:template>
+
   <xsl:variable name="emphasized-template-parameter-types" select="
     'Allocator',
     'AsyncStream',
diff --git a/include/boost/beast/http/read.hpp b/include/boost/beast/http/read.hpp
index ffe0793c..bbd85a5d 100644
--- a/include/boost/beast/http/read.hpp
+++ b/include/boost/beast/http/read.hpp
@@ -209,10 +209,9 @@ read_some(
 
     @li @c net::cancellation_type::terminal
 
-    if the `stream` also supports terminal cancellation.
-
-    `terminal` cancellation leaves the stream in an undefined state,
-    so that only closing it is guaranteed to succeed.
+    if the `stream` also supports terminal cancellation, `terminal`
+    cancellation leaves the stream in an undefined state, so that only
+    closing it is guaranteed to succeed.
 
 */
 template<
@@ -420,10 +419,9 @@ read_header(
 
     @li @c net::cancellation_type::terminal
 
-    if the `stream` also supports terminal cancellation.
-
-    `terminal` cancellation leaves the stream in an undefined state,
-    so that only closing it is guaranteed to succeed.
+    if the `stream` also supports terminal cancellation, `terminal`
+    cancellation leaves the stream in an undefined state, so that only
+    closing it is guaranteed to succeed.
 
 */
 template<
@@ -631,10 +629,9 @@ read(
 
     @li @c net::cancellation_type::terminal
 
-    if the `stream` also supports terminal cancellation.
-
-    `terminal` cancellation leaves the stream in an undefined state,
-    so that only closing it is guaranteed to succeed.
+    if the `stream` also supports terminal cancellation, `terminal`
+    cancellation leaves the stream in an undefined state, so that only
+    closing it is guaranteed to succeed.
 
 */
 template<
@@ -851,10 +848,9 @@ read(
 
     @li @c net::cancellation_type::terminal
 
-    if the `stream` also supports terminal cancellation.
-
-    `terminal` cancellation leaves the stream in an undefined state,
-    so that only closing it is guaranteed to succeed.
+    if the `stream` also supports terminal cancellation, `terminal`
+    cancellation leaves the stream in an undefined state, so that only
+    closing it is guaranteed to succeed.
 
 */
 template<
diff --git a/include/boost/beast/http/write.hpp b/include/boost/beast/http/write.hpp
index 92050d27..fd82a667 100644
--- a/include/boost/beast/http/write.hpp
+++ b/include/boost/beast/http/write.hpp
@@ -169,10 +169,9 @@ write_some(
 
     @li @c net::cancellation_type::terminal
 
-    if the `stream` also supports terminal cancellation.
-
-    `terminal` cancellation leaves the stream in an undefined state,
-    so that only closing it is guaranteed to succeed.
+    if the `stream` also supports terminal cancellation, `terminal`
+    cancellation leaves the stream in an undefined state, so that only
+    closing it is guaranteed to succeed.
 
     @see serializer
 */
@@ -312,10 +311,9 @@ write_header(
 
     @li @c net::cancellation_type::terminal
 
-    if the `stream` also supports terminal cancellation.
-
-    `terminal` cancellation leaves the stream in an undefined state,
-    so that only closing it is guaranteed to succeed.
+    if the `stream` also supports terminal cancellation, `terminal`
+    cancellation leaves the stream in an undefined state, so that only
+    closing it is guaranteed to succeed.
 
     @see serializer
 */
@@ -446,10 +444,9 @@ write(
 
     @li @c net::cancellation_type::terminal
 
-    if the `stream` also supports terminal cancellation.
-
-    `terminal` cancellation leaves the stream in an undefined state,
-    so that only closing it is guaranteed to succeed.
+    if the `stream` also supports terminal cancellation, `terminal`
+    cancellation leaves the stream in an undefined state, so that only
+    closing it is guaranteed to succeed.
 
     @see serializer
 */
@@ -684,10 +681,9 @@ write(
 
     @li @c net::cancellation_type::terminal
 
-    if the `stream` also supports terminal cancellation.
-
-    `terminal` cancellation leaves the stream in an undefined state,
-    so that only closing it is guaranteed to succeed.
+    if the `stream` also supports terminal cancellation, `terminal`
+    cancellation leaves the stream in an undefined state, so that only
+    closing it is guaranteed to succeed.
 
     @see message
 */
@@ -759,10 +755,9 @@ async_write(
 
     @li @c net::cancellation_type::terminal
 
-    if the `stream` also supports terminal cancellation.
-
-    `terminal` cancellation leaves the stream in an undefined state,
-    so that only closing it is guaranteed to succeed.
+    if the `stream` also supports terminal cancellation, `terminal`
+    cancellation leaves the stream in an undefined state, so that only
+    closing it is guaranteed to succeed.
 
     @see message
 */
diff --git a/include/boost/beast/websocket/stream.hpp b/include/boost/beast/websocket/stream.hpp
index 0595851f..8dec12b1 100644
--- a/include/boost/beast/websocket/stream.hpp
+++ b/include/boost/beast/websocket/stream.hpp
@@ -1639,7 +1639,8 @@ public:
         by dispatching to the immediate executor. If no
         immediate executor is specified, this is equivalent
         to using `net::post`.
-         @par Per-Operation Cancellation
+
+        @par Per-Operation Cancellation
 
         This asynchronous operation supports cancellation for the following
         net::cancellation_type values:
@@ -1649,6 +1650,7 @@ public:
 
         `total` cancellation succeeds if the operation is suspended due to ongoing
         control operations such as a ping/pong.
+
         `terminal` cancellation succeeds when supported by the underlying stream.
 
         @note `terminal` cancellation will may close the underlying socket.
@@ -1760,6 +1762,7 @@ public:
         by dispatching to the immediate executor. If no
         immediate executor is specified, this is equivalent
         to using `net::post`.
+
         @par Per-Operation Cancellation
 
         This asynchronous operation supports cancellation for the following
@@ -1770,6 +1773,7 @@ public:
 
         `total` cancellation succeeds if the operation is suspended due to ongoing
         control operations such as a ping/pong.
+
         `terminal` cancellation succeeds when supported by the underlying stream.
 
         `terminal` cancellation leaves the stream in an undefined state,
@@ -1885,6 +1889,7 @@ public:
         by dispatching to the immediate executor. If no
         immediate executor is specified, this is equivalent
         to using `net::post`.
+
         @par Per-Operation Cancellation
 
         This asynchronous operation supports cancellation for the following
@@ -1895,6 +1900,7 @@ public:
 
         `total` cancellation succeeds if the operation is suspended due to ongoing
         control operations such as a ping/pong.
+
         `terminal` cancellation succeeds when supported by the underlying stream.
 
         `terminal` cancellation leaves the stream in an undefined state,
@@ -2063,6 +2069,7 @@ public:
         by dispatching to the immediate executor. If no
         immediate executor is specified, this is equivalent
         to using `net::post`.
+
         @par Per-Operation Cancellation
 
         This asynchronous operation supports cancellation for the following
@@ -2073,6 +2080,7 @@ public:
 
         `total` cancellation succeeds if the operation is suspended due to ongoing
         control operations such as a ping/pong.
+
         `terminal` cancellation succeeds when supported by the underlying stream.
 
         `terminal` cancellation leaves the stream in an undefined state,
@@ -2259,6 +2267,7 @@ public:
         by dispatching to the immediate executor. If no
         immediate executor is specified, this is equivalent
         to using `net::post`.
+
         @par Per-Operation Cancellation
 
         This asynchronous operation supports cancellation for the following
@@ -2269,6 +2278,7 @@ public:
 
         `total` cancellation succeeds if the operation is suspended due to ongoing
         control operations such as a ping/pong.
+
         `terminal` cancellation succeeds when supported by the underlying stream.
 
         `terminal` cancellation leaves the stream in an undefined state,
@@ -2388,6 +2398,7 @@ public:
 
         `total` cancellation succeeds if the operation is suspended due to ongoing
         control operations such as a ping/pong.
+
         `terminal` cancellation succeeds when supported by the underlying stream.
 
         `terminal` cancellation leaves the stream in an undefined state,
@@ -2477,6 +2488,7 @@ public:
 
         `total` cancellation succeeds if the operation is suspended due to ongoing
         control operations such as a ping/pong.
+
         `terminal` cancellation succeeds when supported by the underlying stream.
 
         `terminal` cancellation leaves the stream in an undefined state,
@@ -2607,6 +2619,7 @@ public:
         by dispatching to the immediate executor. If no
         immediate executor is specified, this is equivalent
         to using `net::post`.
+
         @par Per-Operation Cancellation
 
         This asynchronous operation supports cancellation for the following
@@ -2617,6 +2630,7 @@ public:
 
         `total` cancellation succeeds if the operation is suspended due to ongoing
         control operations such as a ping/pong.
+
         `terminal` cancellation succeeds when supported by the underlying stream.
 
         `terminal` cancellation leaves the stream in an undefined state,
@@ -2756,6 +2770,7 @@ public:
         by dispatching to the immediate executor. If no
         immediate executor is specified, this is equivalent
         to using `net::post`.
+
         @par Per-Operation Cancellation
 
         This asynchronous operation supports cancellation for the following
@@ -2766,6 +2781,7 @@ public:
 
         `total` cancellation succeeds if the operation is suspended due to ongoing
         control operations such as a ping/pong.
+
         `terminal` cancellation succeeds when supported by the underlying stream.
 
         `terminal` cancellation leaves the stream in an undefined state,