CMYK

.github/workflows/black.yaml

@@ -7,8 +7,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: psf/black@stable
+      - name: Set up Python
+        uses: actions/setup-python@v5
         with:
-          options: "--check --verbose"
-          src: "./protograf"
-          use_pyproject: true
+          python-version: '3.11'
+      - name: Install specific Black version
+        run: |
+          pip install black==25.1.0  # desired version here
+      - name: Run Black check
+        run: |
+          black --check --verbose ./protograf

CHANGES.txt

@@ -1,16 +1,31 @@
 protograf Changes
 =================
 
-2026-00-00 (0.4.6)
+2026-00-00 (0.4.7)
 ------------------
-- [PLANNED] Enable Line connections to Ellipse shapes
-- [PLANNED] Enable Line connections to Stadium shapes
-- [PLANNED] Enable text labels for snail lines
-- [PLANNED] Add code to connect *Locations
-- [PLANNED] Docs: list all props for Hex, Circle, Rectangle, Line
-- [PLANNED] Support compass directions for Circle radii
-
-2026-00-00 (0.4.5)
+- [PLANNED-1] Enable curve for a Line
+- [PLANNED-2] Enable non-curve Line connections to Ellipse shapes
+- [PLANNED-2] Enable Line connections to Stadium shapes
+- [PLANNED-2] Enable Line connections to Rhombus shapes
+- [PLANNED-2] Enable Line connections to Text shapes
+- [PLANNED-2] Add Circle/Dot end for an arrowhead
+- [PLANNED-2] Enable centred multi-line shape label
+- [PLANNED-3] Add code to connect *Locations
+- [PLANNED-3] Docs: list all props for Hex, Circle, Rectangle, Line
+
+2026-03-014 (0.4.6)
+------------------
+- Enable radii for Ellipse shapes
+- Support compass directions for Circle radii
+- Patch error with label rotation for Line
+- Add diagram example for New Classic Board Games
+- Add CMYK support for colors
+- Add Card-specific bleed area
+- Enable vertical alignment of wrap Text
+- Allow shapes to use multiple Default commands
+- Add a script to generate a basic Card template
+
+2026-03-01 (0.4.5)
 ------------------
 - Enable grid marks for Hexagonal cards
 - Add DiamondLocations for Layout

CONTRIBUTORS.txt

@@ -1,3 +1,4 @@
 Derek Richard Hohls <[email protected]> - primary designer and author
-Kate Walsh https://kathleenmaywalsh.wixsite.com/copywriter - docs proof-reader and editor
+R. Martinho Fernandes - https://github.com/rmartinho - contributor
+Kate Walsh - https://kathleenmaywalsh.wixsite.com/copywriter - proof-reader and editor
 Rory Meyer - https://github.com/RoryMMMM - maintainer

LICENSE

@@ -1,6 +1,6 @@
 protograf - a Python program to support graphic layouts
 
-Copyright (c) 2016-2025, Derek Richard Hohls
+Copyright (c) 2016-2026, Derek Richard Hohls
 
 This program is free software: you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
@@ -14,3 +14,6 @@ GNU General Public License for more details.
 
 You should have received a copy of the GNU General Public License
 along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Individual scripts which use this software may be released under their
+own licenses.  Consult the text embedded in each script for details.

README.md

@@ -7,8 +7,8 @@ graphical designs in PDF (or PNG/GIF/SVG) format via a script.
 
 __protograf__  has been primarily created to handle the prototyping of cards,
 counters, tiles and boards for board games, including hexagonal grids, but can
-also be used for creating any simple design that has regular or repetitive
-elements; typically a mix of graphics and text.
+also be used for creating any relatively simple design that has regular or
+repetitive elements; typically a mix of graphics and text.
 
 > You do not need to know the Python language to be able to use __protograf__
 > but you do need Python installed on your machine!
@@ -33,7 +33,7 @@ __protograf__ requires Python (version of 3.13 or higher) to be installed
 and running on your machine.
 
 If this is **not** your current Python version, or Python is not installed on
