From 3d3ea9016f339b3753fc7e4c909d6a522a0b7a75 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gr=C3=A9goire=20Locqueville?=
 <glocq@users.noreply.github.com>
Date: Wed, 7 Jun 2023 14:22:43 +0200
Subject: [PATCH] Clarify markup details in the documentation (#1434)

---
 library/src/layout/enum.rs  | 5 +++++
 library/src/layout/list.rs  | 5 +++++
 library/src/layout/terms.rs | 5 +++++
 library/src/text/raw.rs     | 3 +++
 4 files changed, 18 insertions(+)

diff --git a/library/src/layout/enum.rs b/library/src/layout/enum.rs
index 62f4c351e..2204b284b 100644
--- a/library/src/layout/enum.rs
+++ b/library/src/layout/enum.rs
@@ -72,6 +72,11 @@ pub struct EnumElem {
     /// [leading]($func/par.leading) instead. This makes the enumeration more
     /// compact, which can look better if the items are short.
     ///
+    /// In markup mode, the value of this parameter is determined based on
+    /// whether items are separated with a blank line. If items directly follow
+    /// each other, this is set to `{true}`; if items are separated by a blank
+    /// line, this is set to `{false}`.
+    ///
     /// ```example
     /// + If an enum has a lot of text, and
     ///   maybe other inline content, it
diff --git a/library/src/layout/list.rs b/library/src/layout/list.rs
index b308c2ce8..a11b019f2 100644
--- a/library/src/layout/list.rs
+++ b/library/src/layout/list.rs
@@ -47,6 +47,11 @@ pub struct ListElem {
     /// [leading]($func/par.leading) instead. This makes the list more compact,
     /// which can look better if the items are short.
     ///
+    /// In markup mode, the value of this parameter is determined based on
+    /// whether items are separated with a blank line. If items directly follow
+    /// each other, this is set to `{true}`; if items are separated by a blank
+    /// line, this is set to `{false}`.
+    ///
     /// ```example
     /// - If a list has a lot of text, and
     ///   maybe other inline content, it
diff --git a/library/src/layout/terms.rs b/library/src/layout/terms.rs
index 0cfe98d97..8b8a72233 100644
--- a/library/src/layout/terms.rs
+++ b/library/src/layout/terms.rs
@@ -32,6 +32,11 @@ pub struct TermsElem {
     /// [leading]($func/par.leading) instead. This makes the term list more
     /// compact, which can look better if the items are short.
     ///
+    /// In markup mode, the value of this parameter is determined based on
+    /// whether items are separated with a blank line. If items directly follow
+    /// each other, this is set to `{true}`; if items are separated by a blank
+    /// line, this is set to `{false}`.
+    ///
     /// ```example
     /// / Fact: If a term list has a lot
     ///   of text, and maybe other inline
diff --git a/library/src/text/raw.rs b/library/src/text/raw.rs
index 75e8ddc74..01766e399 100644
--- a/library/src/text/raw.rs
+++ b/library/src/text/raw.rs
@@ -63,6 +63,9 @@ pub struct RawElem {
 
     /// Whether the raw text is displayed as a separate block.
     ///
+    /// In markup mode, using one-backtick notation makes this `{false}`,
+    /// whereas using three-backtick notation makes it `{true}`.
+    ///
     /// ````example
     /// // Display inline code in a small box
     /// // that retains the correct baseline.