fix(headings): error if line starts with uppercase #24

Problem:
Plaintext lines starting with uppercase word(s) are flagged as (h3) ERROR.

Solution:
Tell the grammar explicitly that uppercase words are allowed at the
start of a plaintext (line), this does not necessarily mean the line is
an invalid (h3) heading.

Author: justinmk

corpus/heading3-column_heading.txt

@@ -151,6 +151,13 @@ NOT h3 uppercase heading
 ^V	0x16	 22	(SYN)
 ^W	0x17	 23	END
 
+ABC not-h3
+
+4. 'runtimepath' `/xxx;yyy/baz`.The
+   `/foo/bar`-and-`/abc`.
+5. PRODUCT of 3.
+   ...`/lua`-path,-leaving:
+
 --------------------------------------------------------------------------------
 
 (help_file
@@ -164,6 +171,29 @@ NOT h3 uppercase heading
       (word)
       (word)
       (word)
+      (word)))
+  (block
+    (line
+      (word)
+      (word)))
+  (block
+    (line
+      (word)
+      (optionlink
+        (word))
+      (codespan
+        (word))
+      (word))
+    (line
+      (codespan
+        (word))
+      (word))
+    (line
+      (word)
+      (word)
+      (word)
+      (word))
+    (line
       (word))))
 
 ================================================================================

grammar.js

@@ -1,8 +1,14 @@
+const _uppercase_word = /[A-Z0-9.()][-A-Z0-9.()_]+/;
+
 module.exports = grammar({
   name: 'help', // The actual language name is help
 
   extras: () => [/[\t ]/],
 
+  inline: ($) => [
+    $.uppercase_words,
+  ],
+
   rules: {
     help_file: ($) =>
       seq(
@@ -52,6 +58,17 @@ module.exports = grammar({
       /\{\}/,
     ),
 
+    // First part (minus tags) of h3 or column_heading.
+    uppercase_name: () => seq(
+      token.immediate(_uppercase_word),  // No whitespace before heading.
+      repeat(_uppercase_word),
+    ),
+    // Line (plaintext) can start with uppercase words; don't flag as "invalid h3".
+    uppercase_words: ($) => prec.left(-1, seq(
+      alias(token.immediate(_uppercase_word), $.word),
+      alias(repeat(_uppercase_word), $.word),
+    )),
+
     // Text block/paragraph: adjacent lines followed by blank line(s).
     block: ($) => prec.right(seq(
         repeat1(choice($.line, $.line_li)),
@@ -111,10 +128,7 @@ module.exports = grammar({
         repeat(_blank()),
       ),
 
-    // Heading 3: UPPERCASE WORDS, followed by optional *tags*.
-    uppercase_name: () => seq(
-      token.immediate(/[A-Z0-9.()][-A-Z0-9.()_]+/),  // No whitespace before heading.
-      repeat(/[A-Z0-9.()][-A-Z0-9.()_]+/)),
+    // Heading 3: UPPERCASE NAME, followed by optional *tags*.
     h3: ($) =>
       seq(
         field('name', $.uppercase_name),
@@ -167,8 +181,9 @@ function _line($, require_eol) {
   const eol = require_eol ? '\n' : optional('\n');
   return choice(
     $.column_heading,
-    seq(repeat($._atom), $.codeblock),
-    seq(repeat1($._atom), choice($.codeblock, eol)));
+    seq(optional($.uppercase_words), repeat($._atom), $.codeblock),
+    seq(optional($.uppercase_words), repeat1($._atom), choice($.codeblock, eol)),
+  );
 }
 
 function _blank() {

src/grammar.json

@@ -180,6 +180,58 @@
         }
       ]
     },
+    "uppercase_name": {
+      "type": "SEQ",
+      "members": [
+        {
+          "type": "IMMEDIATE_TOKEN",
+          "content": {
+            "type": "PATTERN",
+            "value": "[A-Z0-9.()][-A-Z0-9.()_]+"
+          }
+        },
+        {
+          "type": "REPEAT",
+          "content": {
+            "type": "PATTERN",
+            "value": "[A-Z0-9.()][-A-Z0-9.()_]+"
+          }
+        }
+      ]
+    },
+    "uppercase_words": {
+      "type": "PREC_LEFT",
+      "value": -1,
+      "content": {
+        "type": "SEQ",
+        "members": [
+          {
+            "type": "ALIAS",
+            "content": {
+              "type": "IMMEDIATE_TOKEN",
+              "content": {
+                "type": "PATTERN",
+                "value": "[A-Z0-9.()][-A-Z0-9.()_]+"
+              }
+            },
+            "named": true,
+            "value": "word"
+          },
+          {
+            "type": "ALIAS",
+            "content": {
+              "type": "REPEAT",
+              "content": {
+                "type": "PATTERN",
+                "value": "[A-Z0-9.()][-A-Z0-9.()_]+"
+              }
+            },
+            "named": true,
+            "value": "word"
+          }
+        ]
+      }
+    },
     "block": {
       "type": "PREC_RIGHT",
       "value": 0,
@@ -343,6 +395,18 @@
         {
           "type": "SEQ",
           "members": [
+            {
+              "type": "CHOICE",
+              "members": [
+                {
+                  "type": "SYMBOL",
+                  "name": "uppercase_words"
+                },
+                {
+                  "type": "BLANK"
+                }
+              ]
+            },
             {
               "type": "REPEAT",
               "content": {
@@ -359,6 +423,18 @@
         {
           "type": "SEQ",
           "members": [
+            {
+              "type": "CHOICE",
+              "members": [
+                {
+                  "type": "SYMBOL",
+                  "name": "uppercase_words"
+                },
+                {
+                  "type": "BLANK"
+                }
+              ]
+            },
             {
               "type": "REPEAT1",
               "content": {
@@ -393,6 +469,18 @@
         {
           "type": "SEQ",
           "members": [
+            {
+              "type": "CHOICE",
+              "members": [
+                {
+                  "type": "SYMBOL",
+                  "name": "uppercase_words"
+                },
+                {
+                  "type": "BLANK"
+                }
+              ]
+            },
             {
               "type": "REPEAT",
               "content": {
@@ -409,6 +497,18 @@
         {
           "type": "SEQ",
           "members": [
+            {
+              "type": "CHOICE",
+              "members": [
+                {
+                  "type": "SYMBOL",
+                  "name": "uppercase_words"
+                },
+                {
+                  "type": "BLANK"
+                }
+              ]
+            },
             {
               "type": "REPEAT1",
               "content": {
@@ -604,25 +704,6 @@
         }
       ]
     },
-    "uppercase_name": {
-      "type": "SEQ",
-      "members": [
-        {
-          "type": "IMMEDIATE_TOKEN",
-          "content": {
-            "type": "PATTERN",
-            "value": "[A-Z0-9.()][-A-Z0-9.()_]+"
-          }
-        },
-        {
-          "type": "REPEAT",
-          "content": {
-            "type": "PATTERN",
-            "value": "[A-Z0-9.()][-A-Z0-9.()_]+"
-          }
-        }
-      ]
-    },
     "h3": {
       "type": "SEQ",
       "members": [
@@ -850,7 +931,9 @@
   "conflicts": [],
   "precedences": [],
   "externals": [],
-  "inline": [],
+  "inline": [
+    "uppercase_words"
+  ],
   "supertypes": []
 }