1
1
tree-sitter-vimdoc
2
2
==================
3
3
4
- This grammar intentionally support a subset of the vimdoc "spec"
4
+ This grammar implements the vimdoc "spec"
5
5
([ ref1] ( https://neovim.io/doc/user/helphelp.html#help-writing ) ,
6
- [ ref2] ( https://github.com/nanotee/vimdoc-notes ) );
7
- predictable results are the primary goal, so that _ output_ formats (e.g. HTML)
6
+ [ ref2] ( https://github.com/nanotee/vimdoc-notes ) ).
7
+ Predictable results are the primary goal, so that _ output_ formats (e.g. HTML)
8
8
are well-formed; the _ input_ (vimdoc) is secondary. The first step should
9
9
always be to try to fix the input rather than insist on a grammar that handles
10
10
vimdoc's endless quirks.
11
11
12
12
Overview
13
13
--------
14
14
15
- - ` block ` is the main top-level node which contains ` line ` and ` line_li ` nodes.
16
- - delimited by blank line(s) or any line starting with ` < ` (codeblock terminator).
15
+ - ` block ` is the main top-level node, delimited by blank line(s) or any line
16
+ starting with ` < ` (codeblock terminator).
17
+ - contains ` line ` and ` line_li ` nodes.
17
18
- ` line ` :
18
19
- contains atoms (words, tags, taglinks, …)
19
- - contains headings (` h1 ` , ` h2 ` , ` h3 ` ) because ` codeblock ` terminated by
20
- "implicit stop" (no terminating ` < ` ) consumes blank lines, so ` block ` has
21
- no way to end.
22
- - contains ` column_heading ` because ` < ` (the ` codeblock ` terminating char)
23
- can appear at the start of ` column_heading ` .
20
+ - contains headings (` h1 ` , ` h2 ` , ` h3 ` , ` column_heading ` ) because ` codeblock `
21
+ terminated by "implicit stop" (no terminating ` < ` ) consumes blank lines, so
22
+ ` block ` has no way to end.
24
23
- ` line_li ` ("list item")
25
24
- consumes lines until blank line, codeblock, or next listitem.
26
25
- nesting is ignored: indented listitems are parsed as siblings.
27
26
- ` codeblock ` :
28
- - contained by ` line ` or ` line_li ` . Because ">" can start
29
- a codeblock at the end of any line.
30
- - contains ` line ` nodes without ` word ` nodes, it's just the full
31
- raw text line including whitespace. This is somewhat dictated by its
32
- "preformatted" nature; parsing the contents would require loading a "child"
33
- language (injection). See [ #2 ] ( https://github.com/neovim/tree-sitter-vimdoc/issues/2 ) .
27
+ - contained by ` line ` or ` line_li ` , because ">" can start a codeblock at the
28
+ end of any line.
29
+ - contains ` line ` nodes without ` word ` nodes: it's just the full raw text
30
+ line including whitespace. This is somewhat dictated by its "preformatted"
31
+ nature; parsing the contents would require loading a "child" language
32
+ (injection). See [ #2 ] ( https://github.com/neovim/tree-sitter-vimdoc/issues/2 ) .
34
33
- the terminating ` < ` (and any following whitespace) is discarded (anonymous).
35
34
- ` h1 ` = "Heading 1": ` ====== ` followed by text and optional ` *tags* ` .
36
35
- ` h2 ` = "Heading 2": ` ------ ` followed by text and optional ` *tags* ` .
37
- - ` h3 ` = "Heading 3": only UPPERCASE WORDS, followed by optional ` *tags* ` .
36
+ - ` h3 ` = "Heading 3": UPPERCASE WORDS, followed by optional ` *tags* ` , followed
37
+ by atoms.
38
38
39
39
Known issues
40
40
------------
@@ -47,8 +47,7 @@ Known issues
47
47
- ` url ` doesn't handle _ surrounding_ parens. E.g. ` (https://example.com/#yay) ` yields ` word `
48
48
- ` url ` doesn't handle _ nested_ parens. E.g. ` (https://example.com/(foo)#yay) `
49
49
- ` column_heading ` currently only recognizes tilde ` ~ ` preceded by space (i.e.
50
- ` foo ~ ` not ` foo~ ` ). This covers 99% of : help files, but the grammar should
51
- probably support "foo~ " also.
50
+ ` foo ~ ` not ` foo~ ` ). This covers 99% of : help files.
52
51
- ` column_heading ` children should be plaintext. Currently its children are parsed as ` $._atom ` .
53
52
54
53
TODO
57
56
- ` line_modeline ` ?
58
57
- ` tag_heading ` : line(s) containing only tags, typically implies a "heading"
59
58
before a block.
59
+
60
+ Release
61
+ -------
62
+
63
+ Steps to perform a release:
64
+
65
+ 1 . Bump and tag the version (choose ` patch ` /` minor ` /` major ` as appropriate).
66
+ ```
67
+ npm version patch -m "release %s"
68
+ ```
69
+ 2 . Bump to prerelease, without creating a tag .
70
+ ```
71
+ npm version --no-git-tag-version prerelease --preid dev && git add package*.json && git commit -m bump
72
+ ```
73
+ 3 . Push.
74
+ ```
75
+ git push --follow-tags
76
+ ```
77
+ 4 . Release the tagged commit: https://github.com/neovim/tree-sitter-vimdoc/releases/new
0 commit comments