From 3405ae5c8d2506682fbfccfaf99bd7629ea98d6d Mon Sep 17 00:00:00 2001 From: ChristianH99 Date: Sun, 17 Dec 2023 20:27:07 +0100 Subject: [PATCH 1/6] Created script to build OnStage rules on Windows --- build_rules_on_windows.bat | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 build_rules_on_windows.bat diff --git a/build_rules_on_windows.bat b/build_rules_on_windows.bat new file mode 100644 index 0000000..661854b --- /dev/null +++ b/build_rules_on_windows.bat @@ -0,0 +1,27 @@ +@echo off + +REM Set the path to the Git repository +set REPO_PATH=/mnt/c/Users/%USERNAME%/Documents/GitHub/onstage-rules + +echo Running commands in WSL... + +REM Create temporary copies of .sh scripts with Linux-style line endings using wsl cp +wsl cp %REPO_PATH%/.ci/adoc-to-tex.sh %REPO_PATH%/.ci/adoc-to-tex-temp.sh +wsl cp %REPO_PATH%/.ci/tex-to-pdf.sh %REPO_PATH%/.ci/tex-to-pdf-temp.sh + +REM Convert line endings to LF (Linux-style) +wsl dos2unix %REPO_PATH%/.ci/adoc-to-tex-temp.sh +wsl dos2unix %REPO_PATH%/.ci/tex-to-pdf-temp.sh + +REM Run commands in WSL with sudo for Docker +wsl sudo docker run -v %REPO_PATH%:/documents asciidoctor/docker-asciidoctor .ci/adoc-to-tex-temp.sh onstage_rules +wsl sudo docker run -v %REPO_PATH%:/documents mrshu/texlive-dblatex .ci/tex-to-pdf-temp.sh onstage_rules + +REM Clean up temporary files +wsl rm %REPO_PATH%/.ci/adoc-to-tex-temp.sh +wsl rm %REPO_PATH%/.ci/tex-to-pdf-temp.sh + +echo WSL commands completed. + +REM Pause the script and wait for any key to be pressed +pause From c99d2b5a5acad4003bab66ed184eb480976cacd5 Mon Sep 17 00:00:00 2001 From: ChristianH99 Date: Sun, 17 Dec 2023 20:37:12 +0100 Subject: [PATCH 2/6] Modified script so that it uses a relative path to the adoc file instead of a fixed path to the .../Documents/GitHub/... folder --- build_rules_on_windows.bat | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/build_rules_on_windows.bat b/build_rules_on_windows.bat index 661854b..af74768 100644 --- a/build_rules_on_windows.bat +++ b/build_rules_on_windows.bat @@ -1,7 +1,13 @@ @echo off -REM Set the path to the Git repository -set REPO_PATH=/mnt/c/Users/%USERNAME%/Documents/GitHub/onstage-rules +REM Set the path to the Git repository dynamically +set REPO_PATH=%CD% + +REM Convert backslashes to forward slashes in WSL paths +set REPO_PATH=%REPO_PATH:\=/% + +REM Replace C: with /mnt/c/ +set REPO_PATH=%REPO_PATH:C:=/mnt/c% echo Running commands in WSL... From c045fe7f77e841aeb18facdfa78b85111f28290f Mon Sep 17 00:00:00 2001 From: ChristianH99 Date: Sun, 17 Dec 2023 20:48:44 +0100 Subject: [PATCH 3/6] Added check if dos2unix is already installed and install it if necessary --- build_rules_on_windows.bat | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/build_rules_on_windows.bat b/build_rules_on_windows.bat index af74768..5c1b3c6 100644 --- a/build_rules_on_windows.bat +++ b/build_rules_on_windows.bat @@ -11,6 +11,15 @@ set REPO_PATH=%REPO_PATH:C:=/mnt/c% echo Running commands in WSL... +REM Check if dos2unix is installed in WSL +wsl dos2unix --version >nul 2>&1 +if %errorlevel% neq 0 ( + echo Installing dos2unix... + REM Add installation command for dos2unix here + wsl sudo apt-get update + wsl sudo apt-get install dos2unix +) + REM Create temporary copies of .sh scripts with Linux-style line endings using wsl cp wsl cp %REPO_PATH%/.ci/adoc-to-tex.sh %REPO_PATH%/.ci/adoc-to-tex-temp.sh wsl cp %REPO_PATH%/.ci/tex-to-pdf.sh %REPO_PATH%/.ci/tex-to-pdf-temp.sh @@ -20,6 +29,7 @@ wsl dos2unix %REPO_PATH%/.ci/adoc-to-tex-temp.sh wsl dos2unix %REPO_PATH%/.ci/tex-to-pdf-temp.sh REM Run commands in WSL with sudo for Docker +@echo Building rules wsl sudo docker run -v %REPO_PATH%:/documents asciidoctor/docker-asciidoctor .ci/adoc-to-tex-temp.sh onstage_rules wsl sudo docker run -v %REPO_PATH%:/documents mrshu/texlive-dblatex .ci/tex-to-pdf-temp.sh onstage_rules From ef918c6754825ff32042efd0992dea84e7fadc8f Mon Sep 17 00:00:00 2001 From: ChristianH99 Date: Sun, 17 Dec 2023 20:50:23 +0100 Subject: [PATCH 4/6] Added note on why to use dos2unix --- build_rules_on_windows.bat | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/build_rules_on_windows.bat b/build_rules_on_windows.bat index 5c1b3c6..bf4ebf0 100644 --- a/build_rules_on_windows.bat +++ b/build_rules_on_windows.bat @@ -20,7 +20,7 @@ if %errorlevel% neq 0 ( wsl sudo apt-get install dos2unix ) -REM Create temporary copies of .sh scripts with Linux-style line endings using wsl cp +REM Create temporary copies of .sh scripts with Linux-style line endings using wsl cp (because Github checkout might automatically change them to Windows style which will stop the scripts from working) wsl cp %REPO_PATH%/.ci/adoc-to-tex.sh %REPO_PATH%/.ci/adoc-to-tex-temp.sh wsl cp %REPO_PATH%/.ci/tex-to-pdf.sh %REPO_PATH%/.ci/tex-to-pdf-temp.sh From 4387e4aa5a2b1ddc0c6043d83066c35df8265980 Mon Sep 17 00:00:00 2001 From: ChristianH99 Date: Sun, 17 Dec 2023 20:52:04 +0100 Subject: [PATCH 5/6] Create README.md with instructions on how to build the rules on linux and windows --- README.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..871f2d9 --- /dev/null +++ b/README.md @@ -0,0 +1,50 @@ +## Building the PDF rules on your own + +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](https://asciidoctor.org/docs/asciidoc-writers-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: + +1. `AsciiDoc` -> `CriticMarked AsciiDoc` (_to visualize rule changes in red_) +2. `CriticMarked AsciiDoc` -> **HTML** +3. `CriticMarked AsciiDoc` -> `LaTeX` (for formatting purposes) +4. `LaTeX` -> `LaTeX + RCJ Soccer formatting` (_to ensure uniformity of the output_) +5. `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](http://travis-ci.org/) +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. + +### Linux or MacOS System + +1. Install [Docker](https://docker.com) with the instructions on the website. +2. Open a console and run the following commands +3. `docker run -v $(pwd):/documents asciidoctor/docker-asciidoctor .ci/adoc-to-tex.sh rules` +4. `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. + +### Windows System + +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. + +1. Install the [Windows subsystem for linux(WSL)](https://learn.microsoft.com/en-us/windows/wsl/install) +2. Open the WSL (search for WSL in the Windows search bar) and create username and passwort +5. Install [Docker](https://docker.com) with the instructions on the website if not done yet +6. Run the [build_rules_on_windows script](https://github.com/robocup-junior/onstage-rules/blob/main/build_rules_on_windows.bat) to build the rules + +You can now find the PDF and HTML version of the rules in the rules_documents folder. From 6dd4416cba1f764eb13c67b4de952a93d3e76e1d Mon Sep 17 00:00:00 2001 From: ChristianH99 Date: Sun, 17 Dec 2023 20:53:32 +0100 Subject: [PATCH 6/6] Fixed typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 871f2d9..67d5296 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ that's the `$(pwd)` part) go through the build steps above and generate the file 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. -1. Install the [Windows subsystem for linux(WSL)](https://learn.microsoft.com/en-us/windows/wsl/install) +1. Install the [Windows subsystem for linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/install) 2. Open the WSL (search for WSL in the Windows search bar) and create username and passwort 5. Install [Docker](https://docker.com) with the instructions on the website if not done yet 6. Run the [build_rules_on_windows script](https://github.com/robocup-junior/onstage-rules/blob/main/build_rules_on_windows.bat) to build the rules