From 527216eb95af095b807a6edd1ddedc8327381f03 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Llu=C3=ADs=20Alemany=20Puig?= Date: Sat, 30 Aug 2025 15:04:00 +0200 Subject: [PATCH 1/7] Optionally specify margin size #396 (#411) Whoever wants to shrink the margins, they can now do so via the new optional command line arguments --geometry:left --geometry:right --geometry:top --geometry:bottom which are default options in pandoc (see pandoc's documentation [here](https://pandoc.org/demo/example33/6.2-variables.html)). Their default value is ''. These options are not passed to pandoc when their value is ''. The argument parser added can be extended easily with other pandoc's argument options. If the new options' default value is '' then they will not be passed to pandoc. --- build_ebook.py | 24 +++++++++++++++++++----- make_parser.py | 37 +++++++++++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+), 5 deletions(-) create mode 100644 make_parser.py diff --git a/build_ebook.py b/build_ebook.py index 39e9a969..112483dc 100755 --- a/build_ebook.py +++ b/build_ebook.py @@ -11,6 +11,9 @@ from subprocess import CalledProcessError from re import Match import shutil +import argparse +import sys +from make_parser import make_parser logging.basicConfig( format="%(asctime)s %(levelname)-8s %(message)s", @@ -148,7 +151,7 @@ def compile_full_markdown( return markdown_file -def build_pdf(markdown_file: Path, pdf_file: Path) -> Path: +def build_pdf(markdown_file: Path, pdf_file: Path, args: argparse.Namespace) -> Path: """Build combined Markdown file into a PDF.""" try: @@ -157,12 +160,21 @@ def build_pdf(markdown_file: Path, pdf_file: Path) -> Path: raise RuntimeError(f"failed to build {pdf_file}: xelatex not installed") try: + keys_values = [(arg, getattr(args, arg)) for arg in vars(args)] + opts = [f"{key}={val}" for key, val in keys_values if val != ""] + pandoc_args = [x for i in opts for x in ("-V", i)] + subprocess.check_output( [ "pandoc", markdown_file.as_posix(), "-V", - "documentclass=report", + "documentclass=report" + ] + + + pandoc_args + + + [ "-t", "latex", "-s", @@ -202,8 +214,10 @@ def build_epub(markdown_file: Path, epub_file: Path) -> Path: return epub_file - def main() -> None: + parser = make_parser() + args = parser.parse_args(sys.argv[1:]) + """Build ebooks.""" with TemporaryDirectory() as raw_out_dir: out_dir = Path(raw_out_dir) @@ -223,11 +237,11 @@ def main() -> None: ) logging.info(f"{lang}: building pdf...") - pdf_file = build_pdf(markdown_file, out_dir / f"{lang}.pdf") + pdf_file = build_pdf(markdown_file, out_dir / f"{lang}.pdf", args) logging.info(f"{lang}: building epub...") epub_file = build_epub(markdown_file, out_dir / f"{lang}.epub") - + shutil.copy(pdf_file, f"ebook/vulkan_tutorial_{lang}.pdf") shutil.copy(epub_file, f"ebook/vulkan_tutorial_{lang}.epub") diff --git a/make_parser.py b/make_parser.py new file mode 100644 index 00000000..12e10a2f --- /dev/null +++ b/make_parser.py @@ -0,0 +1,37 @@ +import argparse + +def make_parser() -> argparse.ArgumentParser: + parser = argparse.ArgumentParser( + description="Build the pdf and epub files of the Vulkan Tutorial." + ) + + parser.add_argument( + "--geometry:left", + type=str, + required=False, + default="", + help="Specify left margin space as a string. Example: 2cm.", + ) + parser.add_argument( + "--geometry:right", + type=str, + required=False, + default="", + help="Specify right margin space as a string. Example: 2cm.", + ) + parser.add_argument( + "--geometry:top", + type=str, + required=False, + default="", + help="Specify top margin space as a string. Example: 2cm.", + ) + parser.add_argument( + "--geometry:bottom", + type=str, + required=False, + default="", + help="Specify bottom margin space as a string. Example: 2cm.", + ) + + return parser From c7ec526bd3c3e20854409b21962d656a60aedc2b Mon Sep 17 00:00:00 2001 From: Alexander Overvoorde Date: Sun, 21 Sep 2025 17:06:20 +0000 Subject: [PATCH 2/7] Update default PDF margins (fixes #396) --- .gitignore | 219 +++++++++++++++++++++++++++++++++++++++++++++++- .python-version | 1 + make_parser.py | 8 +- pyproject.toml | 7 ++ uv.lock | 8 ++ 5 files changed, 238 insertions(+), 5 deletions(-) create mode 100644 .python-version create mode 100644 pyproject.toml create mode 100644 uv.lock diff --git a/.gitignore b/.gitignore index ae5f6c81..410b95ad 100644 --- a/.gitignore +++ b/.gitignore @@ -7,4 +7,221 @@ ads.txt build_ebook.log temp_ebook.md ebook/*.pdf -ebook/*.epub \ No newline at end of file +ebook/*.epub + +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[codz] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py.cover +.hypothesis/ +.pytest_cache/ +cover/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py +db.sqlite3 +db.sqlite3-journal + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +.pybuilder/ +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# IPython +profile_default/ +ipython_config.py + +# pyenv +# For a library or package, you might want to ignore these files since the code is +# intended to run in multiple environments; otherwise, check them in: +# .python-version + +# pipenv +# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. +# However, in case of collaboration, if having platform-specific dependencies or dependencies +# having no cross-platform support, pipenv may install dependencies that don't work, or not +# install all needed dependencies. +# Pipfile.lock + +# UV +# Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control. +# This is especially recommended for binary packages to ensure reproducibility, and is more +# commonly ignored for libraries. +# uv.lock + +# poetry +# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control. +# This is especially recommended for binary packages to ensure reproducibility, and is more +# commonly ignored for libraries. +# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control +# poetry.lock +# poetry.toml + +# pdm +# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control. +# pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python. +# https://pdm-project.org/en/latest/usage/project/#working-with-version-control +# pdm.lock +# pdm.toml +.pdm-python +.pdm-build/ + +# pixi +# Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control. +# pixi.lock +# Pixi creates a virtual environment in the .pixi directory, just like venv module creates one +# in the .venv directory. It is recommended not to include this directory in version control. +.pixi + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm +__pypackages__/ + +# Celery stuff +celerybeat-schedule +celerybeat.pid + +# Redis +*.rdb +*.aof +*.pid + +# RabbitMQ +mnesia/ +rabbitmq/ +rabbitmq-data/ + +# ActiveMQ +activemq-data/ + +# SageMath parsed files +*.sage.py + +# Environments +.env +.envrc +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json + +# Pyre type checker +.pyre/ + +# pytype static type analyzer +.pytype/ + +# Cython debug symbols +cython_debug/ + +# PyCharm +# JetBrains specific template is maintained in a separate JetBrains.gitignore that can +# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore +# and can be added to the global gitignore or merged into this file. For a more nuclear +# option (not recommended) you can uncomment the following to ignore the entire idea folder. +# .idea/ + +# Abstra +# Abstra is an AI-powered process automation framework. +# Ignore directories containing user credentials, local state, and settings. +# Learn more at https://abstra.io/docs +.abstra/ + +# Visual Studio Code +# Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore +# that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore +# and can be added to the global gitignore or merged into this file. However, if you prefer, +# you could uncomment the following to ignore the entire vscode folder +# .vscode/ + +# Ruff stuff: +.ruff_cache/ + +# PyPI configuration file +.pypirc + +# Marimo +marimo/_static/ +marimo/_lsp/ +__marimo__/ + +# Streamlit +.streamlit/secrets.toml diff --git a/.python-version b/.python-version new file mode 100644 index 00000000..24ee5b1b --- /dev/null +++ b/.python-version @@ -0,0 +1 @@ +3.13 diff --git a/make_parser.py b/make_parser.py index 12e10a2f..8d0c5b5b 100644 --- a/make_parser.py +++ b/make_parser.py @@ -9,28 +9,28 @@ def make_parser() -> argparse.ArgumentParser: "--geometry:left", type=str, required=False, - default="", + default="2.5cm", help="Specify left margin space as a string. Example: 2cm.", ) parser.add_argument( "--geometry:right", type=str, required=False, - default="", + default="2.5cm", help="Specify right margin space as a string. Example: 2cm.", ) parser.add_argument( "--geometry:top", type=str, required=False, - default="", + default="2.5cm", help="Specify top margin space as a string. Example: 2cm.", ) parser.add_argument( "--geometry:bottom", type=str, required=False, - default="", + default="2.5cm", help="Specify bottom margin space as a string. Example: 2cm.", ) diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 00000000..7749678c --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,7 @@ +[project] +name = "vulkantutorial" +version = "0.1.0" +description = "Add your description here" +readme = "README.md" +requires-python = "~=3.13.0" +dependencies = [] diff --git a/uv.lock b/uv.lock new file mode 100644 index 00000000..84d6b942 --- /dev/null +++ b/uv.lock @@ -0,0 +1,8 @@ +version = 1 +revision = 3 +requires-python = "==3.13.*" + +[[package]] +name = "vulkantutorial" +version = "0.1.0" +source = { virtual = "." } From 3e78cbe874396341af8554768df03f3db34566db Mon Sep 17 00:00:00 2001 From: ladysadie <144490006+ladysadie@users.noreply.github.com> Date: Sun, 21 Sep 2025 10:11:09 -0700 Subject: [PATCH 3/7] Add a code block for the GLFW window pointer. (#413) Almost all of the code listed in this chapter uses a c++ code block. The block for the 'GLFWWindow* window' was missing. --- en/03_Drawing_a_triangle/00_Setup/00_Base_code.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/en/03_Drawing_a_triangle/00_Setup/00_Base_code.md b/en/03_Drawing_a_triangle/00_Setup/00_Base_code.md index df26c6ac..e5b0e0b3 100644 --- a/en/03_Drawing_a_triangle/00_Setup/00_Base_code.md +++ b/en/03_Drawing_a_triangle/00_Setup/00_Base_code.md @@ -145,8 +145,14 @@ disable it for now with another window hint call: glfwWindowHint(GLFW_RESIZABLE, GLFW_FALSE); ``` -All that's left now is creating the actual window. Add a `GLFWwindow* window;` -private class member to store a reference to it and initialize the window with: +All that's left now is creating the actual window. Add a private class member to store a reference to it: + +```c++ +private: +GLFWwindow* window; +``` + +Initialize the window with ```c++ window = glfwCreateWindow(800, 600, "Vulkan", nullptr, nullptr); From 06165e5245fd0a22f7fa7deebeb2da1577cc04bd Mon Sep 17 00:00:00 2001 From: ladysadie <144490006+ladysadie@users.noreply.github.com> Date: Sun, 21 Sep 2025 10:11:34 -0700 Subject: [PATCH 4/7] Fix typo in the html generation instructions. (#412) * Fix typo in the html generation instructions. * Add a code block for the GLFW window pointer. Almost all of the code listed in this chapter uses a c++ code block. The block for the 'GLFWWindow* window' was missing. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index fcbb3775..b14b7f26 100644 --- a/README.md +++ b/README.md @@ -124,7 +124,7 @@ necessary. Now with the above done, we can generate the static files. Asuming the daux.io and VulkanTutorial directories are next to each other, go into the `daux.io` directory and run a command similar to: -`php generate -s ../VulkanTutorial -d ../VulkanTutorial/out`. +`daux generate -s ../VulkanTutorial -d ../VulkanTutorial/out`. `-s` tells it where to find the documentation, while `-d` tells it where to put the generated files. From ab3b8400cf163894c8e3174d22af90597dbe8deb Mon Sep 17 00:00:00 2001 From: Alexander Overvoorde Date: Sun, 25 Jan 2026 17:19:27 +0000 Subject: [PATCH 5/7] Add notice about age of the tutorial (fixes #416) --- en/00_Introduction.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/en/00_Introduction.md b/en/00_Introduction.md index e56799e9..f2741b0a 100644 --- a/en/00_Introduction.md +++ b/en/00_Introduction.md @@ -1,3 +1,12 @@ +>## Read before following this tutorial +> +>This tutorial was written shortly after Vulkan was initially released, back in +>2016. A lot has changed since then and this tutorial no longer reflects the best +>way to use Vulkan today. +> +>Instead of reading this website, I recommend to follow the guide or one of the +>tutorials linked here: https://vulkan.org/learn + ## About This tutorial will teach you the basics of using the [Vulkan](https://www.khronos.org/vulkan/) From 8951d937b95331f70b82f03f68194318ef2d4532 Mon Sep 17 00:00:00 2001 From: Alexander Overvoorde Date: Sun, 25 Jan 2026 17:29:14 +0000 Subject: [PATCH 6/7] Fix link --- en/00_Introduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/00_Introduction.md b/en/00_Introduction.md index f2741b0a..bbcb39ac 100644 --- a/en/00_Introduction.md +++ b/en/00_Introduction.md @@ -5,7 +5,7 @@ >way to use Vulkan today. > >Instead of reading this website, I recommend to follow the guide or one of the ->tutorials linked here: https://vulkan.org/learn +>tutorials linked here: [https://vulkan.org/learn] ## About From 945583820d5e6286879d08bb87cb245c56d880a6 Mon Sep 17 00:00:00 2001 From: Alexander Overvoorde Date: Sun, 25 Jan 2026 17:29:46 +0000 Subject: [PATCH 7/7] Fix link even more --- en/00_Introduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/00_Introduction.md b/en/00_Introduction.md index bbcb39ac..1d14c781 100644 --- a/en/00_Introduction.md +++ b/en/00_Introduction.md @@ -5,7 +5,7 @@ >way to use Vulkan today. > >Instead of reading this website, I recommend to follow the guide or one of the ->tutorials linked here: [https://vulkan.org/learn] +>tutorials linked here: [https://vulkan.org/learn](https://vulkan.org/learn) ## About