Vimdoc writer (#11132)

Support for vimdoc, documentation format used by vim in its help pages.
Relies heavily on definition lists and precise text alignment to generate tags.

7 files changed, 483 insertions, 0 deletions

diff --git a/test/vimdoc/definition-lists.markdown b/test/vimdoc/definition-lists.markdown
new file mode 100644
index 000000000..a075d5125
--- /dev/null
+++ b/test/vimdoc/definition-lists.markdown
@@ -0,0 +1,70 @@
+---
+vimdoc-prefix: pandoc
+abstract: "A short description"
+filename: "definition-lists.txt"
+author: Author
+title: Title
+---
+
+## Basic
+
+Term 1
+:   Definition I
+
+Term 2
+:   Definition II
+
+Term 3
+:   Definition III
+
+## Code
+
+<!-- Source: <https://github.com/ggandor/leap.nvim/blob/c4a215acef90749851d85ddba08bc282867b50eb/doc/leap.txt#L283-L294> -->
+
+`leap.opts.keys.next_target`
+: Jump to the next available target (use the previous search pattern if no input
+  has been given). `:h leap-repeat`
+
+`leap.opts.keys.prev_target`
+: Jump to the previous target (revert `next_target`).
+
+`leap.opts.keys.next_group`
+: Shift to the next group of labeled targets.
+
+`leap.opts.keys.prev_group`
+: Shift to the previous group of labeled targets (revert `next_group`).
+
+## Span
+
+[Important concept]{#important-concept}
+: Definition
+
+[I am too long to fit on the same line as a reference, so reference is put above me!]{#i-am-too-long}
+: Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
+  tempor incididunt ut labore et dolore magna aliqua.
+
+## Commands
+
+In markdown vim commands are represented as inline code starting with colon (ie.
+`:MyCommand`), but writer strips the backticks
+
+`:FnlCompileBuffer`{#:FnlCompileBuffer}
+
+:   Compiles current active fennel buffer
+
+`:FnlCompile[!]`{#:FnlCompile}
+
+:   Diff compiles all indexed fennel files
+    If bang! is present then forcefully compiles all `source` files
+
+`:[range]Fnl {expr}`{#:Fnl}
+
+:    Evaluates {expr} or range
+
+     ```
+     :'<,'>Fnl
+
+     :Fnl (print "Hello World")
+
+     :Fnl (values some_var)
+     ```
diff --git a/test/vimdoc/definition-lists.vimdoc b/test/vimdoc/definition-lists.vimdoc
new file mode 100644
index 000000000..3061de6be
--- /dev/null
+++ b/test/vimdoc/definition-lists.vimdoc
@@ -0,0 +1,71 @@
+*definition-lists.txt*	A short description
+
+                               Title by Author
+
+
+                                       Type |gO| to see the table of contents.
+
+Basic ........................................................... |pandoc-basic|
+Code ............................................................. |pandoc-code|
+Span ............................................................. |pandoc-span|
+Commands ..................................................... |pandoc-commands|
+
+------------------------------------------------------------------------------
+Basic                                                             *pandoc-basic*
+
+Term 1
+    Definition I
+Term 2
+    Definition II
+Term 3
+    Definition III
+
+------------------------------------------------------------------------------
+Code                                                               *pandoc-code*
+
+`leap.opts.keys.next_target`
+    Jump to the next available target (use the previous search pattern if no
+    input has been given). |leap-repeat|
+`leap.opts.keys.prev_target`
+    Jump to the previous target (revert `next_target`).
+`leap.opts.keys.next_group`
+    Shift to the next group of labeled targets.
+`leap.opts.keys.prev_group`
+    Shift to the previous group of labeled targets (revert `next_group`).
+
+------------------------------------------------------------------------------
+Span                                                               *pandoc-span*
+
+Important concept                                     *pandoc-important-concept*
+    Definition
+                                                          *pandoc-i-am-too-long*
+I am too long to fit on the same line as a reference, so reference is put
+above me!
+    Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
+    tempor incididunt ut labore et dolore magna aliqua.
+
+------------------------------------------------------------------------------
+Commands                                                       *pandoc-commands*
+
+In markdown vim commands are represented as inline code starting with colon
+(ie. `:MyCommand`), but writer strips the backticks
+
+:FnlCompileBuffer                                            *:FnlCompileBuffer*
+    Compiles current active fennel buffer
+
+:FnlCompile[!]                                                     *:FnlCompile*
+    Diff compiles all indexed fennel files If bang! is present then forcefully
+    compiles all `source` files
+
+:[range]Fnl {expr}                                                        *:Fnl*
+    Evaluates {expr} or range
+
+    >
+        :'<,'>Fnl
+
+        :Fnl (print "Hello World")
+
+        :Fnl (values some_var)
+<
+
+ vim:tw=78:sw=4:ts=4:ft=help:norl:et:
diff --git a/test/vimdoc/headers-numbered.vimdoc b/test/vimdoc/headers-numbered.vimdoc
new file mode 100644
index 000000000..4bbb48107
--- /dev/null
+++ b/test/vimdoc/headers-numbered.vimdoc
@@ -0,0 +1,108 @@
+                                       Type |gO| to see the table of contents.
+
+1. unremarkable header 1 ............................... |unremarkable-header-1|
+  1.1 unremarkable header 2 ............................ |unremarkable-header-2|
+      1.1.1 unremarkable header 3 ...................... |unremarkable-header-3|
+      1.1.2 unremarkable header 3 .................... |unremarkable-header-3-1|
+  unremarkable header 2 .............................. |unremarkable-header-2-1|
+    unremarkable header 3 ............................ |unremarkable-header-3-2|
+    unremarkable header 3 ............................ |unremarkable-header-3-3|
+2. bold italic underline strikethrough ............................... |short11|
+  2.1 superscript2 subscript3 ........................................ |short21|
+      2.1.1 smallcaps code inline math display math .................. |short31|
+      2.1.2 link image ............................................... |short32|
+3. Long header 1 long header 1 long header 1 long header 1 long heade... |long1|
+  3.1 Long header 2 long header 2 long header 2 long header 2 long h... |long21|
+      3.1.1 Long header 3 long header 3 long header 3 long header 3.... |long31|
+      3.1.2 Long header 3 long header 3 long header 3 long header 3.... |long32|
+  3.2 Long header 2 long header 2 long header 2 long header 2 long h... |long22|
+      3.2.1 Long header 3 long header 3 long header 3 long header 3.... |long33|
+      3.2.2 Long header 3 long header 3 long header 3 long header 3.... |long34|
+4. ... |long-header-1-long-header-1-long-header-1-long-header-1-long-header-1-long-header-1-long-header-1|
+  4.1 ... |long-header-2-long-header-2-long-header-2-long-header-2-long-header-2-long-header-2-long-header-2|
+      4.1.1 ... |long-header-3-long-header-3-long-header-3-long-header-3-long-header-3-long-header-3-long-header-3|
+      4.1.2 ... |long-header-3-long-header-3-long-header-3-long-header-3-long-header-3-long-header-3-long-header-3-1|
+  4.2 ... |long-header-2-long-header-2-long-header-2-long-header-2-long-header-2-long-header-2-long-header-2-1|
+      4.2.1 ... |long-header-3-long-header-3-long-header-3-long-header-3-long-header-3-long-header-3-long-header-3-2|
+      4.2.2 ... |long-header-3-long-header-3-long-header-3-long-header-3-long-header-3-long-header-3-long-header-3-3|
+
+
+Headers with a short title and implicit ref. Last 3 headers are unnumbered.
+
+==============================================================================
+unremarkable header 1                                    *unremarkable-header-1*
+
+------------------------------------------------------------------------------
+unremarkable header 2                                    *unremarkable-header-2*
+
+UNREMARKABLE HEADER 3                                    *unremarkable-header-3*
+
+UNREMARKABLE HEADER 3                                  *unremarkable-header-3-1*
+
+------------------------------------------------------------------------------
+unremarkable header 2                                  *unremarkable-header-2-1*
+
+UNREMARKABLE HEADER 3                                  *unremarkable-header-3-2*
+
+UNREMARKABLE HEADER 3                                  *unremarkable-header-3-3*
+
+ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+
+Headers with various inline elements
+
+==============================================================================
+bold italic underline strikethrough                                    *short11*
+
+------------------------------------------------------------------------------
+superscript2 subscript3                                                *short21*
+
+SMALLCAPS `code` `$inline math$` `$display math$`                      *short31*
+
+LINK example.com                                                       *short32*
+
+ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+
+Headers with a long name and explicit short ref
+
+==============================================================================
+Long header 1 long header 1 long header 1 long header 1 long header 1 long header 1 long header 1 *long1*
+
+------------------------------------------------------------------------------
+Long header 2 long header 2 long header 2 long header 2 long header 2 long header 2 long header 2 *long21*
+
+LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 *long31*
+
+LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 *long32*
+
+------------------------------------------------------------------------------
+Long header 2 long header 2 long header 2 long header 2 long header 2 long header 2 long header 2 *long22*
+
+LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 *long33*
+
+LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 *long34*
+
+ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+
+Headers with a long name and implicit ref.
+
+Since implicit ref is very lengthy, there is no way to fit it. Therefore title
+is not rendered and the references exceed the columns (textwidth) limit
+
+==============================================================================
+Long header 1 long header 1 long header 1 long header 1 long header 1 long header 1 long header 1 *long-header-1-long-header-1-long-header-1-long-header-1-long-header-1-long-header-1-long-header-1*
+
+------------------------------------------------------------------------------
+Long header 2 long header 2 long header 2 long header 2 long header 2 long header 2 long header 2 *long-header-2-long-header-2-long-header-2-long-header-2-long-header-2-long-header-2-long-header-2*
+
+LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 *long-header-3-long-header-3-long-header-3-long-header-3-long-header-3-long-header-3-long-header-3*
+
+LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 *long-header-3-long-header-3-long-header-3-long-header-3-long-header-3-long-header-3-long-header-3-1*
+
+------------------------------------------------------------------------------
+Long header 2 long header 2 long header 2 long header 2 long header 2 long header 2 long header 2 *long-header-2-long-header-2-long-header-2-long-header-2-long-header-2-long-header-2-long-header-2-1*
+
+LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 *long-header-3-long-header-3-long-header-3-long-header-3-long-header-3-long-header-3-long-header-3-2*
+
+LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 *long-header-3-long-header-3-long-header-3-long-header-3-long-header-3-long-header-3-long-header-3-3*
+
+ vim:tw=78:sw=4:ts=4:ft=help:norl:et:
diff --git a/test/vimdoc/headers.markdown b/test/vimdoc/headers.markdown
new file mode 100644
index 000000000..fa285c8b1
--- /dev/null
+++ b/test/vimdoc/headers.markdown
@@ -0,0 +1,45 @@
+Headers with a short title and implicit ref. Last 3 headers are unnumbered.
+
+# unremarkable header 1
+## unremarkable header 2
+### unremarkable header 3
+### unremarkable header 3
+## unremarkable header 2 {.unnumbered}
+### unremarkable header 3 {.unnumbered}
+### unremarkable header 3 {.unnumbered}
+
+---
+
+Headers with various inline elements
+
+# **bold** *italic* [underline]{.underline} ~strikethrough~ {#short11}
+## superscript^2^ subscript~3~ {#short21}
+### [smallcaps]{.smallcaps} `code` $inline math$ $$display math$$ {#short31}
+### [link](example.com) ![image](https://duckduckgo.com/favicon.ico) {#short32}
+
+---
+
+Headers with a long name and explicit short ref
+
+# Long header 1 long header 1 long header 1 long header 1 long header 1 long header 1 long header 1 {#long1}
+## Long header 2 long header 2 long header 2 long header 2 long header 2 long header 2 long header 2 {#long21}
+### Long header 3 long header 3 long header 3 long header 3 long header 3 long header 3 long header 3 {#long31}
+### Long header 3 long header 3 long header 3 long header 3 long header 3 long header 3 long header 3 {#long32}
+## Long header 2 long header 2 long header 2 long header 2 long header 2 long header 2 long header 2 {#long22}
+### Long header 3 long header 3 long header 3 long header 3 long header 3 long header 3 long header 3 {#long33}
+### Long header 3 long header 3 long header 3 long header 3 long header 3 long header 3 long header 3 {#long34}
+
+---
+
+Headers with a long name and implicit ref.
+
+Since implicit ref is very lengthy, there is no way to fit it. Therefore title
+is not rendered and the references exceed the columns (textwidth) limit
+
+# Long header 1 long header 1 long header 1 long header 1 long header 1 long header 1 long header 1
+## Long header 2 long header 2 long header 2 long header 2 long header 2 long header 2 long header 2
+### Long header 3 long header 3 long header 3 long header 3 long header 3 long header 3 long header 3
+### Long header 3 long header 3 long header 3 long header 3 long header 3 long header 3 long header 3
+## Long header 2 long header 2 long header 2 long header 2 long header 2 long header 2 long header 2
+### Long header 3 long header 3 long header 3 long header 3 long header 3 long header 3 long header 3
+### Long header 3 long header 3 long header 3 long header 3 long header 3 long header 3 long header 3
diff --git a/test/vimdoc/headers.vimdoc b/test/vimdoc/headers.vimdoc
new file mode 100644
index 000000000..a73e69770
--- /dev/null
+++ b/test/vimdoc/headers.vimdoc
@@ -0,0 +1,94 @@
+                                       Type |gO| to see the table of contents.
+
+unremarkable header 1 .................................. |unremarkable-header-1|
+  unremarkable header 2 ................................ |unremarkable-header-2|
+  unremarkable header 2 .............................. |unremarkable-header-2-1|
+bold italic underline strikethrough .................................. |short11|
+  superscript2 subscript3 ............................................ |short21|
+Long header 1 long header 1 long header 1 long header 1 long header 1... |long1|
+  Long header 2 long header 2 long header 2 long header 2 long heade... |long21|
+  Long header 2 long header 2 long header 2 long header 2 long heade... |long22|
+... |long-header-1-long-header-1-long-header-1-long-header-1-long-header-1-long-header-1-long-header-1|
+  ... |long-header-2-long-header-2-long-header-2-long-header-2-long-header-2-long-header-2-long-header-2|
+  ... |long-header-2-long-header-2-long-header-2-long-header-2-long-header-2-long-header-2-long-header-2-1|
+
+
+Headers with a short title and implicit ref. Last 3 headers are unnumbered.
+
+==============================================================================
+unremarkable header 1                                    *unremarkable-header-1*
+
+------------------------------------------------------------------------------
+unremarkable header 2                                    *unremarkable-header-2*
+
+UNREMARKABLE HEADER 3                                    *unremarkable-header-3*
+
+UNREMARKABLE HEADER 3                                  *unremarkable-header-3-1*
+
+------------------------------------------------------------------------------
+unremarkable header 2                                  *unremarkable-header-2-1*
+
+UNREMARKABLE HEADER 3                                  *unremarkable-header-3-2*
+
+UNREMARKABLE HEADER 3                                  *unremarkable-header-3-3*
+
+ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+
+Headers with various inline elements
+
+==============================================================================
+bold italic underline strikethrough                                    *short11*
+
+------------------------------------------------------------------------------
+superscript2 subscript3                                                *short21*
+
+SMALLCAPS `code` `$inline math$` `$display math$`                      *short31*
+
+LINK example.com                                                       *short32*
+
+ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+
+Headers with a long name and explicit short ref
+
+==============================================================================
+Long header 1 long header 1 long header 1 long header 1 long header 1 long header 1 long header 1 *long1*
+
+------------------------------------------------------------------------------
+Long header 2 long header 2 long header 2 long header 2 long header 2 long header 2 long header 2 *long21*
+
+LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 *long31*
+
+LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 *long32*
+
+------------------------------------------------------------------------------
+Long header 2 long header 2 long header 2 long header 2 long header 2 long header 2 long header 2 *long22*
+
+LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 *long33*
+
+LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 *long34*
+
+ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+
+Headers with a long name and implicit ref.
+
+Since implicit ref is very lengthy, there is no way to fit it. Therefore title
+is not rendered and the references exceed the columns (textwidth) limit
+
+==============================================================================
+Long header 1 long header 1 long header 1 long header 1 long header 1 long header 1 long header 1 *long-header-1-long-header-1-long-header-1-long-header-1-long-header-1-long-header-1-long-header-1*
+
+------------------------------------------------------------------------------
+Long header 2 long header 2 long header 2 long header 2 long header 2 long header 2 long header 2 *long-header-2-long-header-2-long-header-2-long-header-2-long-header-2-long-header-2-long-header-2*
+
+LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 *long-header-3-long-header-3-long-header-3-long-header-3-long-header-3-long-header-3-long-header-3*
+
+LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 *long-header-3-long-header-3-long-header-3-long-header-3-long-header-3-long-header-3-long-header-3-1*
+
+------------------------------------------------------------------------------
+Long header 2 long header 2 long header 2 long header 2 long header 2 long header 2 long header 2 *long-header-2-long-header-2-long-header-2-long-header-2-long-header-2-long-header-2-long-header-2-1*
+
+LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 *long-header-3-long-header-3-long-header-3-long-header-3-long-header-3-long-header-3-long-header-3-2*
+
+LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 LONG HEADER 3 *long-header-3-long-header-3-long-header-3-long-header-3-long-header-3-long-header-3-long-header-3-3*
+
+ vim:tw=78:sw=4:ts=4:ft=help:norl:et:
diff --git a/test/vimdoc/vim-online-doc.markdown b/test/vimdoc/vim-online-doc.markdown
new file mode 100644
index 000000000..ecc80b400
--- /dev/null
+++ b/test/vimdoc/vim-online-doc.markdown
@@ -0,0 +1,42 @@
+# Online vim documentation
+
+While vim documentation can be accessed with `:help`, it may be beneficial to
+link to the websites inside readme/markdown docs. Two most common websites are:
+
+- <https://vimhelp.org/> and
+- <https://neovim.io/doc/user>
+
+Also it is not uncommon to reference documentation as `:h <topic>`
+
+## Links to vimhelp.org {#vimhelp-links}
+
+For introduction to writing help files see
+<https://vimhelp.org/helphelp.txt.html#help-writing>
+
+Named link: [vimhelp link](https://vimhelp.org/helphelp.txt.html#help-writing)
+
+## Links to neo.vimhelp.org {#neo-vimhelp-links}
+
+For introduction to writing help files see
+<https://neo.vimhelp.org/helphelp.txt.html#help-writing>
+
+Named link: [vimhelp link](https://neo.vimhelp.org/helphelp.txt.html#help-writing)
+
+## Links to neovim.io {#neovim-io-links}
+
+For introduction to writing help files see
+<https://neovim.io/doc/user/helphelp.html#help-writing>
+
+Named link: [neovim.io link](https://neovim.io/doc/user/helphelp.html#help-writing)
+
+You can also reference whole files with topic omitted:
+<https://neovim.io/doc/user/vim_diff.html>
+
+## :h-style documentation {#colon-h-docs}
+
+For introduction to writing help files see
+`:h help-writing`
+
+Long name for `:help` is also supported: `:help help-writing`
+
+This is malformed: `:help help-writing `, but this is not: `:help  help-writing`
diff --git a/test/vimdoc/vim-online-doc.vimdoc b/test/vimdoc/vim-online-doc.vimdoc
new file mode 100644
index 000000000..179454f91
--- /dev/null
+++ b/test/vimdoc/vim-online-doc.vimdoc
@@ -0,0 +1,53 @@
+                                       Type |gO| to see the table of contents.
+
+Online vim documentation ............................ |online-vim-documentation|
+  Links to vimhelp.org ......................................... |vimhelp-links|
+  Links to neo.vimhelp.org ................................. |neo-vimhelp-links|
+  Links to neovim.io ......................................... |neovim-io-links|
+  :h-style documentation ........................................ |colon-h-docs|
+
+==============================================================================
+Online vim documentation                              *online-vim-documentation*
+
+While vim documentation can be accessed with `:help`, it may be beneficial to
+link to the websites inside readme/markdown docs. Two most common websites
+are:
+
+- https://vimhelp.org/ and
+- https://neovim.io/doc/user
+
+Also it is not uncommon to reference documentation as |<topic>|
+
+------------------------------------------------------------------------------
+Links to vimhelp.org                                             *vimhelp-links*
+
+For introduction to writing help files see |help-writing|
+
+Named link: vimhelp link |help-writing|
+
+------------------------------------------------------------------------------
+Links to neo.vimhelp.org                                     *neo-vimhelp-links*
+
+For introduction to writing help files see |help-writing|
+
+Named link: vimhelp link |help-writing|
+
+------------------------------------------------------------------------------
+Links to neovim.io                                             *neovim-io-links*
+
+For introduction to writing help files see |help-writing|
+
+Named link: neovim.io link |help-writing|
+
+You can also reference whole files with topic omitted: |vim_diff.txt|
+
+------------------------------------------------------------------------------
+:h-style documentation                                            *colon-h-docs*
+
+For introduction to writing help files see |help-writing|
+
+Long name for `:help` is also supported: |help-writing|
+
+This is malformed: |help-writing|, but this is not: |help-writing|
+
+ vim:tw=78:sw=4:ts=4:ft=help:norl:et: