From 35f6c62869dfda613ea7fffc409f715a523559d8 Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Mon, 26 Jun 2023 01:32:58 +0200
Subject: [PATCH] [optional]

Problem:
Using _word() to define an optional arg leads to a lot of syntax errors in
real-world :help files because [brackets] are commonly used for non-args.

Solution:
Define (optional) with a regex, like (keycode) instead of using the more
"formal" mechanism. Regex has "best-effort" behavior, while seq() behaves more
strictly.

Don't treat `[{arg}]` as (optional), else it clobbers the nested `{arg}`.

fix #1
---
 corpus/argument.txt          |  6 ++++--
 corpus/argument_optional.txt | 24 ++++++++----------------
 corpus/codeblock.txt         |  3 +--
 corpus/taglink.txt           |  3 +--
 corpus/url.txt               |  3 +--
 grammar.js                   |  7 ++++---
 6 files changed, 19 insertions(+), 27 deletions(-)

diff --git a/corpus/argument.txt b/corpus/argument.txt
index 87b293d..0abb389 100644
--- a/corpus/argument.txt
+++ b/corpus/argument.txt
@@ -117,8 +117,10 @@ nvim_buf_detach_event[{buf}]
       (word))
     (line
       (word)
-      (optional_arg
-        (word)))))
+      (word)
+      (argument
+        (word))
+      (word))))
 
 ================================================================================
 NOT an argument
diff --git a/corpus/argument_optional.txt b/corpus/argument_optional.txt
index fb1a649..7b5cc6f 100644
--- a/corpus/argument_optional.txt
+++ b/corpus/argument_optional.txt
@@ -11,30 +11,22 @@ optional [argument]
   (block
     (line
       (word)
-      (optional_arg
-        (word))
+      (optional)
       (word)
-      (optional_arg
-        (word))
-      (optional_arg
-        (word))
+      (optional)
+      (optional)
       (argument
         (word))
       (tag
         (word)))
     (line
       (word)
-      (optional_arg
-        (word))
+      (optional)
       (word)
-      (optional_arg
-        (word))
-      (optional_arg
-        (word))
-      (optional_arg
-        (word))
-      (optional_arg
-        (word))
+      (optional)
+      (optional)
+      (optional)
+      (optional)
       (argument
         (word))
       (word))))
diff --git a/corpus/codeblock.txt b/corpus/codeblock.txt
index a138078..f1c655b 100644
--- a/corpus/codeblock.txt
+++ b/corpus/codeblock.txt
@@ -398,8 +398,7 @@ codeblock stop and start on same line
     (line
       (word)
       (word)
-      (optional_arg
-        (word)))
+      (optional))
     (line
       (argument
         (word))))
diff --git a/corpus/taglink.txt b/corpus/taglink.txt
index 8bdea96..6d7390d 100644
--- a/corpus/taglink.txt
+++ b/corpus/taglink.txt
@@ -56,8 +56,7 @@ Hello |world| hello
       (taglink
         (word))
       (word)
-      (optional_arg
-        (word))
+      (optional)
       (word))
     (line
       (taglink
diff --git a/corpus/url.txt b/corpus/url.txt
index 8e7f4b1..53e0ef2 100644
--- a/corpus/url.txt
+++ b/corpus/url.txt
@@ -54,8 +54,7 @@ markdown: [https://neovim.io/doc/user/#yay](https://neovim.io/doc/user/#yay).
       (word))
     (line
       (word)
-      (optional_arg
-        (word))
+      (optional)
       (word)
       (url
         (word))
diff --git a/grammar.js b/grammar.js
index ff13d76..f979e3e 100644
--- a/grammar.js
+++ b/grammar.js
@@ -53,7 +53,7 @@ module.exports = grammar({
         $.taglink,
         $.codespan,
         $.argument,
-        $.optional_arg,
+        $.optional,
         $.keycode,
       ),
 
@@ -96,6 +96,9 @@ module.exports = grammar({
       /ALT-./,
     ),
 
+    // Optional argument: [arg] (no whitespace allowed)
+    optional: () => /\[[^\]{\n\t ]+\]/,
+
     // First part (minus tags) of h3 or column_heading.
     uppercase_name: () => seq(
       token.immediate(_uppercase_word),  // No whitespace before heading.
@@ -211,8 +214,6 @@ module.exports = grammar({
     codespan: ($) => _word($, /[^``\n]+/, '`', '`'),
     // Argument: {arg} (no whitespace allowed)
     argument: ($) => _word($, /[^}\n\t ]+/, '{', '}'),
-    // Optional argument: [arg] (no whitespace allowed)
-    optional_arg: ($) => _word($, /[^\]\n\t ]+/, '[', ']'),
   },
 });