Add support for PDF output

.github/workflows/main.yml

@@ -0,0 +1,46 @@
+---
+name: Generate PDF using Pandoc
+
+# Controls when the workflow will run
+on:
+  # Triggers the workflow on push or pull request events but only for the master branch
+  push:
+    branches: [ master ]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# A workflow run is made up of one or more jobs that can run sequentially or in parallel
+jobs:
+  # This workflow contains a single job called "create_pdf"
+  create_pdf:
+    # The type of runner that the job will run on
+    runs-on: ubuntu-latest
+
+    # Pandoc Docker image v3.1.1.0
+    container:
+      image: pandoc/latex:3.1.1.0
+
+    # Steps represent a sequence of tasks that will be executed as part of the job
+    steps:
+      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
+      - uses: actions/checkout@v4
+
+      # Run the PDF creation script in the container
+      - uses: docker://pandoc/latex:3.1.1.0
+        with:
+          entrypoint: './pandoc-docker.sh'
+
+      # Create an output with the shortened version of the commit SHA
+      - id: short_sha
+        env:
+          GITHUB_SHA: ${{ github.sha }}
+        run: echo "short_sha=${GITHUB_SHA::7}" >> $GITHUB_OUTPUT
+
+      # Create a release with the PDFs as assets and the shortened SHA as the tag name
+      - uses: softprops/action-gh-release@v2
+        with:
+          tag_name: v${{ steps.short_sha.outputs.short_sha }}
+          draft: false
+          files: |
+            *.pdf

.gitignore

@@ -1 +1,2 @@
+*.pdf
 book

README.md

