Update documentation

docs/source/usage/advanced_formatting.rst

@@ -56,6 +56,20 @@ activated by clicking the left-most icon button in the editor header.
 .. versionadded:: 2.2
 
 
+.. _docs_usage_formatting_shortcodes_break:
+
+Forced Line Break
+-----------------
+
+Inserting ``[br]`` in the text will ensure a line break is always inserted in that place, even if
+you turn off **Preserve Hard Line breaks** in your **Manuscript Build Settings**.
+
+You can add a manual line break after it too, for a better visual representation in the editor, but
+keep in mind that this line break is removed before the text is processed, so the text on either
+side will be considered as belonging to the same line. This can affect how alignment is treated.
+See :ref:`docs_usage_align_indent_forced` for more details.
+
+
 .. _docs_usage_formatting_breaks:
 
 Vertical Space and Page Breaks

docs/source/usage/alignment_and_indent.rst

@@ -53,18 +53,33 @@ the entire paragraph. For the following text, all lines will be centred:
 
 .. code-block:: md
 
-   >> I am the very model of a modern Major-General
+   >> I am the very model of a modern Major-General <<
    I've information vegetable, animal, and mineral
    I know the kings of England, and I quote the fights historical
-   From Marathon to Waterloo, in order categorical <<
+   From Marathon to Waterloo, in order categorical
+
+If you have multiple conflicting alignments on a paragraph, only one is applied. The order of
+precedence is:
+
+#. Left alignment
+#. Right alignment
+#. Centred text
+#. Justified text
+
+.. note::
+
+   It is strongly recommended that you keep the **Preserve Hard Line Breaks** setting enabled in
+   your **Manuscript Build Settings**. This setting assumes all single line breaks in your text are
+   intended. Turning this off makes adding line breaks much more complicated, but it is still
+   possible. See :ref:`docs_usage_align_indent_forced`.
 
 
 Alignment with First Line Indent
 ================================
 
 If you have first line indent enabled in your manuscript build settings, you probably want to
-disable it for text in verses. Adding any alignment tags will cause the first line indent to be
+disable it for text in verses. Adding any alignment tags on a paragraph will cause the first
-switched off for that paragraph.
+line indent to be switched off for that paragraph.
 
 :bdg-info:`Example`
 
@@ -76,3 +91,35 @@ The following text will always be aligned against the left margin:
    I've information vegetable, animal, and mineral
    I know the kings of England, and I quote the fights historical
    From Marathon to Waterloo, in order categorical
+
+
+.. _docs_usage_align_indent_forced:
+
+Alignment with Forced Line Breaks
+=================================
+
+If you turn off **Preserve Hard Line Breaks** in **Manuscript Build Settings**, you can still force
+line breaks in paragraphs using the ``[br]`` shortcode. For clarity in the text, you can add a line
+break after it as well. It doesn't result in two line breaks.
+
+Keep in mind that when the text is processed, these lines on either side of a ``[br]`` shortcode
+are combined, and a trailing hard line break is *ignored*. This means that when such a paragraph is
+processed, these line breaks count as the same line. This affects hiw alignment tags are handled.
+For instance, this text becomes centred instead of left aligned.
+
+.. code-block:: md
+
+   >> I am the very model of a modern Major-General[br]
+   I've information vegetable, animal, and mineral[br]
+   I know the kings of England, and I quote the fights historical[br]
+   From Marathon to Waterloo, in order categorical <<
+
+Since this is understood as one line, this is the only way you can actually centre this paragraph.
+
+.. caution::
+
+   Due to this difference in how text with ``[br]`` tags are processed, it is generally better to
+   stick with the **Preserve Hard Line Breaks** setting enabled. It ensures a better correspondence
+   between what you see in the editor and what output you get.
+
+See also :ref:`docs_usage_formatting_shortcodes_break`.