Revamp text-formatting page, add info about the new styles

docs/source/topics/text-formatting.rst

@@ -1,40 +1,99 @@
 Text Formatting
 ===============
 
-Pyrogram, just like the `Telegram Bot API`_, natively supports basic Markdown and HTML formatting styles for text
+.. role:: strike
-messages and media captions.
+    :class: strike
 
-Markdown style uses the same syntax as Telegram Desktop's and is enabled by default.
+.. role:: underline
+    :class: underline
 
-Beside bold, italic, and pre-formatted code, **Pyrogram does also support inline URLs and inline mentions of users**.
+.. role:: bold-underline
+    :class: bold-underline
+
+.. role:: strike-italic
+    :class: strike-italic
+
+Pyrogram uses a custom Markdown dialect for text formatting which adds some unique features that make writing styled
+texts easier in both Markdown and HTML. You can send sophisticated text messages and media captions using a great
+variety of decorations that can also be nested in order to combine multiple styles together.
+
+Basic Styles
+------------
+
+When formatting your messages, you can choose between Markdown-style, HTML-style or both (default). The following is a
+list of the basic styles currently supported by Pyrogram.
+
+- **bold**
+- *italic*
+- :strike:`strike`
+- :underline:`underline`
+- `text URL <https://pyrogram.org>`_
+- `user text mention <https://t.me/haskell>`_
+- ``inline fixed-width code``
+- .. code-block:: text
+
+    pre-formatted
+      fixed-width
+        code block
+
+.. note::
+
+    User text mentions are only guaranteed to work if you have already met the user (in groups or private chats).
 
 Markdown Style
 --------------
 
-To use this mode, pass "markdown" in the *parse_mode* field when using
+To strictly use this mode, pass "markdown" to the *parse_mode* parameter when using
 :meth:`~pyrogram.Client.send_message`. Use the following syntax in your message:
 
 .. code-block:: text
 
-    **bold text**
+    **bold**
 
-    __italic text__
+    __italic__
 
