From ce0f5c3beb1ecbdb9c43622012b07c0b9754555d Mon Sep 17 00:00:00 2001
From: Ihor Radchenko <yantar92@gmail.com>
Date: Fri, 19 Nov 2021 19:27:56 +0800
Subject: [PATCH] org-manual.org: Clarify how to handle markup ambiguity

* doc/org-manual.org (Emphasis and Monospace): Advice users to insert
zero width space to force Org ignore emphasis markers.
---
 doc/org-manual.org | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 3772c6bbe..ad1a06a24 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -10811,6 +10811,18 @@ To turn off fontification for marked up text, you can set
 ~org-fontify-emphasized-text~ to ~nil~.  To narrow down the list of
 available markup syntax, you can customize ~org-emphasis-alist~.
 
+Sometimes, when marked text also contains the marker character itself,
+the result may be unsettling.  For example,
+
+#+begin_example
+/One may expect this whole sentence to be italicized, but the
+following ~user/?variable~ contains =/= character, which effectively
+stops emphasis there./
+#+end_example
+
+You can use zero width space to help Org sorting out the ambiguity.
+See [[*Escape Character]] for more details.
+
 ** Subscripts and Superscripts
 :PROPERTIES:
 :DESCRIPTION: Simple syntax for raising/lowering text.