@@ -0,0 +1,35 @@
+# WAYLAND BOOK
+
+This repository is a clone of the repository for [Wayland Book](https://wayland-book.com/), located at
+[~sircmpwn/wayland-book](https://git.sr.ht/~sircmpwn/wayland-book).
+
+The original author of this work is [Drew DeVault](https://github.com/ddevault).
+
+## GENERATING A PDF
+
+Every commit or push to the master branch will generate a PDF that can then be
+downloaded under the Releases tab. There are two local scripts available if
+that is preferred as well.
+
+The PDF can also be generated on a local client by cloning this repository and
+running `pandoc.sh` in a shell, assuming the dependencies below are installed
+locally and accessible.
+
+The `pandoc-docker.sh` script can be used with the [pandoc/latex Docker images](https://hub.docker.com/r/pandoc/latex)
+to similarly generate the same output PDF as the one in the Releases tab.
+
+## DEPENDENCIES
+
+The local execution of the script depends on two packages being installed:
+
+- pandoc
+- tex
+
+Check with your distribution for how to install those packages.
+
+## CONTRIBUTING
+
+All issues to report or contributions to be made should be done upstream at the
+source content repository linked above. This repository will then be rebased so
+that a new PDF can be generated with the changes. The only exception would be
+the case where something specific to the PDF generation should be addressed.

deeplists.tex

@@ -0,0 +1,24 @@
+   \usepackage{enumitem}
+   \setlistdepth{9}
+
+   \setlist[itemize,1]{label=$\bullet$}
+   \setlist[itemize,2]{label=$\bullet$}
+   \setlist[itemize,3]{label=$\bullet$}
+   \setlist[itemize,4]{label=$\bullet$}
+   \setlist[itemize,5]{label=$\bullet$}
+   \setlist[itemize,6]{label=$\bullet$}
+   \setlist[itemize,7]{label=$\bullet$}
+   \setlist[itemize,8]{label=$\bullet$}
+   \setlist[itemize,9]{label=$\bullet$}
+   \renewlist{itemize}{itemize}{9}
+
+   \setlist[enumerate,1]{label=$\arabic*.$}
+   \setlist[enumerate,2]{label=$\alph*.$}
+   \setlist[enumerate,3]{label=$\roman*.$}
+   \setlist[enumerate,4]{label=$\arabic*.$}
+   \setlist[enumerate,5]{label=$\alpha*$}
+   \setlist[enumerate,6]{label=$\roman*.$}
+   \setlist[enumerate,7]{label=$\arabic*.$}
+   \setlist[enumerate,8]{label=$\alph*.$}
+   \setlist[enumerate,9]{label=$\roman*.$}
+   \renewlist{enumerate}{enumerate}{9}

pandoc-docker.sh

@@ -0,0 +1,15 @@
+#! /bin/sh
+
+# Install dependencies for successful PDF generations
+tlmgr install ctex enumitem float koma-script titling
+
+# Generate PDFs using pandoc
+for filename in pandoc-*yaml; do
+  # Create variable for language based on filename
+  language=`echo $filename | cut -d'.' -f1 | cut -d'-' -f2-3`
+
+  # Attempt to create the PDF
+  echo "Generating ${language} PDF..."
+  pandoc -d ${filename}
+  [[ $? -eq 0 ]] && echo "Success! The ${language} PDF has been successfully created!"
+done

pandoc-en-US.yaml

@@ -0,0 +1,97 @@
+---
+metadata:
+  title: The Wayland Protocol
+  author: Drew DeVault
+  category: "License: Creative Commons Attribution 4.0 International License"
+  keywords:
+    - "display server"
+    - "wayland"
+    - "xorg"
+    - "xwayland"
+standalone: true
+variables:
+  documentclass: scrbook
+  header-includes:
+    - \usepackage{graphicx}
+    - \usepackage{titling}
+    - \newcommand{\titlesc}[1]{\textsc{#1}}
+    - \pretitle{\begin{center}\includegraphics[width=2in]{wayland-logo.png}\\\LARGE\titlesc}
+    - \posttitle{\end{center}}
+  lang: en-US
+  links-as-notes: true
+  lot: false
+  lof: false
+  margin-top: 1.27cm
+  margin-left: .635cm
+  margin-right: .635cm
+  margin-bottom: 1.27cm
+  numbersections: true
+table-of-contents: true
+toc-depth: 2
+include-in-header: deeplists.tex
+verbosity: ERROR
+pdf-engine: xelatex
+input-files:
+  - ./src/introduction.md
+  - ./src/introduction/high-level-design.md
+  - ./src/introduction/goals.md
+  - ./src/introduction/package.md
+  - ./src/protocol-design.md
+  - ./src/protocol-design/wire-protocol.md
+  - ./src/protocol-design/interfaces-reqs-events.md
+  - ./src/protocol-design/high-level.md
+  - ./src/protocol-design/design-patterns.md
+  - ./src/libwayland.md
+  - ./src/libwayland/util.md
+  - ./src/libwayland/wayland-scanner.md
+  - ./src/libwayland/proxies.md
+  - ./src/libwayland/interfaces.md
+#  - ./src/libwayland/event-loop.md
+#  - ./src/libwayland/fds.md
+  - ./src/wayland-display.md
+  - ./src/wayland-display/creation.md
+  - ./src/wayland-display/event-loop.md
+  - ./src/registry.md
+  - ./src/registry/binding.md
+  - ./src/registry/server-side.md
+  - ./src/surfaces.md
+  - ./src/surfaces/compositor.md
+  - ./src/surfaces/shared-memory.md
+  - ./src/surfaces/dmabuf.md
+  - ./src/surfaces/roles.md
+#  - ./src/surfaces/surface-roles.md
+  - ./src/xdg-shell-basics.md
+  - ./src/xdg-shell-basics/xdg-surface.md
+  - ./src/xdg-shell-basics/xdg-toplevel.md
+  - ./src/xdg-shell-basics/example-code.md
+  - ./src/surfaces-in-depth.md
+  - ./src/surfaces-in-depth/lifecycle.md
+  - ./src/surfaces-in-depth/frame-callbacks.md
+  - ./src/surfaces-in-depth/damaging-surfaces.md
+  - ./src/surfaces-in-depth/surface-regions.md
+  - ./src/surfaces-in-depth/subsurfaces.md
+  - ./src/surfaces-in-depth/hidpi.md
+  - ./src/seat.md
+  - ./src/seat/pointer.md
+  - ./src/seat/xkb.md
+  - ./src/seat/keyboard.md
+  - ./src/seat/touch.md
+  - ./src/seat/example.md
+  - ./src/xdg-shell-in-depth.md
+  - ./src/xdg-shell-in-depth/configuration.md
+  - ./src/xdg-shell-in-depth/popups.md
+  - ./src/xdg-shell-in-depth/interactive.md
+  - ./src/xdg-shell-in-depth/positioners.md
+#  - ./src/clipboard.md
+#  - ./src/clipboard/data-offers.md
+#  - ./src/clipboard/dnd.md
+#  - ./src/protocol-extensions.md
+#  - ./src/protocol-extensions/timing.md
+#  - ./src/protocol-extensions/pointer-constraints.md
+#  - ./src/protocol-extensions/clipboard.md
+#  - ./src/protocol-extensions/desktop-shell.md
+#  - ./src/protocol-extensions/misc.md
+#  - ./src/protocol-extensions/writing.md
+#  - ./src/acknowledgements.md
+output-file: wayland-book.pdf
+...

pandoc.sh

@@ -0,0 +1,31 @@
+#! /bin/bash
+
+# Generate PDFs using pandoc
+generate_pdfs() {
+  for filename in pandoc-*yaml; do
+    # Create variable for language based on filename
+    IFS=- read _ language <<< "${filename}"
+    language=${language/.yaml/}
+
+    # Attempt to create the PDF
+    echo "Generating ${language} PDF..."
+    pandoc -d "${filename}"
+    [[ $? -eq 0 ]] && echo "Success! The ${language} PDF has been successfully created!"
+  done
+}
+
+# Check if dependencies exist
+check_dependencies () {
+  for dependency in "${dependencies[@]}"
+  do
+    if ! [ -x "$(command -v ${dependency})" ]; then
+      echo "Error: $dependency is not installed." >&2
+      exit 1
+    fi
+  done
+}
+
+dependencies=("pandoc" "tex")
+
+check_dependencies
+generate_pdfs

src/clipboard/data-offers.md

@@ -1 +1 @@
-# Data offers
+## Data offers

src/clipboard/dnd.md

@@ -1 +1 @@
-# Drag & drop
+## Drag & drop

src/introduction.md

@@ -26,7 +26,7 @@ be updated later. Chapters 11 forward in large part remain to be written.
 - Add example code for interactive move, to demonstrate the use of serials
 - Prepare PDFs and EPUBs
 
-## About the book
+### About the book
 
 This work is licensed under a <a rel="license"
 href="http://creativecommons.org/licenses/by-sa/4.0/">Creative Commons
@@ -37,7 +37,7 @@ Attribution-ShareAlike 4.0 International License</a>. The source code is
 
 [source]: https://git.sr.ht/~sircmpwn/wayland-book
 
-## About the author
+### About the author
 
 <small>
   In the words of Preston Carpenter, a close collaborator of Drew's:

src/introduction/goals.md

@@ -1,4 +1,4 @@
-# Goals & target audience
+## Goals & target audience
 
 Our goal is for you to come away from this book with an understanding of the
 Wayland protocol and its high-level usage. You should have a solid understanding

src/introduction/high-level-design.md

@@ -1,4 +1,4 @@
-# High-level design
+## High-level design
 
 Your computer has *input* and *output* devices, which respectively are
 responsible for receiving information from you and displaying information to
@@ -18,7 +18,7 @@ their appropriate place on your outputs. The process of bringing together all of
 your application windows for display on an output is called *compositing* 
 — and thus we call the software which does this the *compositor*.
 
-## In practice
+### In practice
 
 There are many distinct software components in desktop ecosystem. There are
 tools like Mesa for rendering (and each of its drivers), the Linux KMS/DRM
@@ -31,7 +31,7 @@ run most applications without implicating any of this software. That being said,
 a surface-level understanding of what these pieces are and how they work is
 useful. Let's start from the bottom and work our way up.
 
-## The hardware
+### The hardware
 
 A typical computer is equipped with a few important pieces of hardware. Outside
 of the box, we have your displays, keyboard, mouse, perhaps some speakers and a
@@ -55,7 +55,7 @@ on your system. The hardware provides an interface with which it can be
 commanded to perform work, and does what it's told — regardless of who 
 tells it so. For this reason, only one component is allowed to talk to it...
 
-## The kernel
+### The kernel
 
 This responsibility falls onto the kernel. The kernel is a complex beast, so
 we'll focus on only the parts which are relevant to Wayland. Linux's job is to
@@ -74,20 +74,20 @@ modesetting, and a render node (e.g. `renderD128`), for unprivileged operations
 like rendering or video decoding. For evdev, the "device nodes" are
 `/dev/input/event*`.
 
-## Userspace
+### Userspace
 
 Now, we enter userspace. Here, applications are isolated from the hardware and
 must work via the device nodes provided by the kernel.
 
-### libdrm
+#### libdrm
 
 Most Linux interfaces have a userspace counterpart which provides a
 pleasant(ish) C API for working with these device nodes. One such library is
 libdrm, which is the userspace portion of the DRM subsystem. libdrm is used by
 Wayland compositors to do modesetting and other DRM operations, but is generally
 not used by Wayland clients directly.
 
-### Mesa
+#### Mesa
 
 Mesa is one of the most important parts of the Linux graphics stack. It
 provides, among other things, vendor-optimized implementations of OpenGL (and
@@ -96,7 +96,7 @@ abstraction on top of libdrm for allocating buffers on the GPU. Most Wayland
 compositors will use both GBM and OpenGL via Mesa, and most Wayland clients will
 use at least its OpenGL or Vulkan implementations.
 
-### libinput
+#### libinput
 
 Like libdrm abstracts the DRM subsystem, libinput provides the userspace end of
 evdev. It's responsible for receiving input events from the kernel from your
@@ -105,7 +105,7 @@ the Wayland compositor. The Wayland compositor requires special permissions to
 use the evdev files, forcing Wayland clients to go through the compositor to
 receive input events — which, for example, prevents keylogging.
 
-### (e)udev
+#### (e)udev
 
 Dealing with the appearance of new devices from the kernel, configuring
 permissions for the resulting device nodes in `/dev`, and sending word of these
@@ -114,7 +114,7 @@ onto userspace. Most systems use udev (or eudev, a fork) for this purpose. Your
 Wayland compositor uses udev to enumerate input devices and GPUs, and to receive
 notifications when new ones appear or old ones are unplugged.
 
-### xkbcommon
+#### xkbcommon
 
 XKB, short for X keyboard, is the original keyboard handling subsystem of the
 Xorg server. Several years ago, it was extracted from the Xorg tree and made
@@ -126,21 +126,21 @@ these scan codes into meaningful and generic key "symbols" — for example,
 converting `65` to `XKB_KEY_Space`. It also contains a state machine which knows
 that pressing "1" while shift is held emits "!".
 
-### pixman
+#### pixman
 
 A simple library used by clients and compositors alike for efficiently
 manipulating pixel buffers, doing math with intersecting rectangles, and
 performing other similar **pix**el **man**ipulation tasks.
 
-### libwayland
+#### libwayland
 
 libwayland the most commonly used implementation of the Wayland protocol,
 is written in C, and handles much of the low-level wire protocol. It also
 provides a tool which generates high-level code from Wayland protocol
 definitions (which are XML files). We will be discussing libwayland in detail in
 chapter 1.3, and throughout this book.
 
-### ...and all the rest.
+#### ...and all the rest.
 
 Each of the pieces mentioned so far are consistently found throughout the Linux
 desktop ecosystem. Beyond this, more components exist. Many graphical