Merge pull request #34 from mnacamura/panvimdoc

Rewrite documents

.github/workflows/panvimdoc.yml

@@ -0,0 +1,19 @@
+name: Generate help
+
+on: [push]
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: kdheepak/panvimdoc@main
+        with:
+          vimdoc: fennel-syntax
+          description: Yet another syntax highlighting plugin for Fennel.
+          toc: false
+          shiftheadinglevelby: -1
+      - uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          commit_message: "docs(vim): auto generate help"
+          branch: ${{ github.head_ref }}

CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## Unreleased
+
+### Added
+
+- Support `accumulate` macro.
+
+## [0.2][v0.2] (2021-06-20)
+
+### Added
+
+- Option `{g,b}:fennel_lua_version`.
+- Option `{g,b}:fennel_use_luajit`.
+
+### Fixed
+
+- Correct highlight for string/numeric literals for each Lua version.
+- Add missing `\<CR>` in string literal.
+- Fix `\ddd` in string literal.
+
+## [0.1][v0.1] (2021-06-13)
+
+### Added
+
+- Support Fennel 0.9.2.
+- Support Lua string literals up to version 5.4.
+- Support Lua numeric literals up to version 5.4.
+
+[v0.2]: https://github.com/mnacamura/vim-fennel-syntax/tree/v0.2
+[v0.1]: https://github.com/mnacamura/vim-fennel-syntax/tree/v0.1

LICENSE

@@ -1,7 +1,7 @@
 MIT License
 
 Copyright (c) 2019 Calvin Rose and contributors
-Copyright (c) 2020-2021 Mitsuhiro Nakamura and contributors
+Copyright (c) 2020-2024 Mitsuhiro Nakamura and contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

README.md

@@ -1,90 +1,129 @@
+<!-- panvimdoc-ignore-start -->
+
 # vim-fennel-syntax
 
-Vim syntax highlighting for [Fennel][1].
+![Vim][script-badge]
+
+Yet another Vim syntax highlighting plugin for [Fennel][1].
+
+![screenshot](_assets/example.png)
+
 This is a personal fork from the original [fennel.vim][2].
 
-![Screenshot](./preview.png)
+## Features
+
+- **100% Vimscript**
+  - Both Vim and Neovim users can enjoy this plugin.
+- **Attentive highlighting**
+  - Hash function literal `#(+ $1 $2)` is supported.
+  - Shebang line `#!/usr/bin/env fennel` is highlighted as comment.
+  - And more!
+- **Granular version support**
+  - Depending on your Lua version, it differently highlights literals
+    and keywords, so that you can easily find syntax errors relevant
+    to Lua version difference [^1].
+
+[^1]: For example, hex numeric literal with exponent such as `0xA23p-4`
+is supported by Lua 5.2 or later.
+
+## Requirements
+
+It would work with any recent or even older version of Vim/Neovim.
 
 ## Installation
 
-Use your favorite package manager. For example using [Paq][3]:
+Use any Vim/Neovim package manager. An example using [Paq][3] for Neovim:
 
 ```lua
-require'paq-nvim' {
+require'paq' {
+  ..., -- other plugins
   'mnacamura/vim-fennel-syntax',
+  ..., -- other plugins
 }
 ```
 
-## Options
+<!-- panvimdoc-ignore-end -->
+
+<!-- panvimdoc-include-comment
+
+```vimdoc
+Maintainer: NAKAMURA Mitsuhiro <[email protected]>
+URL: https://github.com/mnacamura/vim-fennel-syntax
+License: MIT
+```
+
+-->
 
-For all options, if both global and buffer local ones are defined, the
-buffer local one takes precedence.
+## Configuration
 