-your machine, may want to [install uv](https://docs.astral.sh/uv/getting-started/installation/)
+your machine, you may want to [install uv](https://docs.astral.sh/uv/getting-started/installation/)
 which is a cross-platform tool able to [install Python](https://docs.astral.sh/uv/guides/install-python).
 
 If using [uv](https://docs.astral.sh/uv/), it is recommended to also create and use a
@@ -99,8 +99,8 @@ Please see the [list of contributors](CONTRIBUTORS.txt).
 
 ## :game_die: Potential Features
 
-These features are **not** guaranteed to be implemented; they just represent
-current / potential areas of work or ideas.
+Features not yet checked off are **not** guaranteed to be implemented;
+they just represent current / potential areas of work or ideas.
 
 * [x] New Shapes:
     * [x] Cross shape
@@ -119,19 +119,20 @@ current / potential areas of work or ideas.
 * [x] Stripes: interior "areas" for a Rectangle
 * [ ] Cards:
     * [x] support card-back designs
-    * [ ] grid lines for hexagonal cards
+    * [x] grid lines for hexagonal cards
     * [x] corner crosses as grid marks
     * [x] access to Google Sheets
     * [x] extract rectangular cards as PNG files
     * [x] page annotations
-* [ ] Color:
-    * [ ] add support for CYMK
+    * [x] bleed areas
+    * [ ] extraction as TableTopSimulator deck
+* [x] Color:
+    * [x] add support for CYMK
 
 ## :jigsaw: Potential Examples
 
 These are possible examples to show board creation based on existing games:
 
-* [ ] Extra abstract game boards: Mancala, Mu Torere
 * [ ] Wargame board: Squad Leader with full terrain features (vector and bitmap)
 * [ ] Traveller board: show a fully-styled Star System
 * [x] WarpWar board: show a fully-styled example
@@ -143,7 +144,7 @@ These are possible examples to show board creation based on existing games:
 > skimming off a tiny bit of it.*
 > "[Snow Crash](https://en.wikipedia.org/wiki/Snow_Crash)", Neal Stephenson, 1992.
 
-As always, with Python, you are building "on the shoulders of giants".
+As usual, with Python, you are building "on the shoulders of giants".
 In this case, the [pyMuPDF](https://pymupdf.io/) library provides all of the
 core infrastructure used to do the underlying graphics processing, PDF file
 creation and images exports; __protograf__ is effectively a highly customised
@@ -157,6 +158,8 @@ also a powerful and useful library for supporting this type of application.
 Users on [BoardGameGeek](https://boardgamegeek.com) have provided invaluable
 feedback and suggestions!
 
+Those who have directly contributed to the project are listed in CONTRIBUTORS.
+
 ### :books: Additional Libraries
 
 * `cairoSVG` https://pypi.org/project/cairosvg/ - support for drawing SVG images

docs/source/additional_commands.rst

@@ -32,7 +32,7 @@ The ``Common()`` command allows different shapes to use exactly the same
 properties.
 
 These properties are listed in much the same way as they would for an actual
-shape, but the ``Common()`` command does not actually draw anything itself.
+shape, but the ``Common()`` command does *not* actually draw anything itself.
 
 For example:
 
@@ -57,27 +57,67 @@ Default Command
 ===============
 `↑ <table-of-contents-addcmd_>`_
 
-The ``Default()`` command allows different shapes to potentially all use the
-same properties.
+The ``Default()`` command allows different shapes to potentially all share
+the same properties.
 
 These properties are listed in much the same way as they would for an actual
-shape, but the ``Default()`` command does not actually draw anything itself.
+shape, but the ``Default()`` command does *not* actually draw anything itself.
+
+.. NOTE::
+
+    Unlike the ``Common()`` command, the common properties set by the
+    ``Default()`` command **will**  be overwritten by any of the same
+    ones which are set by the shape itself!
+
+For a shape to make use of properties set by a ``Default()`` command, the shape
+must assign the name given to the ``Default()`` to its *default* property.
 
 For example:
 
-.. code:: python
+.. |dfc| image:: images/custom/commands/defaults.png
+   :width: 330
 
-  colors = Default(stroke="tomato", fill="gold")
-  Circle(default=colors, cx=1, cy=2)
-  Square(default=colors, cx=2, cy=2)
+===== ======
+|dfc| This example shows setting and using defaults for shapes.
 
-Here the circle and the square will both use the ``default`` properties that
-have been assigned to the ``colors`` name.
+      .. code:: python
 
-.. NOTE::
+        def1 = Default(
+            radius=0.75, fill="gold", stroke_width=4)
+        def2 = Default(
+            label="ne", label_size=24, stroke_width=2)
+
+        Circle(
+            default=def2,
+            cx=1, cy=1, label_size=12)
+        Circle(
+            default=def1,
+            cx=2, cy=2.5, fill="aqua")
+        Circle(
+            default=[def1, def2],
+            cx=3, cy=5, radius=1)
+
+      Here the various circles make use of the ``default`` properties that
+      have been assigned to the ``def1`` and ``def2`` names.
+
+      The top circle makes use of properties assigned to ``def2`` to set
+      the properties of *radius*, *fill* and *stroke_width*.
+
+      The middle circle makes use of properties assigned to ``def1``.
+      However, the *fill* color is set to ``aqua`` and not ``gold``
+      because the property value set in the shape itself overrides the
+      one supplied in ``def1``.
+
+      The bottom circle makes use of properties assigned to **both** of the
+      ``def1`` and ``def2`` names.  It does this by using them in a list
+      format, as shown by the square brackets from ``[`` to ``]``.
+
+      Note that the **order**, when using multiple Defaults, is important.
+      Its clear in the bottom circle that ``stroke_width=2`` from ``def2``
+      supercedes ``stroke_width=4`` from ``def1`` i.e. the values from
+      the second, and onwards, Defaults override those from earlier ones.
 
-  Unlike the ``Common()`` command, the common properties set here **will**
-  be overwritten by any of the same ones which are set by the shape itself!
+===== ======
 
 
 .. _the-font-command:
@@ -378,12 +418,12 @@ Examples of using BGG API data for card creation can be found at
    2. Access to the BGG API requires that you apply to the site and request
       permission; when granted, this will allow you to generate a *token*
       |dash| a long, unique, set of characters and numbers that look something
-      like ``48398139-7fb1-4809-b7af-0be28d35dcec`` |dash| for details see 
+      like ``48398139-7fb1-4809-b7af-0be28d35dcec`` |dash| for details see
       https://boardgamegeek.com/application/
    3. Furthermore, there is an upper limit to how many games can be retrieved
       at a time |dash| best available knowledge suggests this is about 15,000.
-   4. Copies are kept of data downloaded from BGG |dash| and this data will 
-      *not* be re-retrieved from BGG unless you delete those copies; 
+   4. Copies are kept of data downloaded from BGG |dash| and this data will
+      *not* be re-retrieved from BGG unless you delete those copies;
       see `Caching`_ below.
 
 Usage
@@ -395,10 +435,10 @@ The ``BGG`` command allows game data to be retrieved either by providing:
   game IDs
 - the ID of a BoardGameGeek user; by default all games in that user's collection
   will be retrieved, unless filters are used
-  
+
 In both cases, you will also need to supply your **BGG API token**.
 
-The ID of a game appears in its URL; so, for example, the ID for the boardgame 
+The ID of a game appears in its URL; so, for example, the ID for the boardgame
 "Monopoly" is ``1406`` and is found at https://boardgamegeek.com/boardgame/1406
 
 
@@ -460,8 +500,8 @@ running :doc:`protograf <index>`).
 
 The caching directory is called ``.protograf`` and this will have a ``bgg``
 subdirectory where game data |dash| in the form of ``.pck`` files and
-``images`` and ``thumbs`` |dash| are stored.  If you delete these folders and 
-files, they will be recreated the next time your script runs 
+``images`` and ``thumbs`` |dash| are stored.  If you delete these folders and
+files, they will be recreated the next time your script runs
 i.e. all of their data will need to be downloaded again.
 
 

docs/source/basic_concepts.rst

@@ -233,20 +233,17 @@ Working with color
 
 Everything we see has color.
 
-Color in **protograf**, is defined in the same way as it is in pages
+Color in **protograf**, can be defined in the same way as it is in pages
 that appear on the web i.e. in RGB |dash| red-green-blue |dash| *hexadecimal*
-format; for example, ``#4C271B`` represents a dark shade of the color that we
+format; for example, ``#A0522D`` represents a darker shade of the color that we
 would likely term :dark-brown:`"brown"`, while "basic" colors have their own
 values; :yellow:`"yellow"` is ``#FFFF00``, :red:`"red"` is ``#FF0000``, and
-:blue:`"blue"` is ``#0000FF``.
+:blue:`"blue"` is ``#0000FF``.  RGB colors in **protograf** can also make use
+of names from a pre-defined list - for example ``#A0522D`` is defined as the
+color *sienna*.
 
-Colors in **protograf** can also make use of names from a pre-defined
-list - for example ``#A0522D`` is defined as the color *sienna*. The
-`colorset.pdf <https://github.com/gamesbook/protograf/blob/master/examples/colorset.pdf>`_
-file shows all the names of colors that are available, along with their
-*hexadecimal* value.  The
-`colorset_svg.pdf <https://github.com/gamesbook/protograf/blob/master/examples/colorset_svg.pdf>`_
-shows the subset of names and colors available for SVG documents.
+Color can also be defined using CMYK color values; for example the *sienna*
+color can also be set via these 4 values: ``"0, 48.75, 71.87, 37.2"``.
 
 Color properties in **protograf** are typically set either with a *"fill"*,
 which defines the color of a whole area, or a *"stroke"* which determines
@@ -257,39 +254,8 @@ The :ref:`default <default-concept>` **colors** in **protograf**  are
 
 .. HINT::
 
-   For more details on hexadecimal colors, refer to
-   http://www.w3.org/TR/css3-color; the color names are listed in the
-   section https://www.w3.org/TR/css-color-3/#svg-color (this list can
-   also be found at https://en.wikipedia.org/wiki/X11_color_names)
-
-Quick Colors
-------------
-`↑ <table-of-contents-basic_>`_
-
-A list of "one-letter" colors is also available (based off of a popular
-Python library called *matplotlib*); their hexadecimal codes are also
-shown here for reference:
-
-- ``b`` is blue ("#0000FF")
-- ``c`` is cyan ("#00FFFF")
-- ``d`` is dark blue ("#293BC7")
-- ``e`` is earth/natural ("#F3B54A")
-- ``f`` is forest green ("#007700")
-- ``g`` is green/malachite ("#32CD32")
-- ``h`` is brown/cinnamon ("#D2691E")
-- ``i`` is pink ("#E6506E")
-- ``k`` is black ("#000000")
-- ``l`` is picton blue ("#00BFFF")
-- ``m`` is magenta/violet ("#BF00BF")
-- ``n`` is orange ("#FFA500")
-- ``o`` is white ("#FFFFFF")
-- ``p`` is purple/lavender ("#EE82EE")
-- ``r`` is red ("#FF0000")
-- ``s`` is silver/gray ("#C0C0C0")
-- ``u`` is dark/derby brown ("#4C271B")
-- ``w`` is white ("#FFFFFF")
-- ``y`` is yellow ("#FFFF00")
-- ``x`` is black ("#000000")
+   For more details on colors, and color models, refer to the section on
+   :ref:`Color-orientated Terms <termsColor>`.
 
 
 .. _basic-units:
@@ -397,3 +363,9 @@ Some examples of defaults are:
 
   Use the :ref:`Create <create-command>` command to set your own output
   *filename*.
+
+Finally |dash| and perhaps confusingly |dash| :doc:`protograf <index>` also
+allows you to create your own "defaults" which represent properties that you
+want to share among a number of geometric **shapes**, or text, that make up
+your design; for more on this, see the :ref:`Default <the-default-command>`
+command.