diff --git a/docs/source/usage/advanced_formatting.rst b/docs/source/usage/advanced_formatting.rst index 557db1a7..94bfec0f 100644 --- a/docs/source/usage/advanced_formatting.rst +++ b/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 diff --git a/docs/source/usage/alignment_and_indent.rst b/docs/source/usage/alignment_and_indent.rst index 2494ea32..dea1b171 100644 --- a/docs/source/usage/alignment_and_indent.rst +++ b/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 -switched off for that paragraph. +disable it for text in verses. Adding any alignment tags on a paragraph will cause the first +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`.