Colour Keys

Imprint

Inhalt dieser Seite

1   Overview

This package permits placing in the footer of a page an itemisation of the key colours defined in Programming Roles. For this the following files are used:

  1. A CSS file colourkeys.css. This contains styles for the itemisation and its entries.
  2. A language-specific ReST file Colourkeys.rst, containing replacements to name the entries in the itemisation.

With these files it is then possible to write:

.. include:: Colourkeys.rst

.. container:: colour-keys

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

One needs to list here only those items which are actually relevant for the document.

The colour-keys container can be placed e.g. in the footer. A typical footer definition thus runs:

.. footer::

    .. container:: colour-keys

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

    (...)

A colour key itemisation defined with the help of this package can be found in the footer of this page.

2   Replacements for the Entries of the Itemisation

The Replacements (e.g. |class-key|) are provided by Colourkeys.rst. In the English version the content of this file runs:

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`

and in the German variant:

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`

The Colourkeys.rst files contain thereby a dependency mark:

.. :Blox:`colourkeys.css`

By this, the style described by colourkeys.css is applied to the respective document as soon as Colourkeys.rst is included.

The replacements can be used directly:

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

with the result:

Class Method Attribute Function Module File

In the actual application precisely the same replacements are used (|class-key| etc.), but the result is styled by CSS in another way.

3   Styling the Itemisation and its Entries

The itemisation shall have the following visual appearance:

  1. The itemisation list shall appear right-flushed in a row.
  2. Each entry shall be outfitted with a border. The border shall have the colour of the outlined text. Around the text of the bordered entry some space should remain up to the border line.
  3. Between entries and above/below the itemisation some padding shall be present.

The div.colour-keys section defined by:

.. container:: colour-keys

    (...)

is formatted via:

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

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

The instruction block of this rule is separated in two sections:

All colour roles to be itemised, as defined by Programming Roles, are derived from literal and thus create tt elements. The CSS code in colourkeys.css to adorn the entries of the itemisation each with a border uses this by specifying:

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

Here, all tt elements in the colour-keys container created by the roles are selected. border: thin solid currentColor creates around these tt elements a thin solid border. The specific roles (:class:, :meth: etc.) set the text colour, which is inherited to the border by using currentColor. The declaration border-radius: 1em rounds the borders at the left and right ends. padding: 0.5ex 1.5ex separates the border lines of the singular entries from their label text at the top/bottom sides by 0.5ex, and at the left/right ends by 1.5ex. The vertical padding has been decided at first, and the horizontal padding has then been chosed such that the resulting line is not overlapping with the text.

It results for the entire style sheet:

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   Using the Package Files

For provisioning the files of this package the following rules apply:

  1. The language-dependent file Colourkeys.rst can be placed in Sources/Compounds/LG/, according to the respective language (LG).
  2. The language-universal file colourkeys.css can be made available via Sources/Supp/Common/.

The files made accessible in this way need to be included into the project by the corresponding .blox files. The purpose of the ReST files should be thereby be defined as /rst/, and for the CSS file /css/ is used. While the purpose definition of the ReST files is rather for the sake of completeness, the CSS file must be provided with /css/, such that it is included as a stylesheet when required. The compiler will then respect the dependency on the style sheet specified in the Colourkeys.rst files when the project is compiled.