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:
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.
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.
Der Farbschlüssel soll folgendes Erscheinungsbild haben:
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:
div.colour-keys-Element als
horizontalen Flex-Container (display: flex). Zwischen den
einzelnen Elementen wird dabei 1ex Raum gelassen
(column-gap: 1ex) und prinzipiell werden die enthaltenen
Elemente am rechten Ende angeordnet (justify-content: flex-end).1ex; dies ist ein für die Verwendung in der Fußzeile
angemessener Wert.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; }
Für die Bereitstellung der Dateien dieses Pakets gelten die folgenden Regeln:
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.