Fix garbage text in markdown help heading for template-expanded options (#10096)

Fixes #10084

The markdown help output (`slangc -help-style markdown -h`) listed all
expanded names in `###` headings for template-expanded options. For
`-<compiler>-path`, this produced a heading with 14 compiler-specific
names (`-none-path, -fxc-path, -dxc-path, ...`), rendering as unreadable
garbage in the Downstream section of the docs. The same issue affected
`-fvk-<vulkan-shift>-shift` with 4 expanded names.

The text writer already handles this correctly by using the usage string
instead of the expanded names. The markdown writer had no way to
distinguish template-expanded names from regular aliases (e.g. `-h,
-help, --help`).

This adds a `displayName` field to `CommandOptions::Option` that
separates the display heading from the lookup names. Template-expanded
options set `displayName` to the template form (e.g.
`-<compiler>-path`), while alias options leave it empty and continue to
list all names in the heading. The markdown writer uses `displayName`
when set, and falls back to listing all names otherwise.

Author: aidanfnv

docs/command-line-slangc-reference.md

@@ -490,7 +490,7 @@ Make data accessed through ConstantBuffer, ParameterBlock, StructuredBuffer, Byt
 
 
 <a id="fvk-b-shift"></a>
-### -fvk-b-shift, -fvk-s-shift, -fvk-t-shift, -fvk-u-shift
+### -fvk-&lt;vulkan-shift&gt;-shift
 
 **-fvk-&lt;[vulkan-shift](#vulkan-shift)&gt;-shift &lt;N&gt; &lt;space&gt;**
 
@@ -621,7 +621,7 @@ Sets a comma-separates list of architecture-specific features for the LLVM targe
 Downstream compiler options 
 
 <a id="none-path"></a>
-### -none-path, -fxc-path, -dxc-path, -glslang-path, -spirv-dis-path, -clang-path, -visualstudio-path, -gcc-path, -genericcpp-path, -nvrtc-path, -llvm-path, -spirv-opt-path, -metal-path, -tint-path
+### -&lt;compiler&gt;-path
 
 **-&lt;[compiler](#compiler)&gt;-path &lt;path&gt;**
 

source/core/slang-command-options-writer.cpp

@@ -352,7 +352,14 @@ void MarkdownCommandOptionsWriter::_appendDescriptionForCategory(Index categoryI
                 }
 
                 m_builder << "### ";
-                StringUtil::join(names.getBuffer(), names.getCount(), toSlice(", "), m_builder);
+                if (option.displayName.getLength())
+                {
+                    _appendEscapedMarkdown(option.displayName, m_builder);
+                }
+                else
+                {
+                    StringUtil::join(names.getBuffer(), names.getCount(), toSlice(", "), m_builder);
+                }
                 m_builder << "\n";
 
                 if (option.usage.getLength())

source/core/slang-command-options.cpp

@@ -239,12 +239,14 @@ void CommandOptions::add(
     const char* inName,
     const char* usage,
     const char* description,
-    UserValue userValue)
+    UserValue userValue,
+    const char* displayName)
 {
     UnownedStringSlice nameSlice(inName);
 
     Option option;
     option.categoryIndex = m_currentCategoryIndex;
+    option.displayName = _addString(displayName);
     option.usage = _addString(usage);
     option.description = _addString(UnownedStringSlice(description));
     option.userValue = userValue;

source/core/slang-command-options.h

@@ -86,7 +86,9 @@ struct CommandOptions
     struct Option
     {
         UnownedStringSlice names; ///< Comma delimited list of names, first name is the default
-        UnownedStringSlice usage; ///< Describes usage, can be empty
+        UnownedStringSlice displayName; ///< Heading override for docs (e.g. template form); empty
+                                        ///< means use names
+        UnownedStringSlice usage;       ///< Describes usage, can be empty
         UnownedStringSlice description; ///< A description of usage
 
         UserValue userValue = kInvalidUserValue;
@@ -118,7 +120,8 @@ struct CommandOptions
         const char* name,
         const char* usage,
         const char* description,
-        UserValue userValue = kInvalidUserValue);
+        UserValue userValue = kInvalidUserValue,
+        const char* displayName = nullptr);
     void add(
         const UnownedStringSlice* names,
         Count namesCount,

source/slang/slang-options.cpp

@@ -46,6 +46,7 @@ struct Option
     const char* name;
     const char* usage = nullptr;
     const char* description = nullptr;
+    const char* displayName = nullptr;
 };
 
 enum class ValueCategory
@@ -101,8 +102,12 @@ static void _addOptions(const ConstArrayView<Option>& options, CommandOptions& c
 {
     for (auto& opt : options)
     {
-        cmdOptions
-            .add(opt.name, opt.usage, opt.description, CommandOptions::UserValue(opt.optionKind));
+        cmdOptions.add(
+            opt.name,
+            opt.usage,
+            opt.description,
+            CommandOptions::UserValue(opt.optionKind),
+            opt.displayName);
     }
 }
 
@@ -698,7 +703,8 @@ void initCommandOptions(CommandOptions& options)
          "SPIR-V.rst#implicit-binding-number-assignment)\n"
          "* [GLSL "
          "wiki](https://github.com/KhronosGroup/glslang/wiki/"
-         "HLSL-FAQ#auto-mapped-binding-numbers)\n"},
+         "HLSL-FAQ#auto-mapped-binding-numbers)\n",
+         "-fvk-<vulkan-shift>-shift"},
         {OptionKind::VulkanBindGlobals,
          "-fvk-bind-globals",
          "-fvk-bind-globals <N> <descriptor-set>",
@@ -803,7 +809,8 @@ void initCommandOptions(CommandOptions& options)
             "-<compiler>-path <path>",
             "Specify path to a downstream <compiler> "
             "executable or library.\n",
-            UserValue(OptionKind::CompilerPath));
+            UserValue(OptionKind::CompilerPath),
+            "-<compiler>-path");
     }
 
     const Option downstreamOpts[] = {