.. /*  
    * This file is part of the SavaPage project <https://www.savapage.org>.
    * Copyright (c) 2026 Datraverse B.V.
    * Author: Rijk Ravestein.
    *
    * SPDX-FileCopyrightText: (c) 2020 Datraverse B.V. <info@datraverse.com>
    * SPDX-License-Identifier: CC-BY-SA-4.0
    *
    * For more information, please contact Datraverse B.V. at this
    * address: info@datraverse.com
    */

.. _preface-conventions:

Conventions used in this Document
---------------------------------

.. contents::
   :depth: 2
   :local:

.. _preface-conventions-typo:

Typographical Conventions
~~~~~~~~~~~~~~~~~~~~~~~~~

This is a list with examples of the typographical conventions used in
this manual.


.. list-table:: Typographical conventions
   :widths: 30 70
   :header-rows: 1
   
   * - Convention
     - Example
   * - Executable program with options 
     - | Enter ``ls --reverse`` to get a directory listing in reverse order.
   * - A character or string indicating 
       the start of an input field.
     - Enter your name after the |RST_GUILABEL_USER_NAME| prompt.
   * - User input.
     - | John entered **john** as his login name.
   * - A button.
     - | Press the |RST_BUTTON_CANCEL| button.
   * - A text prompt.
     - | Enter your full name after the **Name** prompt
   * - Content that may or must be
       replaced by the user.
     - | Please enter ``filename`` to save the content to.
   * - Filename.
     - | Please open the file ``server.properties`` in your favorite editor.
   * - Directory.
     - | ``/opt/savapage``
   * - A question-and-answer set.
     - | **Q**: To be, or not to be?
       | **A**: That is the question.
   * - Key on a keyboard.
     - | Press :bdg-dark:`F1` for help.
   * - A combination of keys.
     - | Press :bdg-dark:`Ctrl+C` to abort the program.
   * - | A selection or series of
       | selections from a menu.     
     - | Select Print → Settings to open the dialog.
   * - An inline code fragment.
     - | ``Text in this format`` is used to show code examples, the
       | contents of files, and console output, as well as the names 
       | of variables, commands, and other code excerpts in the text.
   * - Code (listing).
     - .. callout::

           .. code-block:: text
              :caption: Example code

               Line A:
               Line B:    # <1>
               Line C:    # <2>

           .. annotations::
               :1: Comment for Line B.
               :2: Comment for Line C.
   * - Link (external).
     - | A link to an URI is formatted like this:
       | `https://savapage.org <https://www.savapage.org>`__ and `support@savapage.org <mailto:support@savapage.org>`__
       | ... or as an alternative: visit our `website <https://savapage.org>`__ or write an `email <mailto:support@savapage.org>`__.
   * - Link (internal).
     - | See :ref:`Server Installation <ch-install>` of this manual.
   * - Name of a variable.
     - | In Perl, ``@ARGV`` contains the command line parameters used 
       | when the script was run.
   * - | Inline text that holds
       | some literal value.     
     - | When ``debug`` is activated more detailed logging is produced.


.. _preface-conventions-feature-preview:

Feature Preview
~~~~~~~~~~~~~~~

.. figure:: ../images/manual/savapage-feature-preview-75x100.png
   :width: 50px

The icon above marks a section where a “feature preview” is discussed.
This feature is operational yet impermanent, and available for preview
to provoke feedback based on real world use. This may lead to it
becoming permanent in a future release.

.. _preface-conventions-notes:

Notes
~~~~~

You should pay special attention to notes set apart from the text with
the following icons:

.. important::

   Important notes are marked like this.

.. note::

   Notes provide extra background information.

.. tip::

   Tips provide useful advice to make your life easier.

.. caution::

   Indicate situations where you have to be careful what you are doing.

.. warning::

   Where extreme care has to be taken.

.. admonition:: |ADMONITION_TITLE_DEPRECATED|

   Notes about a deprecated feature.

.. admonition:: |ADMONITION_TITLE_PREVIEW|

   Additional notes to a :ref:`Feature Preview <preface-conventions-feature-preview>`.