From a44c996302077b718a2d3c174c1edf9e06b2fd36 Mon Sep 17 00:00:00 2001 From: Dan <14043624+delivrance@users.noreply.github.com> Date: Thu, 27 Jun 2019 23:15:12 +0200 Subject: [PATCH] Revamp text-formatting page, add info about the new styles --- docs/source/topics/text-formatting.rst | 228 +++++++++++++++++++------ 1 file changed, 178 insertions(+), 50 deletions(-) diff --git a/docs/source/topics/text-formatting.rst b/docs/source/topics/text-formatting.rst index bc74d562..03b50a8e 100644 --- a/docs/source/topics/text-formatting.rst +++ b/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 -messages and media captions. +.. role:: strike + :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 `_ +- `user text mention `_ +- ``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,55 +102,124 @@ The following tags are currently supported: italic, italic - inline URL + underline - inline mention of a user + strike, strike, strike + + text URL + + inline mention inline fixed-width code - 
pre-formatted fixed-width code block
+ 
+    pre-formatted
+      fixed-width
+        code block
+
-.. 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: + app.send_message( + "haskell", + ( + "bold, " + "italic, " + "underline, " + "strikethrough, " + "mention, " + "URL, " + "code\n\n" + "
"
+            "for i in range(10):\n"
+            "    print(i)"
+            "
" + ), + parse_mode="html" + ) + +.. 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 ``<``, ``>`` with ``>`` and ``&`` with ``&``). You can use this + snippet to quickly escape those characters: .. code-block:: python - app.send_message( - chat_id="haskell", - text=( - "**bold**, " - "__italic__, " - "[mention](tg://user?id=23122162), " - "[URL](https://docs.pyrogram.org), " - "`code`, " - "```" - "for i in range(10):\n" - " print(i)```" - ) - ) + import html -- HTML: + text = "" + text = html.escape(text) - .. code-block:: python + print(text) - app.send_message( - chat_id="haskell", - text=( - "bold, " - "italic, " - "mention, " - "URL, " - "code, " - "
"
-                "for i in range(10):\n"
-                "    print(i)"
-                "
" - ), - parse_mode="html" - ) + .. code-block:: text -.. _Telegram Bot API: https://core.telegram.org/bots/api#formatting-options \ No newline at end of file + <my text> + +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**, italic") + +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**, italic", parse_mode="markdown") + app.send_message("haskell", "**bold**, italic", parse_mode="html") + +Result: + + **bold**, italic + + \*\*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**, italic", parse_mode=None) + +Result: + + \*\*bold**, italic + +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**: + +- ``bold, underline`` +- ``bold italic underline striked`` +- ``bold and italic`` + +**Combined**: + +- ``--you can combine HTML with **Markdown**--`` +- ``**and also overlap** --entities this way--``