# Dominion Divider Generation
## Introduction
This is a script and library to generate card dividers for storing cards for the game [Dominion](https://boardgamegeek.com/boardgame/36218/dominion). If you are just looking go generate some dominion dividers, there is no need to install this script as I host a [live version of this generator code](http://domdiv.bgtools.net/). However, if you want to use arguments that I don't expose on that page, or change the code, or contribute to the project the full generation code (not the web interface or the fonts) is included here, and contributions are more than welcome.
Again, to generate tabs go to the **[Online Generator](http://domdiv.bgtools.net/)**.
## Installation
If you do need to install the package locally (the script provides a lot more options than the web-based generator), a simple `pip install domdiv` should suffice, providing a command by the name of `dominion_dividers`. However, see the note under Prerequisites->Fonts below as the default install will fall back on a font that doesn't match the cards (though most people don't notice). Run `dominion_dividers <outfile>` to get a pdf of all dividers with the default options, or run `dominion_dividers --help` to see the (extensive) list of options.
Additionally, to ensure the card dividers are generated sorted by correct alphabetical order (especially for languages with many accented characters (e.g. Czech)), you are advised to install the optional `PyICU` [library](https://gitlab.pyicu.org/main/pyicu). If `PyICU` is installed ([instructions](https://github.com/sumpfork/dominiontabs/wiki/PyICU-Installation-Instructions)), the script will sort the card dividers based on selected language alphabet (e.g. in Czech `z < ΕΎ`). Otherwise, default sorting will be used (the cards beginning with accented characters will be at the end of the sorted set).
## Documentation
The script has an extensive set of options that are relatively well documented via `dominion_dividers --help`. Some are hard to describe unless you see output samples, so we recommend running the script with various options to see which configuration you like. The help output is replicated [here](https://github.com/sumpfork/dominiontabs/wiki/Documentation-%28Script-Options%29) for reference.
## Translations
When changing any of the [card database files](card_db_src) you should run the language update tool via `doit update_languages`. This produces [the package version of the card db](src/domdiv/card_db) from the card db source. This will also be run automatically and checked into git when you push to github. You should make sure that the resulting changes to the package are what you intend by generating dividers in the relevant languages.
If you would like to help with translations to new (or updating existing) languages, please see [instructions here](src/domdiv/card_db/translation.md).
## Fonts
There are a number of fonts used in Dominion and many of them we cannot distribute with the package. We use fallbacks to commonly distributed fonts that work fine if you don't care the match the game exactly. If you do want to match, the script prints the preferred fonts if it uses fallbacks. Some come with programs like Adobe Reader and you can grab them from there.
Sadly, many of these fonts use features that are not support by the reportlab package. Thus, they need to first be converted to ttf (TrueType) format. I used the open source package fontforge to do the conversion. Included as 'tools/convert_font.ff' is a script for fontforge to do the conversion, on Mac OS X with fontforge installed through macports or homebrew you can just run commands like `./tools/convert_font.ff MinionPro-Regular.otf`.
If you select language in `domdiv` options which is not supported in [ISO/IEC 8859-1:1998 (Latin1)](https://en.wikipedia.org/wiki/ISO/IEC_8859-1#Modern_languages_with_complete_coverage) (e.g. Czech), you will have to obtain Times Roman TTF fonts as well (see `./src/domdiv/fonts/README.md` for details).
To supply fonts locally, put them in a directory and supply the relative path to it to the script via the `--font-dir` option. Alternatively you can copy the converted `.ttf` files to the `fonts` directory in the `domdiv` package/directory, then perform the package install below.
## Using as a library
The library will be installed as `domdiv` with the main entry point being `domdiv.main.generate(options)`. It takes a `Namespace` of options as generated by python's `argparser` module. You can either use `domdiv.main.parse_opts(cmdline_args)` to get such an object by passing in a list of command line options (like `sys.argv`), or directly create an appropriate object by assigning the correct values to its attributes, starting from an empty class or an actual argparse `Namespace` object.
## Developing
Install requirements via `pip install -r requirements.txt`. Then, run `pre-commit install`. You can use `pip install -e .[dev]` to install the `dominion_dividers` script so that it calls your checked out code, enabling you to run edited code without having to perform an install every time. This also installs needed dev dependencies, or if you want the pinned versions use `pip install -r dev-requirements.txt` instead.
Feel free to comment on boardgamegeek at <https://boardgamegeek.com/thread/926575/web-page-generate-tabbed-dividers> or file issues on github (<https://github.com/sumpfork/dominiontabs/issues>).
Tests can be run (and their dependencies installed) via `pip install .[dev]` and then `doit test`. They will also run if/when you push a branch or make a PR.
## Image Sources
There is a separate [repo](https://github.com/sumpfork/dominiontabs_img_sources) for the image sources. While these are optional, they can be useful reference and/or used for creating new or recreating old tab banners, icons, etc. Many of these were originally scans of the physical game. Some of them have a lot of layers and are approaching 1GB in size, so they are hosted via [Git LFS](https://git-lfs.com/). As the Github version of that incurs a higher monthly cost, I instead host them on a private LFS server. If you would like the images or would like to contribute images let me know and I can make you an account on said server, or you I can copy them for you for easier access.
## Docker
The project can be compiled into a container:
`docker build . -t dominiontabs`
Once you have the `dominiontabs` container you can run it from your CLI and pass it arguments like so, mapping the local directory to where the script will run so you can use local fonts and access the output file (example produces German dividers for Seaside 2nd edition):
`docker run -v .:/app dominiontabs --language=de --expansions=seaside2ndEdition`
<!--TODO update this doc to pull pre-built images from GitHub once those are set up-->
1. Bind mount to an output directory (`-v`) and tell the script to output there so that we get a PDF in the local filesystem when things are done (`--outfile ./output/foo.pdf`).
1. Add the `--rm` argo to tell docker not to save a container each time it runs.
1. Point to the fonts built in to the image with `--font-dir /fonts`
1. Add a few CLI args to reduce the runtime and file size (`--expansions cornucopia`).
So now we have
`docker run -v $PWD/output:/app/output --rm dominiontabs --font-dir /fonts --expansions cornucopia --outfile ./output/dominion_dividers_docker.pdf`
(Replace `$PWD` with `%cd%` on Windows OS)
Once that runs you should have under your current directory:
`./output/dominion_dividers_docker.pdf`
From there you feel free to add other arguments as you like!
Raw data
{
"_id": null,
"home_page": null,
"name": "domdiv",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "boardgame, cardgame, dividers",
"author": null,
"author_email": "Peter Gorniak <sumpfork@mailmight.net>",
"download_url": "https://files.pythonhosted.org/packages/21/f5/a1dbf2c851923ecc2acdc3d60c048ac66317a998e8b5cd95869e4f021661/domdiv-4.5.1.tar.gz",
"platform": null,
"description": "# Dominion Divider Generation\n\n\n\n## Introduction\n\nThis is a script and library to generate card dividers for storing cards for the game [Dominion](https://boardgamegeek.com/boardgame/36218/dominion). If you are just looking go generate some dominion dividers, there is no need to install this script as I host a [live version of this generator code](http://domdiv.bgtools.net/). However, if you want to use arguments that I don't expose on that page, or change the code, or contribute to the project the full generation code (not the web interface or the fonts) is included here, and contributions are more than welcome.\n\nAgain, to generate tabs go to the **[Online Generator](http://domdiv.bgtools.net/)**.\n\n## Installation\n\nIf you do need to install the package locally (the script provides a lot more options than the web-based generator), a simple `pip install domdiv` should suffice, providing a command by the name of `dominion_dividers`. However, see the note under Prerequisites->Fonts below as the default install will fall back on a font that doesn't match the cards (though most people don't notice). Run `dominion_dividers <outfile>` to get a pdf of all dividers with the default options, or run `dominion_dividers --help` to see the (extensive) list of options.\n\nAdditionally, to ensure the card dividers are generated sorted by correct alphabetical order (especially for languages with many accented characters (e.g. Czech)), you are advised to install the optional `PyICU` [library](https://gitlab.pyicu.org/main/pyicu). If `PyICU` is installed ([instructions](https://github.com/sumpfork/dominiontabs/wiki/PyICU-Installation-Instructions)), the script will sort the card dividers based on selected language alphabet (e.g. in Czech `z < \u017e`). Otherwise, default sorting will be used (the cards beginning with accented characters will be at the end of the sorted set).\n\n## Documentation\n\nThe script has an extensive set of options that are relatively well documented via `dominion_dividers --help`. Some are hard to describe unless you see output samples, so we recommend running the script with various options to see which configuration you like. The help output is replicated [here](https://github.com/sumpfork/dominiontabs/wiki/Documentation-%28Script-Options%29) for reference.\n\n## Translations\n\nWhen changing any of the [card database files](card_db_src) you should run the language update tool via `doit update_languages`. This produces [the package version of the card db](src/domdiv/card_db) from the card db source. This will also be run automatically and checked into git when you push to github. You should make sure that the resulting changes to the package are what you intend by generating dividers in the relevant languages.\n\nIf you would like to help with translations to new (or updating existing) languages, please see [instructions here](src/domdiv/card_db/translation.md).\n\n## Fonts\n\nThere are a number of fonts used in Dominion and many of them we cannot distribute with the package. We use fallbacks to commonly distributed fonts that work fine if you don't care the match the game exactly. If you do want to match, the script prints the preferred fonts if it uses fallbacks. Some come with programs like Adobe Reader and you can grab them from there.\n\nSadly, many of these fonts use features that are not support by the reportlab package. Thus, they need to first be converted to ttf (TrueType) format. I used the open source package fontforge to do the conversion. Included as 'tools/convert_font.ff' is a script for fontforge to do the conversion, on Mac OS X with fontforge installed through macports or homebrew you can just run commands like `./tools/convert_font.ff MinionPro-Regular.otf`.\n\nIf you select language in `domdiv` options which is not supported in [ISO/IEC 8859-1:1998 (Latin1)](https://en.wikipedia.org/wiki/ISO/IEC_8859-1#Modern_languages_with_complete_coverage) (e.g. Czech), you will have to obtain Times Roman TTF fonts as well (see `./src/domdiv/fonts/README.md` for details).\n\nTo supply fonts locally, put them in a directory and supply the relative path to it to the script via the `--font-dir` option. Alternatively you can copy the converted `.ttf` files to the `fonts` directory in the `domdiv` package/directory, then perform the package install below.\n\n## Using as a library\n\nThe library will be installed as `domdiv` with the main entry point being `domdiv.main.generate(options)`. It takes a `Namespace` of options as generated by python's `argparser` module. You can either use `domdiv.main.parse_opts(cmdline_args)` to get such an object by passing in a list of command line options (like `sys.argv`), or directly create an appropriate object by assigning the correct values to its attributes, starting from an empty class or an actual argparse `Namespace` object.\n\n## Developing\n\nInstall requirements via `pip install -r requirements.txt`. Then, run `pre-commit install`. You can use `pip install -e .[dev]` to install the `dominion_dividers` script so that it calls your checked out code, enabling you to run edited code without having to perform an install every time. This also installs needed dev dependencies, or if you want the pinned versions use `pip install -r dev-requirements.txt` instead.\n\nFeel free to comment on boardgamegeek at <https://boardgamegeek.com/thread/926575/web-page-generate-tabbed-dividers> or file issues on github (<https://github.com/sumpfork/dominiontabs/issues>).\n\nTests can be run (and their dependencies installed) via `pip install .[dev]` and then `doit test`. They will also run if/when you push a branch or make a PR.\n\n## Image Sources\n\nThere is a separate [repo](https://github.com/sumpfork/dominiontabs_img_sources) for the image sources. While these are optional, they can be useful reference and/or used for creating new or recreating old tab banners, icons, etc. Many of these were originally scans of the physical game. Some of them have a lot of layers and are approaching 1GB in size, so they are hosted via [Git LFS](https://git-lfs.com/). As the Github version of that incurs a higher monthly cost, I instead host them on a private LFS server. If you would like the images or would like to contribute images let me know and I can make you an account on said server, or you I can copy them for you for easier access.\n\n## Docker\n\nThe project can be compiled into a container:\n\n`docker build . -t dominiontabs`\n\nOnce you have the `dominiontabs` container you can run it from your CLI and pass it arguments like so, mapping the local directory to where the script will run so you can use local fonts and access the output file (example produces German dividers for Seaside 2nd edition):\n\n`docker run -v .:/app dominiontabs --language=de --expansions=seaside2ndEdition`\n\n<!--TODO update this doc to pull pre-built images from GitHub once those are set up-->\n\n1. Bind mount to an output directory (`-v`) and tell the script to output there so that we get a PDF in the local filesystem when things are done (`--outfile ./output/foo.pdf`).\n1. Add the `--rm` argo to tell docker not to save a container each time it runs.\n1. Point to the fonts built in to the image with `--font-dir /fonts`\n1. Add a few CLI args to reduce the runtime and file size (`--expansions cornucopia`).\n\nSo now we have\n\n`docker run -v $PWD/output:/app/output --rm dominiontabs --font-dir /fonts --expansions cornucopia --outfile ./output/dominion_dividers_docker.pdf`\n\n(Replace `$PWD` with `%cd%` on Windows OS)\n\nOnce that runs you should have under your current directory:\n\n`./output/dominion_dividers_docker.pdf`\n\nFrom there you feel free to add other arguments as you like!\n",
"bugtrack_url": null,
"license": null,
"summary": "Divider Generation for the Dominion Card Game",
"version": "4.5.1",
"project_urls": {
"Homepage": "http://domtabs.sandflea.org",
"Issue Tracker": "https://github.com/sumpfork/dominiontabs/issues",
"Say Thanks": "https://boardgamegeek.com/thread/926575/web-page-generate-tabbed-dividers",
"Source": "https://github.com/sumpfork/dominiontabs"
},
"split_keywords": [
"boardgame",
" cardgame",
" dividers"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e72aaf558af269102a9f658d1c892954803aad1c6cb0b03a2c9c26084e1e9f9a",
"md5": "eb288f44fc327c6bde4eca41531e39e2",
"sha256": "d74827a2cef3bf714002a24ddafb8e59724c720259a8c8645775a3dbf47d5544"
},
"downloads": -1,
"filename": "domdiv-4.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "eb288f44fc327c6bde4eca41531e39e2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 25078452,
"upload_time": "2024-04-08T21:24:27",
"upload_time_iso_8601": "2024-04-08T21:24:27.730829Z",
"url": "https://files.pythonhosted.org/packages/e7/2a/af558af269102a9f658d1c892954803aad1c6cb0b03a2c9c26084e1e9f9a/domdiv-4.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "21f5a1dbf2c851923ecc2acdc3d60c048ac66317a998e8b5cd95869e4f021661",
"md5": "2ffb7e554f9241d2e55cf7694a9c6ae7",
"sha256": "4244a5c72b91e18055d9a2168db2d64ea205504af0382bd0d6d8397ae058595f"
},
"downloads": -1,
"filename": "domdiv-4.5.1.tar.gz",
"has_sig": false,
"md5_digest": "2ffb7e554f9241d2e55cf7694a9c6ae7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 25969837,
"upload_time": "2024-04-08T21:24:30",
"upload_time_iso_8601": "2024-04-08T21:24:30.635180Z",
"url": "https://files.pythonhosted.org/packages/21/f5/a1dbf2c851923ecc2acdc3d60c048ac66317a998e8b5cd95869e4f021661/domdiv-4.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-08 21:24:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sumpfork",
"github_project": "dominiontabs",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "chardet",
"specs": [
[
"==",
"5.2.0"
]
]
},
{
"name": "configargparse",
"specs": [
[
"==",
"1.7"
]
]
},
{
"name": "pillow",
"specs": [
[
"==",
"10.3.0"
]
]
},
{
"name": "reportlab",
"specs": [
[
"==",
"4.1.0"
]
]
}
],
"tox": true,
"lcname": "domdiv"
}
JSON
