Repository files navigation

This grammar implements the vimdoc "spec"(ref1,ref2).Predictable results are the primary goal, so thatoutput formats (e.g. HTML)are well-formed; theinput (vimdoc) is secondary. The first step shouldalways be to try to fix the input rather than insist on a grammar that handlesvimdoc's endless quirks.

• block is the main top-level node, delimited by blank line(s) or any linestarting with< (codeblock terminator).
  • containsline andline_li nodes.
• line:
  • contains atoms (words, tags, taglinks, …)
  • contains headings (h1,h2,h3,column_heading) becausecodeblockterminated by "implicit stop" (no terminating<) consumes blank lines, soblock has no way to end.
• line_li ("listitem")
  • lines starting with-/• (not+/*) are listitems.
  • consumes lines until blank line, codeblock, or next listitem.
  • nesting is ignored: indented listitems are parsed as siblings.
• codeblock:
  • contained byline orline_li, because ">" can start a codeblock at theend of any line.
  • containsline nodes withoutword nodes: it's just the full raw textline including whitespace. This is somewhat dictated by its "preformatted"nature; parsing the contents would require loading a "child" language(injection). See#2.
  • the terminating< (and any following whitespace) is discarded (anonymous).
• h1 = "Heading 1":====== followed by text and optional*tags*.
• h2 = "Heading 2":------ followed by text and optional*tags*.
• h3 = "Heading 3": UPPERCASE WORDS, followed by optional*tags*, followedby atoms.

• Input must end with newline/EOL (\n). Grammar does not support files without EOL.
• Input must end with a blank line. Though this doesn't seem to matter in practice.
• Spec requires thatcodeblock delimiter ">" must be preceded by a space(" >"), not a tab. But currently the grammar doesn't enforce this. Example::help lcs-tab.
• url doesn't handlesurrounding parens. E.g.(https://example.com/#yay) yieldsword
• url doesn't handlenested parens. E.g.(https://example.com/(foo)#yay)
• column_heading currently only recognizes tilde~ preceded by space (i.e.foo ~ notfoo~). This covers 99% of :help files.
• column_heading children should be plaintext, but currently are parsed as$._atom.
• modeline must be preceded by a blank line.

• tag_heading : line(s) containing only tags, typically implies a "heading"before a block.

Steps to perform a release:

1. Bump and tag the version:

   First bumpCargo.toml,pyproject.toml, andMakefile to the new version.Then bump the package:

   npm version patch -m"release %s"

   Choosepatch/minor/major to indicate query compatibility:

   • patch for bugfixes (no changes to queries needed)
   • minor for added nodes (queries may need changes to use new nodes but will not error)
   • major for removed or renamed nodes (queries will error if not adapted), other breaking changes

2. Bump to prerelease, without creating a tag:

   npm version --no-git-tag-version prerelease --preid devgit add package*.json Cargo.toml pyproject.toml Makefilegit commit -m bump

3. Push:

   git push&& git push --tags

4. Release the tagged commit:https://github.com/neovim/tree-sitter-vimdoc/releases/new