Merge pull request #1506 from freedoom/manual-cover

Add build targets for printable manual

.github/workflows/make.yml

@@ -18,7 +18,8 @@ jobs:
     - name: Install Prerequisites
       run: |
         sudo apt update
-        sudo apt install python3-pil asciidoc unzip zip ruby dos2unix
+        sudo apt install python3-pil asciidoc unzip zip ruby dos2unix \
+                         inkscape
         sudo gem install asciidoctor-pdf --pre
     - name: Install Deutex
       run: |
@@ -43,6 +44,10 @@ jobs:
           export VERSION=${VERSION:1}
         fi
         echo "VERSION=$VERSION" >> $GITHUB_OUTPUT
+    - name: Make print manual PDFs
+      run: |
+        cd manual
+        make print
     - name: Upload Freedoom
       uses: actions/upload-artifact@v4
       with:

.gitignore

@@ -76,4 +76,6 @@ doom.gpl
 
 /lumps/textures/phase2/
 
+/manual/cover/cover-*.svg
+
 /wads/

manual/Makefile

@@ -8,14 +8,40 @@
 #                 es    Spanish
 #                 fr    French
 
-ASCIIDOCTOR_FLAGS = -a pdf-page-size=A5
+BUILD_VERSION=$(shell git describe --abbrev=8 --dirty 2>/dev/null)
+ASCIIDOCTOR_FLAGS = -a pdf-page-size=A5 -a build-version=$(BUILD_VERSION)
 MANUAL_ADOC_FILES=$(wildcard freedoom-manual-??.adoc)
 MANUAL_PDF_FILES=$(subst .adoc,.pdf,$(MANUAL_ADOC_FILES))
+PRINT_PDF_FILES=$(subst .adoc,-print.pdf,$(MANUAL_ADOC_FILES))
+COVER_PDF_FILES=cover-en.pdf cover-es.pdf cover-fr.pdf
+COVER_SVG_FILES=$(patsubst %.pdf,cover/%.svg,$(COVER_PDF_FILES))
 
 all: $(MANUAL_PDF_FILES)
 
+# `make print` builds all the PDFs for printed versions of the manuals.
+print: covers $(PRINT_PDF_FILES)
+
+# We only build the cover PDFs if the user explicitly runs `make covers`;
+# this is because it requires Inkscape and we don't want it as a build
+# dependency. Most users won't ever need these, we only use them when we're
+# uploading the PDF files to print physical manuals.
+covers: $(COVER_PDF_FILES)
+
 freedoom-manual-%.pdf: freedoom-manual-%.adoc
 	-asciidoctor-pdf $(ASCIIDOCTOR_FLAGS) $< -o $@
 
+freedoom-manual-%-print.pdf: freedoom-manual-%.adoc
+	-asciidoctor-pdf $(ASCIIDOCTOR_FLAGS) -a media=print $< -o $@
+
+cover/cover-%.svg: cover/cover-%.sed cover/template.svg
+	sed -f $< < cover/template.svg > $@
+
+cover-%.pdf: cover/cover-%.svg cover/serpentipede.png cover/minigunner.png
+	inkscape -o $@ $<
+
 clean:
-	$(RM) $(MANUAL_PDF_FILES)
+	$(RM) $(MANUAL_PDF_FILES) $(COVER_PDF_FILES) $(COVER_SVG_FILES) \
+	      $(PRINT_PDF_FILES)
+
+# Inkscape can't process files in parallel, it has to be sequential:
+.NOTPARALLEL: covers

manual/cover/cover-en.sed

@@ -0,0 +1,13 @@
+s/__BACK_TEXT__/\
+Freedoom is an open-content First-Person\
+Shooter (FPS) game that is Free and Open\
+Source Software. Developed by volunteers\
+since 2001, Freedoom is made available\
+under the 3-clause BSD license.\
+\
+This manual gives a wealth of information,\
+including how to play the game, strategy,\
+tips and tricks and more./
+
+s/__FRONT_TITLE__/Game Manual/
+s/__SPINE_TITLE__/Freedoom Manual/

