Skip to content

Commit 2b81f6c

Browse files
justinmkjustinmk
committed
rename forms, introduce (h2), move (column_name) into (line)
fixes for url, column_name, etc.
1 parent dcc85f1 commit 2b81f6c

File tree

12 files changed

+284
-116
lines changed

12 files changed

+284
-116
lines changed

‎README.md‎

Lines changed: 18 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -13,14 +13,29 @@ Notes
1313
- vimdoc format "spec":
1414
- [:help help-writing](https://neovim.io/doc/user/helphelp.html#help-writing)
1515
- https://github.com/nanotee/vimdoc-notes
16-
- `(code_block)` is contained by `(line)` because `>` can start a code block at the end of a line.
16+
- whitespace is intentionally captured in `(word)`, because it is often necessary to be
17+
able to correctly layout vim help files (especially old/legacy).
18+
- `(codeblock)` is contained by `(line)` because `>` can start a code block at the end of a line.
19+
- `(column_heading)` is contained by `(line)` because `>` (to close
20+
a `(codeblock)` can appear at the start of `(column_heading)`.
21+
- `h1` ("Heading 1"): `======` followed by text and optional `*tags*`.
22+
- `h2` ("Heading 2"): `------` followed by text and optional `*tags*`.
23+
- `h3` ("Heading 3"): only UPPERCASE WORDS, followed by optional `*tags*`.
1724

1825
Known issues
1926
------------
2027

21-
- `line` in a `code_block` does not contain `word` atoms, it's just the full
28+
- `line_li` ("list item") is _experimental_. It doesn't support nesting yet and
29+
it may not work well; you can treat it as a normal `line` for layout purposes.
30+
- `codeblock` ">" must not be preceded only by tabs, a space char is required (" >").
31+
See `:help lcs-tab` for example. Currently the grammar doesn't enforce this.
32+
- `codeblock` terminated by an "implicit stop" (i.e. no terminating `<`)
33+
consumes the first char of the terminating line, and continues the parent
34+
`block`, preventing top-level forms like `h1`, `h2` from being recognized
35+
until a blank line is encountered.
36+
- `line` in a `codeblock` does not contain `word` atoms, it's just the full
2237
raw text line including whitespace. This is somewhat dictated by its
23-
"preformatted" nature; parsing the contents implies loading a "child"
38+
"preformatted" nature; parsing the contents would require loading a "child"
2439
language (injection). See [#2](https://github.com/vigoux/tree-sitter-vimdoc/issues/2).
2540
- `url` doesn't handle _surrounding_ parens. E.g. `(https://example.com/#yay)` yields `word`
2641
- `url` doesn't handle _nested_ parens. E.g. `(https://example.com/(foo)#yay)`
@@ -37,9 +52,3 @@ TODO
3752
- `line_noeol` is a special-case to support documents that don't end in EOL.
3853
Grammar could be a bit simpler if we just require EOL at end of document.
3954
- `line_modeline` (only at EOF)
40-
- `column_heading` should not allow hotlinks. This is sometimes used in old help files to show results of a code example, e.g. in `usr_41.txt`:
41-
```
42-
List concatenation is done with +: >
43-
:echo alist + ['foo', 'bar']
44-
< ['foo', 'bar', 'foo', 'bar'] ~
45-
```

‎corpus/arguments.txt‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ multiple arguments on the same line
3434
================================================================================
3535
NOT an argument
3636
================================================================================
37-
{foo "{bar}" `{baz}` |{baz| }
37+
{foo "{bar}" `{baz}` |{baz| } {}
3838

3939
--------------------------------------------------------------------------------
4040

@@ -45,8 +45,9 @@ NOT an argument
4545
(word)
4646
(ERROR))
4747
(word)
48-
(backtick
48+
(codespan
4949
(word))
50-
(hotlink
50+
(taglink
5151
(word))
52+
(word)
5253
(word))))

‎corpus/code_block.txt‎ renamed to ‎corpus/codeblock.txt‎

Lines changed: 27 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -21,21 +21,21 @@ block3:
2121
(help_file
2222
(block
2323
(line
24-
(code_block
24+
(codeblock
2525
(line))))
2626
(block
2727
(line
2828
(word))
2929
(line
30-
(code_block
30+
(codeblock
3131
(line)))
3232
(line
3333
(word)))
3434
(block
3535
(line
3636
(word))
3737
(line
38-
(code_block
38+
(codeblock
3939
(line))))
4040
(block
4141
(line
@@ -68,7 +68,7 @@ text
6868
(line
6969
(word)
7070
(word)
71-
(code_block
71+
(codeblock
7272
(line)
7373
(line)
7474
(line))))
@@ -79,11 +79,11 @@ text
7979
(block
8080
(line
8181
(word)
82-
(hotlink
82+
(taglink
8383
(word))
8484
(word))
8585
(line
86-
(code_block
86+
(codeblock
8787
(line)
8888
(line)
8989
(line))))
@@ -92,23 +92,36 @@ text
9292
(word))))
9393

9494
================================================================================
95-
codeblock with implicit stop
95+
codeblock with implicit stop (FIXME)
9696
================================================================================
9797
>
9898
line1
9999
line2
100100

101-
Blehke
101+
-------------------------------
102+
h1-headline *foo*
103+
104+
-------------------------------
105+
h1-headline *foo*
106+
102107
--------------------------------------------------------------------------------
103108

104109
(help_file
105110
(block
106111
(line
107-
(code_block
112+
(codeblock
108113
(line)
109114
(line)
110115
(line)))
111116
(line
117+
(word))
118+
(line
119+
(word)
120+
(tag
121+
(word))))
122+
(h2
123+
(word)
124+
(tag
112125
(word))))
113126

114127
================================================================================
@@ -133,7 +146,7 @@ x
133146
(block
134147
(line
135148
(word)
136-
(code_block
149+
(codeblock
137150
(line)
138151
(line)
139152
(line)
@@ -159,7 +172,7 @@ tricky
159172
(help_file
160173
(block
161174
(line
162-
(code_block
175+
(codeblock
163176
(line)
164177
(line)
165178
(line))))
@@ -192,7 +205,7 @@ To test for a non-empty string, use empty(): >
192205
(word)
193206
(word)
194207
(word)
195-
(code_block
208+
(codeblock
196209
(line)
197210
(line)))
198211
(line
@@ -216,7 +229,7 @@ To test for a non-empty string, use empty(): >
216229
(word)
217230
(word)
218231
(word)
219-
(code_block
232+
(codeblock
220233
(line)
221234
(line)))
222235
(line
@@ -228,5 +241,5 @@ To test for a non-empty string, use empty(): >
228241
(word)
229242
(word)
230243
(word)
231-
(code_block
244+
(codeblock
232245
(line)))))

‎corpus/backtick.txt‎ renamed to ‎corpus/codespan.txt‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
================================================================================
2-
simple backtick
2+
simple codespan
33
================================================================================
44

55
a `foobar` b `:echo`
@@ -10,14 +10,14 @@ a `foobar` b `:echo`
1010
(block
1111
(line
1212
(word)
13-
(backtick
13+
(codespan
1414
(word))
1515
(word)
16-
(backtick
16+
(codespan
1717
(word)))))
1818

1919
================================================================================
20-
backtick in text
20+
codespan in text
2121
================================================================================
2222

2323
Hello `world`, I am `markup language`. But `this is
@@ -29,24 +29,24 @@ an error`.
2929
(block
3030
(line
3131
(word)
32-
(backtick
32+
(codespan
3333
(word))
3434
(word)
3535
(word)
3636
(word)
37-
(backtick
37+
(codespan
3838
(word))
3939
(word)
4040
(word)
41-
(backtick
41+
(codespan
4242
(word)
4343
(MISSING "`")))
4444
(line
4545
(word)
4646
(word))))
4747

4848
================================================================================
49-
NOT a codespan / backtick
49+
NOT a codespan
5050
================================================================================
5151
*'* *'a* *`* *`a*
5252
'{a-z} `{a-z} Jump to the mark.

‎corpus/headline.txt‎ renamed to ‎corpus/heading1_2.txt‎

Lines changed: 38 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,64 @@
11
================================================================================
2-
simple headline
2+
h1 h2 heading
33
================================================================================
44

55
==============================================================================
6-
Headline *headline*
6+
Heading1 *heading1*
77

88
Text
99

10+
-----------------------------------------------------------------------
11+
Heading two *tag2.1* *tag2.2*
12+
13+
Text2
14+
1015
--------------------------------------------------------------------------------
1116

1217
(help_file
13-
(headline
18+
(h1
1419
(word)
1520
(tag
1621
(word)))
22+
(block
23+
(line
24+
(word)))
25+
(h2
26+
(word)
27+
(word)
28+
(tag
29+
(word))
30+
(tag
31+
(word)))
1732
(block
1833
(line
1934
(word))))
2035

2136
================================================================================
22-
headline with tag at the start
37+
h1 h2 heading with tag at the start
2338
================================================================================
2439

2540
==============================================================================
2641
*03.1* Word movement
2742

2843
Text
2944

45+
------------------------------------------------------------------------------
46+
*05.6* heading two
47+
48+
Text
49+
3050
--------------------------------------------------------------------------------
3151

3252
(help_file
33-
(headline
53+
(h1
54+
(tag
55+
(word))
56+
(word)
57+
(word))
58+
(block
59+
(line
60+
(word)))
61+
(h2
3462
(tag
3563
(word))
3664
(word)
@@ -40,26 +68,26 @@ Text
4068
(word))))
4169

4270
================================================================================
43-
NOT a headline
71+
NOT h1 h2 heading
4472
================================================================================
4573

4674
====
47-
Not-a-headline-1 *headline1*
75+
Not-a-heading-1 *heading1*
4876

4977
Text
5078

5179
---
52-
Not-a-headline-2 more words *headline2*
80+
Not-a-heading-2 more words *heading2*
5381

5482
Text
5583

5684
===========a======b========3089uaafaewf_-----awefpoij===========================
57-
Not-a-headline-3 *headline3*
85+
Not-a-heading-3 *heading3*
5886

5987
Text
6088

6189
------------===============--------------------=================================
62-
Not-a-headline-4 *headline4*
90+
Not-a-heading-4 *heading4*
6391
Text
6492

6593
--------------------------------------------------------------------------------

0 commit comments

Comments
 (0)