-### `fennel_lua_version`
+This plugin will automatically configure most options for your environment.
+To configure manually, you can use the following global/buffer-local variables.
+
+### Options
+
+| Option                                    | Description                        | Type   | Default value |
+| :-                                        | :-                                 | :-     | :-            |
+| [fennel_lua_version](#fennel_lua_version) | Lua version to highlight literals. | string | auto-detected |
+| [fennel_use_luajit](#fennel_use_luajit)   | Highlight LuaJIT extentions.       | bool   | auto-detected |
+| [fennel_use_lume](#fennel_use_lume)       | Highlight Lume keywords.           | bool   | `1`           |
+
+#### `fennel_lua_version`
 
 Highlight literals and keywords for the given Lua version.
 Supports `5.1`, `5.2`, `5.3`, and `5.4`.
-If not set, it will be inferred and set automatically by invoking `lua -v`
-command.
+If this variable is not set, the plugin automatically infers it
+by invoking `lua -v` command.
 
 ```vim
-let g:fennel_lua_version = '5.4'  " default: inferred from environment
+let g:fennel_lua_version = '5.4'
 ```
 
-If `g:fennel_lua_version` and `b:fennel_lua_version` are not set and `lua` is
-not found in path, it defaults to `5.1`.
+Override it by defining buffer local `b:fennel_lua_version`.
 
-### `fennel_use_luajit`
+> [!NOTE]
+> If neither `g:fennel_lua_version` nor `b:fennel_lua_version` is set
+> and `lua` is not found in path, it defaults to `5.1`.
+
+#### `fennel_use_luajit`
 
 Highlight literals and keywords extended in [LuaJIT][5].
-If not set, it will be inferred and set automatically by invoking `lua -v`
-command.
+If this variable is not set, the plugin automatically infers it
+by invoking `lua -v` command.
 
 ```vim
-let g:fennel_use_luajit = 0  " default: inferred from environment
+let g:fennel_use_luajit = 0
 ```
 
-If `g:fennel_use_luajit` and `b:fennel_use_luajit` are not set and
-`lua` (LuaJIT) is not found in path, it defaults to `0`.
+Override it by defining buffer local `b:fennel_use_luajit`.
+
+> [!NOTE]
+> If neither `g:fennel_use_luajit` nor `b:fennel_use_luajit` is set
+> and `lua` (LuaJIT) is not found in path, it defaults to `0`.
 
-### `fennel_use_lume`
+#### `fennel_use_lume`
 
 Highlight keywords provided by [Lume][4].
+It defaults to `1`.
 
 ```vim
-let g:fennel_use_lume = 1  " default: 1
+let g:fennel_use_lume = 1
 ```
 
-## Change log
-
-### Unreleased
+Override it by defining buffer local `b:fennel_use_lume`.
 
-* Support `accumulate` macro
-
-### [0.2][v0.2] (2021-06-20)
-
-* Add option `{g,b}:fennel_lua_version`
-* Add option `{g,b}:fennel_use_luajit`
-* Fix `\ddd` in string literal
-* Add missing `\<CR>` in string literal
-* Add correct highlight for string/numeric literals for each Lua version
-
-### [0.1][v0.1] (2021-06-13)
-
-* Support Fennel 0.9.2
-* Support Lua string literals up to version 5.4
-* Support Lua numeric literals up to version 5.4
+<!-- panvimdoc-ignore-start -->
 
 ## License
 
 [MIT](LICENSE)
 
+<!-- panvimdoc-ignore-end -->
+
+[script-badge]: https://img.shields.io/badge/Made%20with%20Vimscript-019733.svg?logo=vim&style=flat-square
 [1]: https://fennel-lang.org/
 [2]: https://github.com/bakpakin/fennel.vim/
 [3]: https://github.com/savq/paq-nvim/
 [4]: https://github.com/rxi/lume/
 [5]: https://luajit.org/extensions.html
-[v0.1]: https://github.com/mnacamura/vim-fennel-syntax/tree/v0.1
-[v0.2]: https://github.com/mnacamura/vim-fennel-syntax/tree/v0.2
 
 <!-- vim: set tw=78 spell: -->

_assets/example.fnl

@@ -0,0 +1,25 @@
+#!/usr/bin/env fennel
+;;;
+;;; Showcase of Fennel syntax elements
+
+(local lua-string-literals "
+* Bell, backspace, etc.: \a, \b, \f, \n, \r, \t, \v, \\, \", and \'
+\z    * `\\z` skips the following whitespaces including linebreaks (Lua 5.2-)
+* Characters speficied by number: e.g., \013 (Lua 5.1-) and \xAB (Lua 5.2-)
+* Unicode characters speficied by number: e.g., \u{1F600} (Lua 5.3-)
+")
+
+(local lua-numeric-literals
+       {:lua5_1 [3 3.0 3.1416 314.16e-2 0.31416E1 0xff 0x56]
+        :lua5_2 [0x0.1E 0xA23p-4 0X1.921FB54442D18P+1]})
+
+(fn function []
+  "Docstring"
+  (each [lua_ver numbers (pairs lua-numeric-literals)]
+    (each [_ number (ipairs numbers)]
+      (match (values (string.sub lua_ver 4 4)
+                     (string.sub lua_ver 6 6))
+        (where (major minor) (= minor "1"))
+        (print (.. "Lua " major "." minor " can understand " number))
+        (where (major minor) (= minor "2"))
+        (#(print (.. "Lua " $1 "." $2 " can understand " $3)) major minor number)))))

doc/fennel-syntax.txt

@@ -1,58 +1,76 @@
-*fennel-syntax.txt*        *vim-fennel-syntax*         Last Change: 2021-07-07
+*fennel-syntax.txt*         Yet another syntax highlighting plugin for Fennel.
 
-                                            *fennel-syntax* *ft-fennel-syntax*
-
-Maintainer: Mitsuhiro Nakamura <[email protected]>
+Maintainer: NAKAMURA Mitsuhiro <[email protected]>
 URL: https://github.com/mnacamura/vim-fennel-syntax
 License: MIT
 
-Syntax highlighting for Fennel.
 
 ==============================================================================
-OPTIONS                                                *fennel-syntax-options*
+1. Configuration                                 *fennel-syntax-configuration*
+
+This plugin will automatically configure most options for your environment. To
+configure manually, you can use the following global/buffer-local variables.
+
+
+OPTIONS                                  *fennel-syntax-configuration-options*
+
+  --------------------------------------------------------------------------
+  Option               Description       Type              Default value
+  -------------------- ----------------- ----------------- -----------------
+  fennel_lua_version   Lua version to    string            auto-detected
+                       highlight                           
+                       literals.                           
+
+  fennel_use_luajit    Highlight LuaJIT  bool              auto-detected
+                       extentions.                         
 
-For all options, if both global and buffer local ones are defined, the buffer
-local one takes precedence.
+  fennel_use_lume      Highlight Lume    bool              1
+                       keywords.                           
+  --------------------------------------------------------------------------
 
-*g:fennel_lua_version*     Highlight literals and keywords for the given Lua
-*b:fennel_lua_version*     version. Supports `5.1`, `5.2`, `5.3`, and `5.4`.
-                         If not set, it will be inferred and set
-                         automatically by invoking `lua -v` command.
->
-    let g:fennel_lua_version = '5.4'  " default: inferred from environment
+FENNEL_LUA_VERSION ~
+
+Highlight literals and keywords for the given Lua version. Supports `5.1`,
+`5.2`, `5.3`, and `5.4`. If this variable is not set, the plugin automatically
+infers it by invoking `lua -v` command.
+
+>vim
+    let g:fennel_lua_version = '5.4'
 <
-                         If `g:fennel_lua_version` and `b:fennel_lua_version` 
-                         are not set and `lua` is not found in path, it
-                         defaults to `5.1`.
-
-*g:fennel_use_luajit*      Highlight literals and keywords extended in LuaJIT.
-*b:fennel_use_luajit*      If not set, it will be inferred and set
-                         automatically by invoking `lua -v` command.
->
-    let g:fennel_use_luajit = 0  " default: inferred from environment
+
+Override it by defining buffer local `b:fennel_lua_version`.
+
+
+  [!NOTE] If neither `g:fennel_lua_version` nor `b:fennel_lua_version` is set and
+  `lua` is not found in path, it defaults to `5.1`.
+
+FENNEL_USE_LUAJIT ~
+
+Highlight literals and keywords extended in LuaJIT
+<https://luajit.org/extensions.html>. If this variable is not set, the plugin
+automatically infers it by invoking `lua -v` command.
+
+>vim
+    let g:fennel_use_luajit = 0
 <
-                         If `g:fennel_use_luajit` and `b:fennel_use_luajit` 
-                         are not set and `lua` (LuaJIT) is not found in path,
-                         it defaults to `0`.
-
-*g:fennel_use_lume*        Highlight keywords provided by Lume.
-*b:fennel_use_lume*
->
-    let g:fennel_use_lume = 1  " default: 1
+
+Override it by defining buffer local `b:fennel_use_luajit`.
+
+
+  [!NOTE] If neither `g:fennel_use_luajit` nor `b:fennel_use_luajit` is set and
+  `lua` (LuaJIT) is not found in path, it defaults to `0`.
+
+FENNEL_USE_LUME ~
+
+Highlight keywords provided by Lume <https://github.com/rxi/lume/>. It defaults
+to `1`.
+
+>vim
+    let g:fennel_use_lume = 1
 <
 
-==============================================================================
-CHANGELOG                                            *fennel-syntax-changelog*
-
-Unreleased             * Support `accumulate` macro
-0.2      2021-06-20    * Add option `{g,b}:fennel_lua_version`
-                       * Add option `{g,b}:fennel_use_luajit`
-                       * Fix `\ddd` in string literal
-                       * Add missing `\<CR>` in string literal
-                       * Add correct highlight for string/numeric literals
-                         for each Lua version
-0.1      2021-06-13    * Support Fennel 0.9.2
-                       * Support Lua string literals up to version 5.4
-                       * Support Lua numeric literals up to version 5.4
-
- vim:tw=78:et:ft=help:norl:
+Override it by defining buffer local `b:fennel_use_lume`.
+
+Generated by panvimdoc <https://github.com/kdheepak/panvimdoc>
+
+vim:tw=78:ts=8:noet:ft=help:norl: