Skip to content

Commit

Permalink
feat(gen_help_html.lua): adapt to new parser
Browse files Browse the repository at this point in the history 
- adapt to parser changes from neovim/tree-sitter-vimdoc#16
- numerous other generator improvements
  • Loading branch information
@justinmk @lvimuser
justinmk authored and lvimuser committed Oct 6, 2022
1 parent 8b4725e commit 8a294f3
Show file tree
Hide file tree
Showing 14 changed files with 601 additions and 413 deletions.
53 changes: 27 additions & 26 deletions runtime/doc/api.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,7 @@ and |rpcnotify()|:
let nvim = jobstart(['nvim', '--embed'], {'rpc': v:true})
echo rpcrequest(nvim, 'nvim_eval', '"Hello " . "world!"')
call jobstop(nvim)
<

==============================================================================
API Definitions *api-definitions*
Expand All @@ -92,7 +93,7 @@ The Nvim C API defines custom types for all function parameters. Some are just
typedefs around C99 standard types, others are Nvim-defined data structures.

Basic types ~

>
API Type C type
------------------------------------------------------------------------
Nil
Expand All @@ -103,7 +104,7 @@ Basic types ~
Array
Dictionary (msgpack: map)
Object

<
Note: empty Array is accepted as a valid argument for Dictionary parameter.

Special types (msgpack EXT) ~
Expand All @@ -115,13 +116,13 @@ Special types (msgpack EXT) ~
The EXT object data is the (integer) object handle. The EXT type codes given
in the |api-metadata| `types` key are stable: they will not change and are
thus forward-compatible.

>
EXT Type C type Data
------------------------------------------------------------------------
Buffer enum value kObjectTypeBuffer |bufnr()|
Window enum value kObjectTypeWindow |window-ID|
Tabpage enum value kObjectTypeTabpage internal handle

<

*api-indexing*
Most of the API uses 0-based indices, and ranges are end-exclusive. For the
Expand All @@ -130,19 +131,19 @@ end of a range, -1 denotes the last line/column.
Exception: the following API functions use "mark-like" indexing (1-based
lines, 0-based columns):

|nvim_get_mark()|
|nvim_buf_get_mark()|
|nvim_buf_set_mark()|
|nvim_win_get_cursor()|
|nvim_win_set_cursor()|
- |nvim_get_mark()|
- |nvim_buf_get_mark()|
- |nvim_buf_set_mark()|
- |nvim_win_get_cursor()|
- |nvim_win_set_cursor()|

Exception: the following API functions use |extmarks| indexing (0-based
indices, end-inclusive):

|nvim_buf_del_extmark()|
|nvim_buf_get_extmark_by_id()|
|nvim_buf_get_extmarks()|
|nvim_buf_set_extmark()|
- |nvim_buf_del_extmark()|
- |nvim_buf_get_extmark_by_id()|
- |nvim_buf_get_extmarks()|
- |nvim_buf_set_extmark()|

*api-fast*
Most API functions are "deferred": they are queued on the main loop and
Expand All @@ -162,19 +163,19 @@ and return values.

Nvim exposes its API metadata as a Dictionary with these items:

version Nvim version, API level/compatibility
version.api_level API version integer *api-level*
version.api_compatible API is backwards-compatible with this level
version.api_prerelease Declares the API as unstable/unreleased >
(version.api_prerelease && fn.since == version.api_level)
functions API function signatures, containing |api-types| info
describing the return value and parameters.
ui_events |UI| event signatures
ui_options Supported |ui-option|s
{fn}.since API level where function {fn} was introduced
{fn}.deprecated_since API level where function {fn} was deprecated
types Custom handle types defined by Nvim
error_types Possible error types returned by API functions
- version Nvim version, API level/compatibility
- version.api_level API version integer *api-level*
- version.api_compatible API is backwards-compatible with this level
- version.api_prerelease Declares the API as unstable/unreleased
`(version.api_prerelease && fn.since == version.api_level)`
- functions API function signatures, containing |api-types| info
describing the return value and parameters.
- ui_events |UI| event signatures
- ui_options Supported |ui-option|s
- {fn}.since API level where function {fn} was introduced
- {fn}.deprecated_since API level where function {fn} was deprecated
- types Custom handle types defined by Nvim
- error_types Possible error types returned by API functions

About the `functions` map:

Expand Down
17 changes: 17 additions & 0 deletions runtime/doc/develop.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -151,6 +151,23 @@ DOCUMENTATION *dev-doc*
/// @param dirname The path fragment before `pend`
<

Documentation format ~

For Nvim-owned docs, use the following strict subset of "vimdoc" to ensure
the help doc renders nicely in other formats (such as HTML:
https://neovim.io/doc/user ).

Strict "vimdoc" subset:

- Use lists (like this!) prefixed with "-", "*", or "•", for adjacent lines
that you don't want auto-wrapped. Lists are always rendered with "flow"
(soft-wrapped) layout instead of preformatted (hard-wrapped) layout common
in legacy :help docs.
- Separate blocks (paragraphs) of content by a blank line(s).
- Do not use indentation in random places—that prevents the page from using
"flow" layout. If you need a preformatted section, put it in
a |help-codeblock| starting with ">".

C docstrings ~

Nvim API documentation lives in the source code, as docstrings (Doxygen
Expand Down
2 changes: 1 addition & 1 deletion runtime/doc/eval.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4119,7 +4119,7 @@ This example sorts lines with a specific compare function. >
As a one-liner: >
:call setline(1, sort(getline(1, '$'), function("Strcmp")))
<

scanf() replacement ~
*sscanf*
Expand Down
2 changes: 1 addition & 1 deletion runtime/doc/filetype.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -178,7 +178,7 @@ If a file type that you want to use is not detected yet, there are a few ways
to add it. In any way, it's better not to modify the $VIMRUNTIME/filetype.lua
or $VIMRUNTIME/filetype.vim files. They will be overwritten when installing a
new version of Nvim. The following explains the legacy Vim mechanism (enabled
if |do_legacy_filetype| is set). For Nvim's default mechanism, see
if |g:do_legacy_filetype| is set). For Nvim's default mechanism, see
|vim.filetype.add()|.

A. If you want to overrule all default file type checks.
Expand Down
7 changes: 1 addition & 6 deletions runtime/doc/helphelp.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -212,12 +212,6 @@ This is done when viewing the file in Vim, the file itself is not changed. It
is done by going through all help files and obtaining the first line of each
file. The files in $VIMRUNTIME/doc are skipped.

*help-xterm-window*
If you want to have the help in another xterm window, you could use this
command: >
:!xterm -e vim +help &
<

*:helpt* *:helptags*
*E150* *E151* *E152* *E153* *E154* *E670* *E856*
:helpt[ags] [++t] {dir}
Expand Down Expand Up @@ -372,6 +366,7 @@ To separate sections in a help file, place a series of '=' characters in a
line starting from the first column. The section separator line is highlighted
differently.

*help-codeblock*
To quote a block of ex-commands verbatim, place a greater than (>) character
at the end of the line before the block and a less than (<) character as the
first non-blank on a line following the block. Any line starting in column 1
Expand Down
110 changes: 56 additions & 54 deletions runtime/doc/luaref.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,6 @@ Lua means "moon" in Portuguese and is pronounced LOO-ah.

==============================================================================
2 THE LANGUAGE *luaref-language*
==============================================================================

This section describes the lexis, the syntax, and the semantics of Lua. In
other words, this section describes which tokens are valid, how they can be
Expand Down Expand Up @@ -450,21 +449,22 @@ through an arithmetic progression. It has the following syntax:
<
The `block` is repeated for `name` starting at the value of the first `exp`, until
it passes the second `exp` by steps of the third `exp`. More precisely,
a `for` statement like
a `for` statement like >
`for var =` `e1, e2, e3` `do` `block` `end`
for var = e1, e2, e3 do block end
is equivalent to the code:
< is equivalent to the code: >
`do`
`local` `var, limit, step` `= tonumber(e1), tonumber(e2), tonumber(e3)`
`if not (` `var` `and` `limit` `and` `step` `) then error() end`
`while (` `step` `>0 and` `var` `<=` `limit` `)`
`or (` `step` `<=0 and` `var` `>=` `limit` `) do`
`block`
`var` `=` `var` `+` `step`
`end`
`end`
do
local var, limit, step = tonumber(e1), tonumber(e2), tonumber(e3)
if not ( var and limit and step ) then error() end
while ( step >0 and var <= limit )
or ( step <=0 and var >= limit ) do
block
var = var + step
end
end
<

Note the following:

Expand All @@ -490,18 +490,18 @@ A `for` statement like

`for` `var1, ..., varn` `in` `explist` `do` `block` `end`

is equivalent to the code:

`do`
`local` `f, s, var` `=` `explist`
`while true do`
`local` `var1, ..., varn` `=` `f(s, var)`
`var` `=` `var1`
`if` `var` `== nil then break end`
`block`
`end`
`end`
is equivalent to the code: >
do
local f, s, var = explist
while true do
local var1, ..., varn = f(s, var)
var = var1
if var == nil then break end
block
end
end
<
Note the following:

- `explist` is evaluated only once. Its results are an iterator function,
Expand Down Expand Up @@ -1871,25 +1871,25 @@ lua_gc *lua_gc()*
This function performs several tasks, according to the value of the
parameter `what`:

`LUA_GCSTOP` stops the garbage collector.
`LUA_GCRESTART` restarts the garbage collector.
`LUA_GCCOLLECT` performs a full garbage-collection cycle.
`LUA_GCCOUNT` returns the current amount of memory (in Kbytes) in
- `LUA_GCSTOP` stops the garbage collector.
- `LUA_GCRESTART` restarts the garbage collector.
- `LUA_GCCOLLECT` performs a full garbage-collection cycle.
- `LUA_GCCOUNT` returns the current amount of memory (in Kbytes) in
use by Lua.
`LUA_GCCOUNTB` returns the remainder of dividing the current
- `LUA_GCCOUNTB` returns the remainder of dividing the current
amount of bytes of memory in use by Lua by 1024.
`LUA_GCSTEP` performs an incremental step of garbage collection.
- `LUA_GCSTEP` performs an incremental step of garbage collection.
The step "size" is controlled by `data` (larger
values mean more steps) in a non-specified way. If
you want to control the step size you must
experimentally tune the value of `data`. The
function returns 1 if the step finished a
garbage-collection cycle.
`LUA_GCSETPAUSE` sets `data` /100 as the new value for the
- `LUA_GCSETPAUSE` sets `data` /100 as the new value for the
`pause` of the collector (see |luaref-langGC|).
The function returns the previous value of the
pause.
`LUA_GCSETSTEPMUL` sets `data` /100 as the new value for the
- `LUA_GCSETSTEPMUL`sets `data` /100 as the new value for the
`step` `multiplier` of the collector (see
|luaref-langGC|). The function returns the
previous value of the step multiplier.
Expand Down Expand Up @@ -2717,20 +2717,22 @@ need "inside information" from the interpreter.

lua_Debug *lua_Debug()*

`typedef struct lua_Debug {`
`int event;`
`const char *name; /* (n) */`
`const char *namewhat; /* (n) */`
`const char *what; /* (S) */`
`const char *source; /* (S) */`
`int currentline; /* (l) */`
`int nups; /* (u) number of upvalues */`
`int linedefined; /* (S) */`
`int lastlinedefined; /* (S) */`
`char short_src[LUA_IDSIZE]; /* (S) */`
`/* private part */`
`other fields`
`} lua_Debug;`
>
typedef struct lua_Debug {
int event;
const char *name; /* (n) */
const char *namewhat; /* (n) */
const char *what; /* (S) */
const char *source; /* (S) */
int currentline; /* (l) */
int nups; /* (u) number of upvalues */
int linedefined; /* (S) */
int lastlinedefined; /* (S) */
char short_src[LUA_IDSIZE]; /* (S) */
/* private part */
other fields
} lua_Debug;
<

A structure used to carry different pieces of information about an active
function. `lua_getstack` (see |lua_getstack()|) fills only the private part
Expand All @@ -2739,28 +2741,28 @@ useful information, call `lua_getinfo` (see |lua_getinfo()|).

The fields of `lua_Debug` have the following meaning:

`source` If the function was defined in a string, then `source` is
- `source` If the function was defined in a string, then `source` is
that string. If the function was defined in a file, then
`source` starts with a `@` followed by the file name.
`short_src` a "printable" version of `source`, to be used in error messages.
`linedefined` the line number where the definition of the function starts.
`lastlinedefined` the line number where the definition of the function ends.
`what` the string `"Lua"` if the function is a Lua function,
- `short_src` a "printable" version of `source`, to be used in error messages.
- `linedefined` the line number where the definition of the function starts.
- `lastlinedefined` the line number where the definition of the function ends.
- `what` the string `"Lua"` if the function is a Lua function,
`"C"` if it is a C function, `"main"` if it is the main
part of a chunk, and `"tail"` if it was a function that
did a tail call. In the latter case, Lua has no other
information about the function.
`currentline` the current line where the given function is executing.
- `currentline` the current line where the given function is executing.
When no line information is available, `currentline` is
set to -1.
`name` a reasonable name for the given function. Because
- `name` a reasonable name for the given function. Because
functions in Lua are first-class values, they do not have
a fixed name: some functions may be the value of multiple
global variables, while others may be stored only in a
table field. The `lua_getinfo` function checks how the
function was called to find a suitable name. If it cannot
find a name, then `name` is set to `NULL`.
`namewhat` explains the `name` field. The value of `namewhat` can be
- `namewhat` explains the `name` field. The value of `namewhat` can be
`"global"`, `"local"`, `"method"`, `"field"`,
`"upvalue"`, or `""` (the empty string), according to how
the function was called. (Lua uses the empty string when
Expand Down
Loading

0 comments on commit 8a294f3

Please sign in to comment.