The rules are written in a format called asciidoc
. It is very similar to
Markdown but unlike Markdown, it is very extensible and has a nice ecosystems
of tools around it. To get a feel for what it looks like, please take a look at
the AsciiDoc Writer's Guide.
Despite how great it is, the rules cannot be built with AsciiDoc alone. They need to be exported into PDF, in a specific format, and we'd also like them to highlight the changes in a nice way and automatically generate IDs for each paragraph. To do all this, the input AsciiDoc file goes thorugh the following steps:
AsciiDoc
->CriticMarked AsciiDoc
(to visualize rule changes in red)CriticMarked AsciiDoc
-> HTMLCriticMarked AsciiDoc
->LaTeX
(for formatting purposes)LaTeX
->LaTeX + RCJ Soccer formatting
(to ensure uniformity of the output)LaTeX + RCJ Soccer formatting
-> PDF
At the end of this process we end up with a HTML and a PDF version of the AsciiDoc file we started with.
This repository is connected to so called Travis CI which allows us to automatically build the rules whenever any change/update takes place.
If you'd like to build the rules on your own computer you have to follow the instructions below.
- Install Docker with the instructions on the website.
- Open a console and run the following commands
docker run -v $(pwd):/documents asciidoctor/docker-asciidoctor .ci/adoc-to-tex.sh rules
docker run -v $(pwd):/documents mrshu/texlive-dblatex .ci/tex-to-pdf.sh rules
These commands will make the rules.adoc
file (in the current working directory --
that's the $(pwd)
part) go through the build steps above and generate the files
rules.html
and rules.pdf
as a result.
When running on Windows you initially have to do a few extra extra steps to be able to build the rules using the Linux scripts with the windows subsystem for Linux.
- Install the Windows subsystem for linux (WSL)
- Open the WSL (search for WSL in the Windows search bar) and create username and passwort
- Install Docker with the instructions on the website if not done yet
- Run the build_rules_on_windows script to build the rules
It helps to have a wsl console runing in the background all the time to avaoid windows starting and stopping it everytime the script is run, as this takes up some time. Just type wsl in the windows search bar to open it.
You can now find the PDF and HTML version of the rules in the rules_documents folder.