manual/cover/cover-es.sed

@@ -0,0 +1,14 @@
+s/__BACK_TEXT__/\
+Freedoom es un videojuego de disparos de\
+primera persona desarrollado por voluntarios\
+desde 2001 y disponible a través de la\
+licencia BSD modificada (de 3 clausuras)\
+permitiendo el software libre, y abierto.\
+\
+Este manual ofrece gran información sobre\
+como jugar, estrategias qué puedes realizar,\
+consejos y trucos qué tomar en cuenta, y\
+mucho más./
+
+s/__FRONT_TITLE__/Manual del Juego/
+s/__SPINE_TITLE__/Manual de Freedoom/

manual/cover/cover-fr.sed

@@ -0,0 +1,12 @@
+s/__BACK_TEXT__/\
+Freedoom est un jeu de tir à la première\
+personne libre et open source. Développé\
+par des bénévoles depuis 2001, Freedoom\
+est disponible sous licence BSD-3-Clause.\
+\
+Ce manuel contient des informations sur le\
+jeu, un guide de stratégie, des trucs et\
+astuces, et bien plus encore./
+
+s/__FRONT_TITLE__/Manuel du Jeu/
+s/__SPINE_TITLE__/Manuel Freedoom/

manual/freedoom-manual-en.adoc

@@ -1,13 +1,54 @@
 = Freedoom Manual
 // SPDX-License-Identifier: BSD-3-Clause
-:toc:
+:toc: macro
 :toc-title:
+:showtitle!:
+:build-version: (unknown)
+
+// This is the title page; it looks weird in Asciidoc but makes more
+// sense in the PDF output.
+
+{empty} +
+{empty} +
+{empty} +
+{empty} +
+{empty} +
+{empty} +
+
+image::images/freedoom-logo.svg[Freedoom Logo,align="center",width=500,pdfwidth=50vw]
+[.text-center]
+*Game Manual*
+
+
+<<<
+
+{empty} +
+{empty} +
+
+Copyright © 2001-2025 Contributors to the Freedoom project.
+This manual is licensed under the 3-clause BSD license.
+
+This is the English version of the Freedoom manual. Translations into other
+languages can be found on the Freedoom website.
+
+This is version {build-version} of the manual.
+
+<<<
+
+// Note this is not a heading, so the ToC does not appear in itself.
+[big]*Table of Contents*
+
+toc::[]
+
+<<<
+
+== Introduction
 
 image::../graphics/titlepic/titlepic.png[Freedoom Title Image,align="center",width=380,pdfwidth=50vw]
 
 Welcome to Freedoom, a complete game that is
-https://www.gnu.org/philosophy/free-sw.html[free]
+https://www.gnu.org/philosophy/free-sw.html[free,role=bare]
-and https://opensource.org/osd/[open source software].
+and https://opensource.org/osd/[open source software,role=bare].
 Freedoom is made available under the <<licence,modified BSD license>>, meaning that
 anyone is free to share it, modify it and reuse parts of it.
 
@@ -841,7 +882,7 @@ would depend on the company supplying them their paints.
 For over 30 years now, the Doom modding community has produced thousands upon
 thousands of levels, mods and even entirely new games built upon the original
 Doom games. These are works of art and ought to be recognised as such.
-https://www.youtube.com/watch?v=KxYND6K6u8w[Doom is an art scene].
+https://www.youtube.com/watch?v=KxYND6K6u8w[Doom is an art scene,role=bare].
 The raw material these works of art are made from is not paint or ink, but the
 original game itself -- endlessly modified, reused and remixed into new
 variations.
@@ -863,12 +904,12 @@ something that Freedoom can help to provide.
 
 == Contributing to Freedoom ==
 
