.. _doc-editing:


Editing the Manual
==================

The manual is written in the `reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`__ (RST) markup language and can be edited using a plain text editor. For a local preview, you convert (build) the manual source files from RST into HTML web pages.


Markup Style Guide
------------------

Headings
^^^^^^^^

.. code-block:: rst

    #################
    Document Part
    #################

    ****************
    Document Chapter
    ****************

    Document Section
    ================

    Document Subsection
    -------------------

    Document Subsubsection
    ^^^^^^^^^^^^^^^^^^^^^^

    Document Paragraph
    """"""""""""""""""

.. note::

    Parts should only be used for contents or index pages.

|

Interface Elements
^^^^^^^^^^^^^^^^^^

Keyboard & Mouse Shourtcuts
"""""""""""""""""""""""""""
``:kbd:`LMB``` - :kbd:`LMB` or ``:kbd:`Ctrl+S``` - :kbd:`Ctrl+S`

Menus
"""""
``:menuselection:`File --> Save As...``` - :menuselection:`File --> Save As...`


|

Code Samples
^^^^^^^^^^^^

There is support for syntax highlighting if the programming language is provided,
and line numbers can be optionally shown with the ``:linenos:`` option

::

   .. code-block:: python
      :linenos:

      page = 1
      pagenum = scribus.pageCount()
      content = []
      while (page <= pagenum):
          scribus.gotoPage(page)
          ...

|

Cross References and Linkage
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You can link to another document in the manual with

::

   :doc:`The Title </section/path/to/file>`

To link to a specific section in another document (or the same one), explicit labels are available

::

   .. _sample-label:

   [section or image to reference]

   Some text :ref:`Optional Title <sample-label>`

Linking to a title in the same file

::

   Titles are Targets
   ==================

   Body text.

   Implicit references, like `Titles are Targets`_

Linking to the outside world

::

   `Scribus Website <https://www.scribus.net>`__