From 5deb56fc797c49b75ecb34853ac94f6fc939b964 Mon Sep 17 00:00:00 2001
From: Larpon <Larpon@users.noreply.github.com>
Date: Sun, 28 Nov 2021 16:17:04 +0100
Subject: [PATCH] docs: add `v shader` section, add help text (#12594)

---
 cmd/tools/vshader.v   |  2 +-
 cmd/v/help/shader.txt | 17 +++++++++++++++++
 doc/docs.md           | 14 ++++++++++++++
 3 files changed, 32 insertions(+), 1 deletion(-)
 create mode 100644 cmd/v/help/shader.txt

diff --git a/cmd/tools/vshader.v b/cmd/tools/vshader.v
index 768dc9b23c..8db9f16d5e 100644
--- a/cmd/tools/vshader.v
+++ b/cmd/tools/vshader.v
@@ -90,7 +90,7 @@ fn main() {
 		show_help: fp.bool('help', `h`, false, 'Show this help text.')
 		force_update: fp.bool('force-update', `u`, false, 'Force update of the sokol-shdc tool.')
 		verbose: fp.bool('verbose', `v`, false, 'Be verbose about the tools progress.')
-		slangs: fp.string_multi('slang', `l`, 'Shader dialects to generate code for. Default is all. Available: $supported_slangs')
+		slangs: fp.string_multi('slang', `l`, 'Shader dialects to generate code for. Default is all.\n                            Available dialects: $supported_slangs')
 	}
 	if opt.show_help {
 		println(fp.usage())
diff --git a/cmd/v/help/shader.txt b/cmd/v/help/shader.txt
new file mode 100644
index 0000000000..a479ab8226
--- /dev/null
+++ b/cmd/v/help/shader.txt
@@ -0,0 +1,17 @@
+Usage:
+  v shader [options] [DIRECTORY / FILE]
+
+Examples:
+  v shader .
+  v shader examples/sokol/02_cubes_glsl/cube_glsl.glsl
+
+  Compile shaders in sokol's annotated GLSL format to C headers for use with sokol based apps.
+  Sokol based apps include all apps using V's gg module.
+
+Options:
+  -h, --help                     Show this help text.
+  -v, --verbose                  Be verbose about the tools progress.
+  -u, --force-update             Force update of the sokol-shdc tool.
+  -l, --slang <multiple strings> Shader dialects to generate code for. Default is all.
+                                 Available: 'glsl330', 'glsl100', 'glsl300es', 'hlsl4', 'hlsl5', 'metal_macos', 'metal_ios', 'metal_sim', 'wgpu'
+								 
diff --git a/doc/docs.md b/doc/docs.md
index f34a38cdcc..767c13b9df 100644
--- a/doc/docs.md
+++ b/doc/docs.md
@@ -124,6 +124,7 @@ For more details and troubleshooting, please visit the [vab GitHub repository](h
 * [Writing documentation](#writing-documentation)
 * [Tools](#tools)
     * [v fmt](#v-fmt)
+    * [v shader](#v-shader)
     * [Profiling](#profiling)
 * [Package Management](#package-management)
 	* [Publish package](#publish-package)
@@ -4121,6 +4122,19 @@ A vfmt run is usually pretty cheap (takes <30ms).
 
 Always run `v fmt -w file.v` before pushing your code.
 
+### v shader
+
+You can use GPU shaders with V graphical apps. You write your shaders in an
+[annotated GLSL dialect](https://github.com/vlang/v/blob/1d8ece7/examples/sokol/02_cubes_glsl/cube_glsl.glsl)
+and use `v shader` to compile them for all supported target platforms.
+
+```shell
+v shader /path/to/project/dir/or/file.v
+```
+
+Currently you need to include a header and declare a glue function before
+using the shader in your code.
+
 ### Profiling
 
 V has good support for profiling your programs: `v -profile profile.txt run file.v`