-Freedoom is a https://www.gnu.org/philosophy/free-sw.html[free content]
+Freedoom is a
-project contributed to by many users around the world. It is available as both
+https://www.gnu.org/philosophy/free-sw.html[free content,role=bare] project
-free in cost (free as in free beer) and in modification and redistribution
+contributed to by many users around the world. It is available as both free in
-rights (free as in free speech) to end users, provided that the original
+cost (free as in free beer) and in modification and redistribution rights (free
-software license is included and/or viewable by users of modified or
+as in free speech) to end users, provided that the original software license is
-redistributed versions.
+included and/or viewable by users of modified or redistributed versions.
 
 If you’d like to contribute to the Freedoom project, please check out
 the following community hubs:
@@ -894,16 +935,16 @@ https://guides.github.com/activities/forking/
 [[reusing]]
 == Reusing portions of Freedoom ==
 
-Since https://freedoom.github.io/about.html[Freedoom is free], some other
+Since https://freedoom.github.io/about.html[Freedoom is free,role=bare], some
-projects have used Freedoom’s assets.  We think this is a great use of the
+other projects have used Freedoom’s assets.  We think this is a great use of
-project and should be encouraged. If you use portions of Freedoom in your
+the project and should be encouraged. If you use portions of Freedoom in your
 project, please let us know by filing an issue or pull request on
 Freedoom’s website project page at https://github.com/freedoom/freedoom.github.io.
 
 [[licence]]
 === BSD 3-Clause copyright licence
 
-Copyright © 2001-2024
+Copyright © 2001-2025
 Contributors to the Freedoom project.  All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

manual/freedoom-manual-es.adoc

@@ -1,13 +1,49 @@
 = Manual de Freedoom
 // SPDX-License-Identifier: BSD-3-Clause
-:toc:
+:toc: macro
 :toc-title:
+:showtitle!:
+:build-version: (desconocida)
+
+// This is the title page; it looks weird in Asciidoc but makes more
+// sense in the PDF output.
+
+{empty} +
+{empty} +
+{empty} +
+{empty} +
+{empty} +
+{empty} +
+
+image::images/freedoom-logo.svg[Freedoom Logo,align="center",width=500,pdfwidth=70vw]
+[.text-center]
+*Manual del Juego*
+
+<<<
+
+{empty} +
+{empty} +
+
+Copyright © 2001-2025 Contributors to the Freedoom project.
+Este manual está licenciado bajo la licencia BSD de 3 cláusulas.
+
+Esta es la versión {build-version} del manual.
+
+<<<
+
+[big]*Sumario*
+
+toc::[]
+
+<<<
+
+== Introducción
 
 image::../graphics/titlepic/titlepic.png[Freedoom Title Image,align="center",width=380,pdfwidth=50vw]
 
 Bienvenido a Freedoom, un juego completo que es software
-https://www.gnu.org/philosophy/free-sw.html[libre]
+https://www.gnu.org/philosophy/free-sw.html[libre,role=bare]
-y de https://opensource.org/osd/[código abierto].
+y de https://opensource.org/osd/[código abierto,role=bare].
 Freedoom esta disponible bajo una <<licence,licencia BSD modificada>>, lo que significa
 que cualquiera es libre de compartirlo, modificarlo y reutilizar partes de el.
 
@@ -864,7 +900,7 @@ Por más de 30 años, la comunidad de modding de Doom ha producido miles y miles
 de niveles, mods e incluso juegos completamente nuevos hechos en base a los
 juegos de Doom originales. Estos son obras de artes y deberían ser reconocidos
 como tales.
-https://www.youtube.com/watch?v=KxYND6K6u8w[Doom es una escena artística].
+https://www.youtube.com/watch?v=KxYND6K6u8w[Doom es una escena artística,role=bare].
 La materia prima de estas obras de arte no es pintura ni tinta, sino el juego
 original -- modificado, reutilizado y reversionado sin cesar para dar nuevas
 variaciones.
@@ -887,10 +923,10 @@ y reutilizar, esperamos que eso sea algo que Freedoom pueda otorgar.
 == Contribuir a Freedoom
 
 Freedoom es un proyecto de
