From 69b94145d32e67c9c2187caab183f6ee8680064c Mon Sep 17 00:00:00 2001
From: Sam Lantinga <[EMAIL REDACTED]>
Date: Tue, 10 Jan 2023 07:53:38 -0800
Subject: [PATCH] Updated documentation for SDL_migration.cocci
Especially note that this can be installed and run in WSL on Windows
---
build-scripts/SDL_migration.cocci | 36 +++++++++++--------------------
1 file changed, 13 insertions(+), 23 deletions(-)
diff --git a/build-scripts/SDL_migration.cocci b/build-scripts/SDL_migration.cocci
index 24b85e8045fd..37436ebfb3fd 100644
--- a/build-scripts/SDL_migration.cocci
+++ b/build-scripts/SDL_migration.cocci
@@ -1,44 +1,34 @@
//
+// This is a coccinelle semantic patch to ease migration of your project from SDL2 to SDL3.
//
-// This is a coccinelle semantic patch (https://github.com/coccinelle/coccinelle)
-// to ease migration of your project, from SDL2 to SDL3.
+// It generates a patch that you can apply to your project to build for SDL3. It does not
+// handle conceptual API changes, but it automates API name changes and function parameter
+// transformations.
//
-// It generates a 'diff' of your SDL2 project, that you can apply
-// to build for SDL3.
-//
-//
-// install:
-// $> apt-get install coccinelle
+// To install (native Ubuntu or using WSL on Windows):
+// sudo apt install coccinelle
//
-// apply the semantic patch to generate a diff file:
-// $> spatch --sp-file path/to/SDL_migration.cocci . > your_diff.txt
+// Apply the semantic patch to generate a patch file:
+// cd path/to/your/code
+// spatch --sp-file path/to/SDL_migration.cocci . >patch.txt
//
// A few options:
// --c++=11 to parse cpp file
// --max-width 200 to increase line witdth of generated source
//
-// patch you project (make a copy before..):
-// $> patch -p1 < your_diff.txt
-//
+// Apply the patch to your project:
+// patch -p1 <patch.txt
//
//
// #############
-// What it does ?
-// - all function renaming (without parameter change) as in SDL_oldnames.h
-// - remove SDL_WINDOW_SHOWN
-// - migrate SDL_CreateRGB* and SDL_ConvertSurface* functions
-//
-// #############
-// In very short, a patch is composed of two sub-blocks, like
+// In very short, a semantic patch is composed of two sub-blocks, like
//
// @@
// declaration
// @@
// rule / transformation
//
-// So this file, is a set of many patches, mostly independant.
-// it can be incremented by inserting new patches as SDL3 api evolves.
-//
+// So this file is a set of many semantic patches, mostly independant.
// SDL_PauseAudioDevice / SDL_PlayAudioDevice