Farbschlüssel

Downloads des Blox-Projektes | Downloads der gesamten Site | Impressum

Inhalt dieser Seite

1   Übersicht

Dieses Paket ermöglicht es, in der Fußzeile einer Seite eine Aufschlüsselung der in Roles für die Programmierung eingeführten Schlüsselfarben anzubringen. Dafür werden die folgenden Dateien verwandt:

  1. Eine CSS-Datei colourkeys.css. Diese enthält die Stile für Farbschlüssel und deren Einträge.
  2. Eine sprachspezifische ReST-Datei Colourkeys.rst, welche Ersetzungen beinhaltet, um die Einträge im Schlüssel zu benennen.

Mit diesen Dateien ist es dann möglich zu schreiben:

.. include:: Colourkeys.rst

.. container:: colour-keys

    |class-key| |meth-key| |attr-key| |func-key| |mod-key| |file-key|

Man braucht dabei nur diejenigen Einträge aufzulisten, welche auch tatsächlich für das Dokument relevant sind.

Der colour-keys-Container kann bspw. in der Fußzeile positioniert werden. Eine typische Fußzeilendefinition lautet also:

.. footer::

    .. container:: colour-keys

        |class-key| |meth-key| (...)

    (...)

Einen mit Hilfe dieses Pakets definierten Farbschlüssel findet man in der Fußzeile dieser Seite.

2   Ersetzungen für die Einträge des Farbschlüssels

Die Ersetzungen (z.B. |class-key|) werden von Colourkeys.rst geliefert. In der deutschsprachigen Version lautet der Inhalt dieser Datei:

Colourkeys.rst (de)
.. :Blox:`colourkeys.css`

.. |class-key| replace:: :class:`Klasse`
.. |meth-key| replace:: :meth:`Methode`
.. |attr-key| replace:: :attr:`Attribut`
.. |func-key| replace:: :func:`Funktion`
.. |mod-key| replace:: :mod:`Modul`
.. |file-key| replace:: :file:`Datei`

und in der englischen Variante:

Colourkeys.rst (en)
.. :Blox:`colourkeys.css`

.. |class-key| replace:: :class:`Class`
.. |meth-key| replace:: :meth:`Method`
.. |attr-key| replace:: :attr:`Attribute`
.. |func-key| replace:: :func:`Function`
.. |mod-key| replace:: :mod:`Module`
.. |file-key| replace:: :file:`File`

Die Colourkeys.rst-Dateien enthalten dabei einen Abhängigkeitmarker:

.. :Blox:`colourkeys.css`

Durch diesen wird auf das jeweilige Dokument der in colourkeys.css beschriebene Stil angewendet, sobald Colourkeys.rst eingebunden wird.

Die Ersetzungen lassen sich direkt verwenden:

|class-key| |meth-key| |attr-key| |func-key| |mod-key| |file-key|

mit dem Ergebnis:

Klasse Methode Attribut Funktion Modul Datei

In der tatsächlichen Anwendung werden genau die gleichen Ersetzungen benutzt (|class-key| etc.), allerdings wird das Ergebnis durch CSS anders formatiert.

3   Formatierung der Aufschlüsselung und ihrer Einträge

Der Farbschlüssel soll folgendes Erscheinungsbild haben:

  1. Die Eintragsliste soll rechtsbündig in einer Zeile erscheinen.
  2. Jeder Schlüsseleintrag soll mit einer Umrandung versehen werden. Die Umrandung soll die Farbe des umrandeten Textes haben. Um den Text des umrandeten Eintrags soll bis zur Umrandungslinie etwas Platz bleiben.
  3. Zwischen den Einträgen und ober/unterhalb der Aufschlüsselung soll etwas Raum sein.

Der durch:

.. container:: colour-keys

    (...)

erzeugte div.colour-keys-Abschnitt wird formatiert per:

div.colour-keys {
    display: flex;
    column-gap: 1ex;
    justify-content: flex-end;

    margin-top: 1ex;
    margin-bottom: 1ex;
}

Der Anweisungsblock dieser Regel ist in zwei Abschnitte gegliedert:

Alle aufzuschlüsselnden Farb-Roles, wie sie in Roles für die Programmierung definiert wurden, sind von literal abgeleitet und erzeugen daher tt-Elemente. Der CSS-Code in colourkeys.css zur Umrandung der Einträge des Farbschlüssels verwendet dies, indem er spezifiziert:

div.colour-keys tt {
    border: thin solid currentColor;
    border-radius: 1em;
    padding: 0.5ex 1.5ex;
}

Hier werden die von den Roles erzeugten tt-Elemente im colour-keys-Container selektiert. border: thin solid currentColor erzeugt eine dünne (thin) durchgezogene (solid) Umrandung um diese tt-Elemente. Die jeweilige Role (:class:, :meth: etc.) setzt die Schriftfarbe, welche durch Verwendung von currentColor auf die Umrandung vererbt wird. Durch border-radius: 1em werden die Umrandungen an den seitlichen Enden abgerundet. padding: 0.5ex 1.5ex separiert die Umrandungslinien der einzelnen Einträge von deren Beschriftung oben/unten um 0.5ex, und links/rechts um 1.5ex. Das vertikale Padding wurde dabei als erstes entschieden, und das horizontale Padding wurde so gewählt, dass der Linienzug im Ergebnis nicht mit der Schrift überlappt.

Es ergibt sich insgesamt für das Stylesheet:

colourkeys.css
/* Developed since: July 2024
 * Based on work dating back to pre-July 2023.
 */


div.colour-keys {
    display: flex;
    column-gap: 1ex;
    justify-content: flex-end;

    margin-top: 1ex;
    margin-bottom: 1ex;
}

div.colour-keys tt {
    border: thin solid currentColor;
    border-radius: 1em;
    padding: 0.5ex 1.5ex;
}

4   Verwendung der Paketdateien

Für die Bereitstellung der Dateien dieses Pakets gelten die folgenden Regeln:

  1. Die sprachabhängige Datei Colourkeys.rst kann in Sources/Compounds/LG/ abgelegt werden, entsprechend der jeweiligen Sprache (LG).
  2. Die sprachuniverselle Datei colourkeys.css kann in Sources/Supp/Common/ bereitgestellt werden.

Die so zugänglich gemachten Dateien müssen über die jeweils zuständige .blox-Datei ins Projekt eingeschlossen werden. Der Zweck der ReST-Dateien sollte dabei als /rst/ bestimmt werden, und für die CSS-Datei wird /css/ verwendet. Während die Zweckbestimmung der ReST-Dateien eher der Vollständigkeit halber geschieht, muss die CSS-Datei mit /css/ versehen werden, damit sie als Stylesheet eingebunden wird, wenn dies notwendig ist. Der Compiler wird dann die in den Colourkeys.rst-Dateien spezifizierte Abhängigkeit vom Stylesheet beachten, wenn das Projekt übersetzt wird.