2 files changed, 29 insertions, 7 deletions
diff --git a/docs/markdown/snippets/qt_preprocess_separate.md b/docs/markdown/snippets/qt_preprocess_separate.md
new file mode 100644
index 0000000..1035f9a
--- /dev/null
+++ b/docs/markdown/snippets/qt_preprocess_separate.md
@@ -0,0 +1,5 @@
+## Separate functions for qt preprocess
+
+`qt.preprocess` is a large, complicated function that does a lot of things,
+a new set of `compile_*` functions have been provided as well. These are
+conceptually simpler, as they do a single thing.
diff --git a/docs/markdown/snippets/qt_preprocessed_varargs_deprecated.md b/docs/markdown/snippets/qt_preprocessed_varargs_deprecated.md
index f763695..5418eb3 100644
--- a/docs/markdown/snippets/qt_preprocessed_varargs_deprecated.md
+++ b/docs/markdown/snippets/qt_preprocessed_varargs_deprecated.md
@@ -1,16 +1,33 @@
-## Qt.preprocess positional source arguments deprecated
+## Qt.preprocess source arguments deprecated
 
 The `qt.preprocess` method currently has this signature:
 `qt.preprocess(name: str | None, *srcs: str)`, this is not a nice signature
-because it's confusing, and there's a `sources` keyword argument that does
-exactly the same thing. Instead of
+because it's confusing, and there's a `sources` keyword argument as well.
+Both of these pass sources through unmodified, this is a bit of a historical
+accident, and not the way that any other module works. These have been
+deprecated, so instead of:
 ```meson
-qt.preprocess(name, list, of, sources)
+sources = qt.preprocess(
+    name,
+    list, of, sources,
+    sources : [more, sources],
+    ... # things to process,
+)
+
+executable(
+    'foo',
+    sources,
+)
 ```
 use
 ```meson
-qt.preprocess(
+processed = qt.preprocess(
     name,
-    sources : [list,  of , sources],
+    ... # thins to process
 )
-```
-\ No newline at end of file
+
+executable(
+    'foo',
+    'list', 'of', 'sources', 'more', 'sources', processed,
+)
+```