-https://www.gnu.org/philosophy/free-sw.es.html[contenido libre] al que
+https://www.gnu.org/philosophy/free-sw.es.html[contenido libre,role=bare] al
-contribuyen muchos usuarios de todo el mundo. Está disponible tanto como sin
+que contribuyen muchos usuarios de todo el mundo. Está disponible tanto como
-costo (gratis) y en derechos de modificación y redistribución (libre como en
+sin costo (gratis) y en derechos de modificación y redistribución (libre como
-libertad de expresión) para los usuarios finales, siempre que la licencia de
+en libertad de expresión) para los usuarios finales, siempre que la licencia de
 software original esté incluida y/o sea visible para los usuarios del software
 modificado o versiones redistribuidas.
 
@@ -915,17 +951,18 @@ https://guides.github.com/activities/forking/
 [[reusing]]
 == Reusar partes de Freedoom
 
-Dado que https://freedoom.github.io/about.html[Freedoom es libre], algunos
+Dado que https://freedoom.github.io/about.html[Freedoom es libre,role=bare],
-otros proyectos han utilizado los materiales de Freedoom. Creemos que este es
+algunos otros proyectos han utilizado los materiales de Freedoom. Creemos que
-un gran uso del proyecto y debe fomentarse. Si tu usas partes de Freedoom en tu
+este es un gran uso del proyecto y debe fomentarse. Si tu usas partes de
-proyecto, puedes informarnos presentando una solicitud a
+Freedoom en tu proyecto, puedes informarnos presentando una solicitud a
-la página web del proyecto Freedoom en https://github.com/freedoom/freedoom.github.io.
+la página web del proyecto Freedoom en
+https://github.com/freedoom/freedoom.github.io.
 
 
 [[licence]]
 === Licencia BSD modificada (inglés)
 
-Copyright © 2001-2024
+Copyright © 2001-2025
 Contributors to the Freedoom project.  All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

manual/freedoom-manual-fr.adoc

@@ -1,13 +1,46 @@
 = Manuel Freedoom
 // SPDX-License-Identifier: BSD-3-Clause
-:toc:
+:toc: macro
 :toc-title:
+:showtitle!:
+:build-version: (inconnue)
+
+// This is the title page; it looks weird in Asciidoc but makes more
+// sense in the PDF output.
+
+{empty} +
+{empty} +
+{empty} +
+{empty} +
+{empty} +
+{empty} +
+
+image::images/freedoom-logo.svg[Freedoom Logo,align="center",width=500,pdfwidth=70vw]
+[.text-center]
+*Manuel du Jeu*
+
+<<<
+
+Copyright © 2001-2025 Contributors to the Freedoom project.
+Ce manuel est sous licence BSD-3-Clause.
+
+Il s'agit de la version {build-version} du manuel.
+
+<<<
+
+[big]*Sommaire*
+
+toc::[]
+
+<<<
+
+== Introduction
 
 image::../graphics/titlepic/titlepic.png[Freedoom Title Image,align="center",width=380,pdfwidth=50vw]
 
 Bienvenue sur Freedoom, un jeu complet qui est
-https://www.gnu.org/philosophy/free-sw.html[libre]
+https://www.gnu.org/philosophy/free-sw.html[libre,role=bare]
-et https://opensource.org/osd/[open source].
+et https://opensource.org/osd/[open source,role=bare].
 Freedoom est disponible sous <<licence, la licence BSD Modifiée>>, permettant
 n'importe qui de partager, de modifier et de réutiliser des parties du jeu.
 
@@ -617,7 +650,7 @@ Le mot « free » a deux significations différentes en Anglais. On dit « fre
 
 Imaginez un monde où les artistes ne peuvent qu'acheter de la peinture d'une seule compagnie. Un tel monopole signifierait que la peinture couterait plus chères, mais le prix ne serait pas le problème principal. Le plus gros problème serait le pouvoir qu'il accorderait à cette compagnie. La liberté de ces artistes de s'exprimer dépendrait de la compagnie qui leur fournit leurs peintures.
 
