Vim/Neovim helpfile grammar

vim-helpfile.ebnf

(* Core Structure *)
HelpFile        = FirstLine, { Section | FreeContent }, [ Modeline ] ;
FirstLine       = TagDef, Tab, Description, Newline ;
Section         = Heading, SeparatorLine, { Block } ;
FreeContent     = { Block } ;

(* Headings and Separators *)
Heading         = TextLine ;
SeparatorLine   = "=", "=", "=", { "=" }, Newline ;  (* Min 3 '=' *)
ColumnHeading   = Text, " ~", Newline ;

(* Content Blocks *)
Block           = Paragraph 
                | ListItem 
                | CodeBlock 
                | TagDefLine 
                | ColumnHeading 
                | SeparatorLine 
                | EmptyLine 
                ;
Paragraph       = { TextLine } ;
ListItem        = "-", Space, Text, Newline ;
CodeBlock       = CodeStart, { CodeLine }, CodeEnd ;
CodeStart       = { TextToken }, ">", Newline ;
CodeEnd         = [ Whitespace ], "<", { TextToken }, Newline ;
CodeLine        = Text, Newline ;
TagDefLine      = { TextToken }, TagDef, { TextToken }, Newline ;
EmptyLine       = Newline ;

(* Inline Elements *)
InlineElement   = TagRef 
                | SpecialKey 
                | BacktickString 
                | SingleQuotedString 
                | CurlyBraces 
                | SquareBrackets 
                | AngleBrackets 
                ;
TagRef          = "|", TagName, "|" ;
SpecialKey      = "<", KeyName, ">" ;
BacktickString  = "`", { ? printable char except "`" ? }, "`" ;
SingleQuotedString = "'", { ? printable char except "'" ? }, "'" ;

(* Bracket Types with Semantic Distinction *)
CurlyBraces     = "{", ( Motion | Visual | CharRange | PlaceholderText ), "}" ;
SquareBrackets  = "[", ( Count | Register | OptionalText ), "]" ;
AngleBrackets   = "<", ( KeyNotation | EscapedChar ), ">" ;

(* Placeholder Types *)
Motion          = "motion" ;
Visual          = "Visual" ;
CharRange       = Char, "-", Char ;
Count           = "count" ;
Register        = "quotex" ;
PlaceholderText = ? ASCII word characters ? ;
OptionalText    = ? ASCII word characters or modifiers (e.g., "++once") ? ;
KeyNotation     = ( [ Modifier, "-" ], BaseKey ) | SpecialKeyName ;
EscapedChar     = "lt" | "Bar" | "Bslash" ;

(* Key Components *)
Modifier        = "C" | "S" | "M" | "A" | "T" | "D" ;  (* CTRL/SHIFT/META/ALT/SUPER*)
BaseKey         = ? Valid key names: F1-12, Up, Down, Enter, etc. ? ;
SpecialKeyName  = "Nul" | "BS" | "Tab" | "NL" | "CR" | "Esc" | ... ;

(* Terminal Definitions *)
TagDef          = "*", TagName, "*" ;
TagName         = ? Printable chars except '*' and whitespace ? ;
Text            = { TextToken | InlineElement } ;
TextToken       = ? Printable chars except special tokens * | < > ` ' { } [ ] ? ;
Description     = ? Any text except newline ? ;
Whitespace      = ( " " | "\t" ), { " " | "\t" } ;
Space           = " " | "\t" ;
Tab             = "\t" ;
Newline         = "\n" | "\r\n" ;
Char            = ? Single ASCII character ? ;

(* Special Cases *)
Modeline        = "vim:", { ? Any character ? }, Newline ;