.. _special:

Special tags
============

All tags may be introduced using the ``:tag-name: <contents> ::`` notation.  However,
some tags admit an alternative notation.


Shorthand
*********

Some tags allow for *shorthand* notation.  Shorthand notation does not need tag names or
Halmoses to modify the contained text, it uses different delimiters instead.  For
example, the following are two different ways for introducing bold text, one using the
standard ``:span:`` tag and another using shorthand notation and asterisks ``*``.

.. rsm::

   :manuscript:
   This text is :span: {:strong:} bold ::, as
   is *this one*.
   ::

Similarly, italic text also has a shorthand version using slashes ``/``.

.. rsm::

   :manuscript:
   This text is :span: {:emphas:} italic ::, as
   is /this one/.
   ::

Math tags allow shorthand notation using one dollar sign ``$`` for inline and two ``$$``
for blocks.

.. rsm::

   :manuscript:

   *Inline math.*

   Either :math:2 + 2 = 4:: or
   $2 + 2 = 4$.

   ::

.. rsm::

   :manuscript:

   *Math block.*

   Either

   :mathblock:
   2 + 2 = 4
   ::

   or

   $$
   2 + 2 = 4.
   $$

   ::


Code allows shorthand notation using one backtick ````` for inline or three ``````` for blocks.


.. rsm::

   :manuscript:

   *Inline code.*

   Either :code:var = "value":: or
   `var = "value"`.

   ::

.. rsm::

   :manuscript:

   *Code block.*

   Either

   :codeblock:
   var = "value"
   ::

   or

   ```
   2 + 2 = 4.
   ```

   ::


.. grid:: 1 1 1 2

   .. grid-item::

      .. tip::

         Either standard or shorthand notation allow meta tags.  For example, to assign a
         label to an inline math region, you may use either ``:math:{:label:some-lbl} 2+2=4
         ::`` or ``${:label:some-lbl} 2+2=4 $``.

   .. grid-item::

      .. tip::

         The standard notation using colons and Halmos as delimiters is easy to parse by
         automated tools.  The shorthand notation is easy to read by humans.


Stamps
******

Some tags deviate from the standard ``:tag-name: <contents> ::`` syntax in that they do
not allow contents nor need a closing Halmos.  These are called *stamp* tags.  One
example is the ``:appendix:`` tag, whose role is to mark the place in the manuscript
where the Appendix starts.

.. rsm::

   :manuscript:

   # First section
   ::

   # Second section
   ::

   :appendix:

   # First appendix
   ::

   ::

Among other things, the ``:appendix:`` stamp restarts the numbering of the following
sections and changes it from arabic to roman numerals.