-    [inline URL](https://docs.pyrogram.org/)
+    --underline--
 
-    [inline mention of a user](tg://user?id=23122162)
+    ~~strike~~
+
+    [text URL](https://docs.pyrogram.org/)
+
+    [text user mention](tg://user?id=23122162)
 
     `inline fixed-width code`
 
-    ```block_language
+    ```
-    pre-formatted fixed-width code block
+    pre-formatted
+      fixed-width
+        code block
     ```
 
+**Example**:
+
+.. code-block:: python
+
+    app.send_message(
+        "haskell",
+        (
+            "**bold**, "
+            "__italic__, "
+            "--underline--, "
+            "~~strikethrough~~, "
+            "[mention](tg://user?id=23122162), "
+            "[URL](https://pyrogram.org), "
+            "`code`, "
+            "```"
+            "for i in range(10):\n"
+            "    print(i)"
+            "```"
+        ),
+        parse_mode="markdown"
+    )
 
 HTML Style
 ----------
 
-To use this mode, pass "html" in the *parse_mode* field when using :meth:`~pyrogram.Client.send_message`.
+To strictly use this mode, pass "html" to the *parse_mode* parameter when using :meth:`~pyrogram.Client.send_message`.
 The following tags are currently supported:
 
 .. code-block:: text
@@ -43,49 +102,36 @@ The following tags are currently supported:
 
     <i>italic</i>, <em>italic</em>
 
-    <a href="http://docs.pyrogram.org/">inline URL</a>
+    <u>underline</u>
 
-    <a href="tg://user?id=23122162">inline mention of a user</a>
+    <s>strike</s>, <del>strike</del>, <strike>strike</strike>
+
+    <a href="http://docs.pyrogram.org/">text URL</a>
+
+    <a href="tg://user?id=23122162">inline mention</a>
 
     <code>inline fixed-width code</code>
 
-    <pre>pre-formatted fixed-width code block</pre>
+    <pre>
+    pre-formatted
+      fixed-width
+        code block
+    </pre>
 
-.. note:: Mentions are only guaranteed to work if you have already met the user (in groups or private chats).
+**Example**:
 
-Examples
+.. code-block:: python
---------
-
--   Markdown:
-
-    .. code-block:: python
 
     app.send_message(
-            chat_id="haskell",
+        "haskell",
-            text=(
+        (
-                "**bold**, "
-                "__italic__, "
-                "[mention](tg://user?id=23122162), "
-                "[URL](https://docs.pyrogram.org), "
-                "`code`, "
-                "```"
-                "for i in range(10):\n"
-                "   print(i)```"
-            )
-        )
-
--   HTML:
-
-    .. code-block:: python
-
-        app.send_message(
-            chat_id="haskell",
-            text=(
             "<b>bold</b>, "
             "<i>italic</i>, "
+            "<u>underline</u>, "
+            "<s>strikethrough</s>, "
             "<a href=\"tg://user?id=23122162\">mention</a>, "
             "<a href=\"https://pyrogram.org/\">URL</a>, "
-                "<code>code</code>, "
+            "<code>code</code>\n\n"
             "<pre>"
             "for i in range(10):\n"
             "    print(i)"
@@ -94,4 +140,86 @@ Examples
         parse_mode="html"
     )
 
-.. _Telegram Bot API: https://core.telegram.org/bots/api#formatting-options
+.. note::
+
+    All ``<``, ``>`` and ``&`` symbols that are not a part of a tag or an HTML entity must be replaced with the
+    corresponding HTML entities (``<`` with ``&lt;``, ``>`` with ``&gt;`` and ``&`` with ``&amp;``). You can use this
+    snippet to quickly escape those characters:
+
+    .. code-block:: python
+
+        import html
+
+        text = "<my text>"
+        text = html.escape(text)
+
+        print(text)
+
+    .. code-block:: text
+
+        &lt;my text&gt;
+
+Different Styles
+----------------
+
+By default, when ignoring the *parse_mode* parameter, both Markdown and HTML styles are enabled together.
+This means you can combine together both syntaxes in the same text:
+
+.. code-block:: python
+
+    app.send_message("haskell", "**bold**, <i>italic</i>")
+
+Result:
+
+    **bold**, *italic*
+
+If you don't like this behaviour you can always choose to only enable either Markdown or HTML in strict mode by passing
+"markdown" or "html" as argument to the *parse_mode* parameter.
+
+.. code-block::
+
+    app.send_message("haskell", "**bold**, <i>italic</i>", parse_mode="markdown")
+    app.send_message("haskell", "**bold**, <i>italic</i>", parse_mode="html")
+
+Result:
+
+    **bold**, <i>italic</i>
+
+    \*\*bold**, *italic*
+
+In case you want to completely turn off the style parser, simply pass ``None`` to *parse_mode*. The text will be sent
+as-is.
+
+.. code-block:: python
+
+    app.send_message("haskell", "**bold**, <i>italic</i>", parse_mode=None)
+
+Result:
+
+    \*\*bold**, <i>italic</i>
+
+Nested and Overlapping Entities
+-------------------------------
+
+You can also style texts with more than one decoration at once by nesting entities together. For example, you can send
+a text message with both :bold-underline:`bold and underline` styles, or a text that has both :italic-strike:`italic and
+strike` styles, and you can still combine both Markdown and HTML together.
+
+Here there are some example texts you can try sending:
+
+**Markdown**:
+
+- ``**bold, --underline--**``
+- ``**bold __italic --underline ~~striked~~--__**``
+- ``**bold __and** italic__``
+
+**HTML**:
+
+- ``<b>bold, <u>underline</u></b>``
+- ``<b>bold <i>italic <u>underline <s>striked</s></u></i></b>``
+- ``<b>bold <i>and</b> italic</i>``
+
+**Combined**:
+
+- ``--you can combine <i>HTML</i> with **Markdown**--``
+- ``**and also <i>overlap** --entities</i> this way--``