From cb4e8ada944813390aa56646a1d1ee0f7f5ae4c6 Mon Sep 17 00:00:00 2001
From: Julian Orth <ju.orth@gmail.com>
Date: Sat, 31 Jan 2026 11:09:33 +0100
Subject: [PATCH] doc: rewrite the book foreword

Signed-off-by: Julian Orth <ju.orth@gmail.com>
---
 doc/book/src/Foreword.md | 60 +++++++++++++++++++++++++++++++++++++---
 1 file changed, 56 insertions(+), 4 deletions(-)

diff --git a/doc/book/src/Foreword.md b/doc/book/src/Foreword.md
index 468b1654..f1b06625 100644
--- a/doc/book/src/Foreword.md
+++ b/doc/book/src/Foreword.md
@@ -1,15 +1,67 @@
+<img style="display: block; margin: auto;" src="images/wayland.png">
+
 # Preface
 
-This document describes the (i) Wayland architecture, (ii) Wayland model of
-operation and (iii) its library API. Also, the Wayland protocol specification is
-shown in the Appendix. This document is aimed primarily at Wayland developers
-and those looking to program with it; it does not cover application development.
+This document describes the Wayland architecture and Wayland model of operation.
+This document is aimed primarily at Wayland developers and those looking to
+program with it; it does not cover application development.
 
 There have been many contributors to this document and since this is only the
 first edition many errors are expected to be found. We appreciate corrections.
 
 Yours, the Wayland open-source community November 2012
 
+## Protocol Documentation
+
+This document does not describe the semantics of individual messages sent
+between compositors and clients. Consult the following documents to learn about
+concrete Wayland interfaces, requests, and events.
+
+- [wayland.xml] - The official documentation of the core protocol.
+- [wayland-protocols] - Standardized Wayland extension protocols.
+- [wayland.app] - A community-maintained website that renders these protocols,
+  and many more, as easily accessible HTML pages.
+
+[wayland.xml]: https://gitlab.freedesktop.org/wayland/wayland/-/blob/main/protocol/wayland.xml
+[wayland-protocols]: https://gitlab.freedesktop.org/wayland/wayland-protocols
+[wayland.app]: https://wayland.app
+
+## About the Book
+
+This book is written in markdown and converted to HTML using
+[mdbook](https://rust-lang.github.io/mdBook).
+
+It supports the [CommonMark](https://commonmark.org/) dialect of markdown plus a number of
+widely supported extensions:
+
+- `~~strikethrough~~`
+- ```markdown
+  footnotes[^note]
+  
+  [^note]: text
+  ```
+- ```markdown
+  | Tables | Header2 |
+  |--------|---------|
+  | abc    | def     |
+  ```
+- ```markdown
+  - [x] Task lists
+  - [ ] Incomplete task
+  ```
+- ```markdown
+  definition lists
+    : This is the definition of a
+      definition list
+  ```
+- ```markdown
+  > [!NOTE]
+  > Admonitions
+  ```
+  
+The full list of extensions is documented
+[here](https://rust-lang.github.io/mdBook/format/markdown.html#extensions).
+
 ## Copyright
 
 Copyright © 2012 Kristian Høgsberg