-Depuis plus de 30 ans, la communauté de modders Doom a produit des milliers de niveaux, mods et même des nouveaux jeux construits à partir des jeux Doom originaux. Ce sont des œuvres d'art qui doivent être reconnues comme telles. https://www.youtube.com/watch?v=KxYND6K6u8w[Doom est une scène artistique]. La matière première à partir de laquelle ces œuvres d'art sont fabriquées n'est ni de la peinture ou de l’encre, mais le jeu original lui-même -- sans cesse modifié, réutilisé et remixé en de nouvelles variations.
+Depuis plus de 30 ans, la communauté de modders Doom a produit des milliers de niveaux, mods et même des nouveaux jeux construits à partir des jeux Doom originaux. Ce sont des œuvres d'art qui doivent être reconnues comme telles. https://www.youtube.com/watch?v=KxYND6K6u8w[Doom est une scène artistique,role=bare]. La matière première à partir de laquelle ces œuvres d'art sont fabriquées n'est ni de la peinture ou de l’encre, mais le jeu original lui-même -- sans cesse modifié, réutilisé et remixé en de nouvelles variations.
 
 Les auteurs de Doom, id Software, ont historiquement été très généreux envers la communauté Doom. Dès la sortie du jeu, ils ont fait de leur mieux pour partager les détails techniques avec les fans, et quelques années après ils ont publié le code source de Doom sous une licence libre -- quelque chose qui était inconnu dans l'industrie du jeu vidéo à l'époque et qui devrait être félicité. Mais malgré cette bienveillance, ils ont toujours occupé une position de pouvoir. Aujourd'hui, au lieu d'être un petit studio indépendant, eux et la franchise Doom appartiennent à une grande multinationale.
 
@@ -625,7 +658,7 @@ Tout le monde mérite de pouvoir apprécier la merveille qu'est Doom et de parti
 
 == Contribuer à Freedoom ==
 
-Freedoom est un projet au https://www.gnu.org/philosophy/free-sw.html[contenu libre] avec de nombreux contributeurs venant du monde entier. Il est disponible à la fois "free" ^1^ en coût ("free" ^1^ comme une bière gratuite) et en droit de modification et de redistribution ("free" ^1^ comme la liberté d'expression) aux utilisateurs finaux, à condition que la licence originale soit incluse et/ou visible aux utilisateurs de versions modifiées ou redistribuées. 
+Freedoom est un projet au https://www.gnu.org/philosophy/free-sw.html[contenu libre,role=bare] avec de nombreux contributeurs venant du monde entier. Il est disponible à la fois "free" ^1^ en coût ("free" ^1^ comme une bière gratuite) et en droit de modification et de redistribution ("free" ^1^ comme la liberté d'expression) aux utilisateurs finaux, à condition que la licence originale soit incluse et/ou visible aux utilisateurs de versions modifiées ou redistribuées. 
 
 Si vous souhaitez contribuer au projet Freedoom, veuillez consulter
 les hubs communautaires suivants:
@@ -653,7 +686,7 @@ https://guides.github.com/activities/forking/
 [[reusing]]
 == Réutilisation de portions de Freedoom ==
 
-Puisque https://freedoom.github.io/about.html[Freedoom est libre], d'autres projets ont utilisé des éléments de Freedom.  Nous pensons que c'est une excellente utilisation du projet et nous l'encourageons. Si vous utilisez des portions de Freedoom dans votre projet, veuillez nous informer en formulant une « issue » ou un « pull request » sur la page du projet Freedoom
+Puisque https://freedoom.github.io/about.html[Freedoom est libre,role=bare], d'autres projets ont utilisé des éléments de Freedom.  Nous pensons que c'est une excellente utilisation du projet et nous l'encourageons. Si vous utilisez des portions de Freedoom dans votre projet, veuillez nous informer en formulant une « issue » ou un « pull request » sur la page du projet Freedoom
 https://github.com/freedoom/freedoom .
 
 <<<
@@ -661,7 +694,7 @@ https://github.com/freedoom/freedoom .
 [[licence]]
 === BSD 3-Clause copyright licence
 
-Copyright © 2001-2024
+Copyright © 2001-2025
 Contributors to the Freedoom project.  All rights reserved.
 
 Redistribution and use in source and binary forms, with or without