Add <help-category> list and hint on usage in slangc -h (#7638)

* Add category list at end of slangc -h output

* Use value category for categories

* format code (#12)

Co-authored-by: slangbot <186143334+slangbot@users.noreply.github.com>

* Regenerate cmdline reference

---------

Co-authored-by: slangbot <ellieh+slangbot@nvidia.com>
Co-authored-by: slangbot <186143334+slangbot@users.noreply.github.com>

3 files changed, 60 insertions, 1 deletions

diff --git a/docs/command-line-slangc-reference.md b/docs/command-line-slangc-reference.md
index c1ea9d720..d8d58ec9b 100644
--- a/docs/command-line-slangc-reference.md
+++ b/docs/command-line-slangc-reference.md
@@ -38,6 +38,7 @@ slangc -help-style markdown -h
 * [vulkan-shift](#vulkan-shift)
 * [capability](#capability)
 * [file-extension](#file-extension)
+* [help-category](#help-category)
 
 <a id="General"></a>
 ## General
@@ -94,7 +95,7 @@ Emit IR typically as a '.slang-module' when outputting to a container.
 <a id="h"></a>
 ### -h, -help, --help
 
-**-h or -h &lt;help-category&gt;**
+**-h or -h &lt;[help-category](#help-category)&gt;**
 
 Print this message, or help in specified category. 
 
@@ -1602,3 +1603,36 @@ A [&lt;language&gt;](#language), &lt;format&gt;, and/or [&lt;stage&gt;](#stage)
 * `slang-module`, `slang-library` : Slang Module/Library 
 * `dir` : Container as a directory 
 
+<a id="help-category"></a>
+## help-category
+
+Available help categories for the [-h](#h) option 
+
+* `General` : General options 
+* `Target` : Target code generation options 
+* `Downstream` : Downstream compiler options 
+* `Debugging` : Compiler debugging/instrumentation options 
+* `Repro` : Slang repro system related 
+* `Experimental` : Experimental options (use at your own risk) 
+* `Internal` : Internal-use options (use at your own risk) 
+* `Deprecated` : Deprecated options (allowed but ignored; may be removed in future) 
+* `compiler` : Downstream Compilers (aka Pass through) 
+* `language` : Language 
+* `language-version` : Language Version 
+* `archive-type` : Archive Type 
+* `line-directive-mode` : Line Directive Mode 
+* `debug-info-format` : Debug Info Format 
+* `fp-mode` : Floating Point Mode 
+* `fp-denormal-mode` : Floating Point Denormal Handling Mode 
+* `help-style` : Help Style 
+* `optimization-level` : Optimization Level 
+* `debug-level` : Debug Level 
+* `file-system-type` : File System Type 
+* `source-embed-style` : Source Embed Style 
+* `target` : Target 
+* `stage` : Stage 
+* `vulkan-shift` : Vulkan Shift 
+* `capability` : A capability describes an optional feature that a target may or may not support. When a [-capability](#capability-1) is specified, the compiler may assume that the target supports that capability, and generate code accordingly. 
+* `file-extension` : A [&lt;language&gt;](#language), &lt;format&gt;, and/or [&lt;stage&gt;](#stage) may be inferred from the extension of an input or [-o](#o) path 
+* `help-category` : Available help categories for the [-h](#h) option 
+
diff --git a/source/core/slang-command-options-writer.cpp b/source/core/slang-command-options-writer.cpp
index 308cc4984..1f1de029d 100644
--- a/source/core/slang-command-options-writer.cpp
+++ b/source/core/slang-command-options-writer.cpp
@@ -504,6 +504,13 @@ void TextCommandOptionsWriter::appendDescriptionImpl()
     {
         _appendDescriptionForCategory(categoryIndex);
     }
+
+    // Add instructions for getting help for specific categories
+    m_builder << "Getting Help for Specific Categories\n";
+    m_builder << "=====================================\n\n";
+    m_builder << "To get help for a specific category of options or values, use: slangc -h "
+                 "<help-category>\n";
+    m_builder << "See the <help-category> section above for the list of categories.\n\n";
 }
 
 void TextCommandOptionsWriter::_appendDescriptionForCategory(Index categoryIndex)
diff --git a/source/slang/slang-options.cpp b/source/slang/slang-options.cpp
index 1b8a45401..af799839c 100644
--- a/source/slang/slang-options.cpp
+++ b/source/slang/slang-options.cpp
@@ -344,6 +344,24 @@ void initCommandOptions(CommandOptions& options)
         options.addValues(pairs, SLANG_COUNT_OF(pairs));
     }
 
+    /* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! help-category !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! */
+
+    {
+        options.addCategory(
+            CategoryKind::Value,
+            "help-category",
+            "Available help categories for the -h option");
+
+        // Add all existing categories as valid help category values
+        const auto& categories = options.getCategories();
+        for (Index categoryIndex = 0; categoryIndex < categories.getCount(); ++categoryIndex)
+        {
+            const auto& category = categories[categoryIndex];
+            options.addValue(category.name, category.description);
+        }
+    }
+
+
     /* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! General !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! */
 
     options.setCategory("General");