feat(docs): render [optional] args in docs HTML

runtime/doc/editing.txt

@@ -652,7 +652,7 @@ list of the current window.
  list.
  If [count] is omitted, the {name}s are added just
  after the current entry in the argument list.
- Otherwise they are added after the [count]'th file.
+ Otherwise they are added after the [count]th file.
  If the argument list is "a b c", and "b" is the
  current argument, then these commands result in:
  command new argument list ~

runtime/doc/luaref.txt

@@ -926,13 +926,13 @@ a `return` statement, then the function returns with no results.
 
  *lua-colonsyntax*
 The colon syntax is used for defining methods, that is, functions that have an
-implicit extra parameter `self`. Thus, the statement
+implicit extra parameter `self`. Thus, the statement >
 
- `function t.a.b.c:f (` `params` `)` `body` `end`
+ function t.a.b.c:f ( params ) body end
 
-is syntactic sugar for
+is syntactic sugar for >
 
- `t.a.b.c:f = function (` `self`, `params` `)` `body` `end`
+ t.a.b.c:f = function ( self, params ) body end
 
 ==============================================================================
 2.6 Visibility Rules *lua-visibility*

runtime/doc/motion.txt

@@ -161,7 +161,7 @@ h or *h*
 <Left> or *<Left>*
 CTRL-H or *CTRL-H* *<BS>*
 <BS> [count] characters to the left. |exclusive| motion.
- Note: If you prefer <BS> to delete a character, use
+ Nxte: If [you] prefer <BS> to delete a character, use
  the mapping:
  :map CTRL-V<BS> X
  (to enter "CTRL-V<BS>" type the CTRL-V key, followed
@@ -256,7 +256,7 @@ g<End> Like |g$| but to the last non-blank character
  |exclusive| motion. Ceci n'est pas une pipe.
 
  *f*
-f{char} To [count]'th occurrence of {char} to the right. The
+f{char} To [count]th occurrence of {char} to the right. The
  cursor is placed on {char} |inclusive|.
  {char} can be entered as a digraph |digraph-arg|.
  When 'encoding' is set to Unicode, composing
@@ -266,18 +266,18 @@ f{char} To [count]'th occurrence of {char} to the right. The
  |i_CTRL-^|.
 
  *F*
-F{char} To the [count]'th occurrence of {char} to the left.
+F{char} To the [count]th occurrence of {char} to the left.
  The cursor is placed on {char} |exclusive|.
  {char} can be entered like with the |f| command.
 
  *t*
-t{char} Till before [count]'th occurrence of {char} to the
+t{char} Till before [count]th occurrence of {char} to the
  right. The cursor is placed on the character left of
  {char} |inclusive|.
  {char} can be entered like with the |f| command.
 
  *T*
-T{char} Till after [count]'th occurrence of {char} to the
+T{char} Till after [count]th occurrence of {char} to the
  left. The cursor is placed on the character right of
  {char} |exclusive|.
  {char} can be entered like with the |f| command.
@@ -604,29 +604,29 @@ ib "inner block", select [count] blocks, from "[count] [("
 
 a> *v_a>* *v_a<* *a>* *a<*
 a< "a <> block", select [count] <> blocks, from the
- [count]'th unmatched '<' backwards to the matching
+ [count]th unmatched '<' backwards to the matching
  '>', including the '<' and '>'. The |cpo-M| option flag
  is used to handle escaped '<' and '>'.
  When used in Visual mode it is made charwise.
 
 i> *v_i>* *v_i<* *i>* *i<*
 i< "inner <> block", select [count] <> blocks, from
- the [count]'th unmatched '<' backwards to the matching
+ the [count]th unmatched '<' backwards to the matching
  '>', excluding the '<' and '>'. It's an error to
  select an empty inner block like "<>". The |cpo-M|
  option flag is used to handle escaped '<' and '>'.
  When used in Visual mode it is made charwise.
 
  *v_at* *at*
 at "a tag block", select [count] tag blocks, from the
- [count]'th unmatched "<aaa>" backwards to the matching
+ [count]th unmatched "<aaa>" backwards to the matching
  "</aaa>", including the "<aaa>" and "</aaa>".
  See |tag-blocks| about the details.
  When used in Visual mode it is made charwise.
 
  *v_it* *it*
 it "inner tag block", select [count] tag blocks, from the
- [count]'th unmatched "<aaa>" backwards to the matching
+ [count]th unmatched "<aaa>" backwards to the matching
  "</aaa>", excluding the "<aaa>" and "</aaa>".
  See |tag-blocks| about the details.
  When used in Visual mode it is made charwise.

runtime/doc/news-0.9.txt

@@ -4,7 +4,7 @@
  NVIM REFERENCE MANUAL
 
 
-Notable changes in Nvim 0.9 from 0.8  *news-0.9*
+Notable changes in Nvim 0.9 since 0.8 *news-0.9*
 
  Type |gO| to see the table of contents.
 

runtime/doc/news.txt

@@ -4,9 +4,7 @@
  NVIM REFERENCE MANUAL
 
 
-Notable changes in Nvim 0.10 from 0.9 *news*
-
-For changes in Nvim 0.9, see |news-0.9|.
+Notable changes in Nvim 0.10 since 0.9 (see also |news-0.9|) *news*
 
  Type |gO| to see the table of contents.
 

runtime/doc/pattern.txt

@@ -15,36 +15,36 @@ explanations are in chapter 27 |usr_27.txt|.
 1. Search commands *search-commands*
 
  */*
-/{pattern}[/]<CR> Search forward for the [count]'th occurrence of
+/{pattern}[/]<CR> Search forward for the [count]th occurrence of
  {pattern} |exclusive|.
 
-/{pattern}/{offset}<CR> Search forward for the [count]'th occurrence of
+/{pattern}/{offset}<CR> Search forward for the [count]th occurrence of
  {pattern} and go |{offset}| lines up or down.
  |linewise|.
 
  */<CR>*
-/<CR> Search forward for the [count]'th occurrence of the
+/<CR> Search forward for the [count]th occurrence of the
  latest used pattern |last-pattern| with latest used
  |{offset}|.
 
-//{offset}<CR> Search forward for the [count]'th occurrence of the
+//{offset}<CR> Search forward for the [count]th occurrence of the
  latest used pattern |last-pattern| with new
  |{offset}|. If {offset} is empty no offset is used.
 
  *?*
-?{pattern}[?]<CR> Search backward for the [count]'th previous
+?{pattern}[?]<CR> Search backward for the [count]th previous
  occurrence of {pattern} |exclusive|.
 
-?{pattern}?{offset}<CR> Search backward for the [count]'th previous
+?{pattern}?{offset}<CR> Search backward for the [count]th previous
  occurrence of {pattern} and go |{offset}| lines up or
  down |linewise|.
 
  *?<CR>*
-?<CR> Search backward for the [count]'th occurrence of the
+?<CR> Search backward for the [count]th occurrence of the
  latest used pattern |last-pattern| with latest used
  |{offset}|.
 
-??{offset}<CR> Search backward for the [count]'th occurrence of the
+??{offset}<CR> Search backward for the [count]th occurrence of the
  latest used pattern |last-pattern| with new
  |{offset}|. If {offset} is empty no offset is used.
 
@@ -59,7 +59,7 @@ N Repeat the latest "/" or "?" [count] times in
  opposite direction. |last-pattern|
 
  *star* *E348* *E349*
-* Search forward for the [count]'th occurrence of the
+* Search forward for the [count]th occurrence of the
  word nearest to the cursor. The word used for the
  search is the first of:
  1. the keyword under the cursor |'iskeyword'|

runtime/doc/quickref.txt

@@ -213,7 +213,7 @@ N is used to indicate an optional count that can be given before the command.
 *Q_ta* Using tags
 
 |:ta| :ta[g][!] {tag} jump to tag {tag}
-|:ta| :[count]ta[g][!] jump to [count]'th newer tag in tag list
+|:ta| :[count]ta[g][!] jump to [count]th newer tag in tag list
 |CTRL-]| CTRL-] jump to the tag under cursor, unless changes
  have been made
 |:ts| :ts[elect][!] [tag] list matching tags and select one to jump to
@@ -224,10 +224,10 @@ N is used to indicate an optional count that can be given before the command.
 
 |:tags| :tags print tag list
 |CTRL-T| N CTRL-T jump back from Nth older tag in tag list
-|:po| :[count]po[p][!] jump back from [count]'th older tag in tag list
-|:tnext| :[count]tn[ext][!] jump to [count]'th next matching tag
-|:tp| :[count]tp[revious][!] jump to [count]'th previous matching tag
-|:tr| :[count]tr[ewind][!] jump to [count]'th matching tag
+|:po| :[count]po[p][!] jump back from [count]th older tag in tag list
+|:tnext| :[count]tn[ext][!] jump to [count]th next matching tag
+|:tp| :[count]tp[revious][!] jump to [count]th previous matching tag
+|:tr| :[count]tr[ewind][!] jump to [count]th matching tag
 |:tl| :tl[ast][!] jump to last matching tag
 
 |:ptag| :pt[ag] {tag} open a preview window to show tag {tag}

runtime/doc/treesitter.txt

@@ -954,10 +954,7 @@ get_lang({filetype}) *vim.treesitter.language.get_lang()*
  (`string?`)
 
 inspect({lang}) *vim.treesitter.language.inspect()*
- Inspects the provided language.
-
- Inspecting provides some useful information on the language like node
- names, ...
+ Gets some useful information on the language like node names, ...
 
  Parameters: ~
  • {lang} (`string`) Language

runtime/lua/vim/treesitter.lua

@@ -72,12 +72,12 @@ local function valid_lang(lang)
  return lang and lang ~= ''
 end
 
---- Returns the parser for a specific buffer and attaches it to the buffer
+--- Gets the parser for a buffer and attaches it to the buffer.
 ---
---- If needed, this will create the parser.
+--- Creates the parser, if needed.
 ---
----@param bufnr (integer|nil) Buffer the parser should be tied to (default: current buffer)
----@param lang (string|nil) Language of this parser (default: from buffer filetype)
+---@param bufnr (integer|nil) Buffer to parse (default: current buffer)
+---@param lang (string|nil) Language of this parser (default: buffer 'filetype')
 ---@param opts (table|nil) Options to pass to the created language tree
 ---
 ---@return vim.treesitter.LanguageTree object to use for parsing
@@ -96,15 +96,13 @@ function M.get_parser(bufnr, lang, opts)
  if not parsers[bufnr] then
  error(
  string.format(
- 'There is no parser available for buffer %d and one could not be'
- .. ' created because lang could not be determined. Either pass lang'
- .. ' or set the buffer filetype',
+ "No parser for buffer %d with unknown lang. Either pass lang or set 'filetype'.",
  bufnr
  )
  )
  end
  elseif parsers[bufnr] == nil or parsers[bufnr]:lang() ~= lang then
- assert(lang, 'lang should be valid')
+ assert(lang, 'invalid lang')
  parsers[bufnr] = M._create_parser(bufnr, lang, opts)
  end
 

runtime/lua/vim/treesitter/language.lua

@@ -106,6 +106,7 @@ function M.add(lang, opts)
  path = paths[1]
  end
 
+ vim._ts_remove_language(lang)
  vim._ts_add_language(path, lang, symbol_name)
  M.register(lang, filetype)
 end
@@ -139,9 +140,7 @@ function M.register(lang, filetype)
  end
 end
 
---- Inspects the provided language.
----
---- Inspecting provides some useful information on the language like node names, ...
+--- Gets some useful information on the language like node names, ...
 ---
 ---@param lang string Language
 ---@return table

scripts/gen_help_html.lua

@@ -10,13 +10,13 @@
 --
 -- USAGE (GENERATE HTML):
 -- 1. `:helptags ALL` first; this script depends on vim.fn.taglist().
--- 2. nvim -V1 -es --clean +"lua require('scripts.gen_help_html').gen('./runtime/doc', 'target/dir/')" +q
+-- 2. rm -rf build/runtime/doc/ && make && nvim -V1 -es --clean +"lua require('scripts.gen_help_html').gen('./runtime/doc', 'target/dir/')" +q
 -- - Read the docstring at gen().
 -- 3. cd target/dir/ && jekyll serve --host 0.0.0.0
 -- 4. Visit http://localhost:4000/…/help.txt.html
 --
 -- USAGE (VALIDATE):
--- 1. nvim -V1 -es +"lua require('scripts.gen_help_html').validate('./runtime/doc')" +q
+-- 1. rm -rf build/runtime/doc/ && make && nvim -V1 -es +"lua require('scripts.gen_help_html').validate('./runtime/doc')" +q
 -- - validate() is 10x faster than gen(), so it is used in CI.
 --
 -- SELF-TEST MODE:
@@ -28,6 +28,7 @@
 -- * visit_node() is the core function used by gen() to traverse the document tree and produce HTML.
 -- * visit_validate() is the core function used by validate().
 -- * Files in `new_layout` will be generated with a "flow" layout instead of preformatted/fixed-width layout.
+-- All Nvim-owned files should migrate to "flow" layout.
 
 local tagmap = nil ---@type table<string, string>
 local helpfiles = nil ---@type string[]
@@ -57,6 +58,7 @@ local M = {}
 
 -- These files are generated with "flow" layout (non fixed-width, wrapped text paragraphs).
 -- All other files are "legacy" files which require fixed-width layout.
+-- All Nvim-owned files should migrate to "flow" layout.
 local new_layout = {
  ['api.txt'] = true,
  ['lsp.txt'] = true,
@@ -328,7 +330,7 @@ local function ignore_parse_error(fname, s)
  end
  -- Ignore parse errors for unclosed tag.
  -- This is common in vimdocs and is treated as plaintext by :help.
- return s:find("^[`'|*]")
+ return s:find('^``') or s:find("^['|]")
 end
 
 ---@param node TSNode
@@ -607,11 +609,20 @@ local function visit_node(root, level, lang_tree, headings, opt, stats)
  s = fix_tab_after_conceal(s, node_text(root:next_sibling()))
  end
  return s
- elseif vim.list_contains({ 'codespan', 'keycode' }, node_name) then
+ elseif vim.list_contains({ 'codespan', 'keycode', 'optional' }, node_name) then
  if root:has_error() then
  return text
  end
- local s = ('%s<code>%s</code>'):format(ws(), trimmed)
+ local class = node_name == 'optional' and ' class="optional"' or ''
+ if node_name == 'optional' then
+ return ('%s<code%s>%s</code>'):format(ws(), class, trimmed)
+ end
+ local s = (
+ node_name == 'keycode'
+ -- TODO: use <kbd>. Currently has a layout issue, example: ":help _".
+ and ('%s<code>%s</code>'):format(ws(), trimmed)
+ or ('%s<code%s>%s</code>'):format(ws(), class, trimmed)
+ )
  if opt.old and node_name == 'codespan' then
  s = fix_tab_after_conceal(s, node_text(root:next_sibling()))
  end
@@ -765,9 +776,10 @@ local function parse_buf(fname, parser_path)
  vim.cmd('sbuffer ' .. tostring(fname)) -- Buffer number.
  end
  if parser_path then
- vim.treesitter.language.add('vimdoc', { path = parser_path })
+ vim.treesitter.language.add('vimdoc2', { path = parser_path })
  end
- local lang_tree = vim.treesitter.get_parser(buf)
+ local lang_tree = vim.treesitter.get_parser(buf, 'vimdoc2')
+ -- vim.print(lang_tree)
  return lang_tree, buf
 end
 
@@ -1013,11 +1025,13 @@ local function gen_css(fname)
  local css = [[
  :root {
  --code-color: #004b4b;
+ --kbd-color: red;
  --tag-color: #095943;
  }
  @media (prefers-color-scheme: dark) {
  :root {
  --code-color: #00c243;
+ --kbd-color: red;
  --tag-color: #00b7b7;
  }
  }
@@ -1087,7 +1101,7 @@ local function gen_css(fname)
  /* Tabs are used for alignment in old docs, so we must match Vim's 8-char expectation. */
  tab-size: 8;
  white-space: pre;
- font-size: 16px;
+ font-size: 15px;
  font-family: ui-monospace,SFMono-Regular,SF Mono,Menlo,Consolas,Liberation Mono,monospace;
  }
  .old-help-para pre {
@@ -1146,7 +1160,14 @@ local function gen_css(fname)
  }
  code {
  color: var(--code-color);
- font-size: 16px;
+ font-size: 15px;
+ }
+ code.optional {
+ color: yellow;
+ }
+ kbd {
+ /* color: var(--kbd-color); */
+ font-size: 15px;
  }
  pre {
  /* Tabs are used in codeblocks only for indentation, not alignment, so we can aggressively shrink them. */
@@ -1155,7 +1176,7 @@ local function gen_css(fname)
  line-height: 1.3; /* Important for ascii art. */
  overflow: visible;
  /* font-family: ui-monospace,SFMono-Regular,SF Mono,Menlo,Consolas,Liberation Mono,monospace; */
- font-size: 16px;
+ font-size: 15px;
  margin-top: 10px;
  }
  pre:last-child {

src/nvim/CMakeLists.txt

@@ -953,6 +953,8 @@ add_dependencies(doc doc-vim doc-eval)
 
 add_target(lintdoc
  COMMAND $<TARGET_FILE:nvim_bin> -u NONE -l scripts/lintdoc.lua
- DEPENDS ${DOCFILES}
+ DEPENDS
+ ${DOCFILES}
+ ${PROJECT_SOURCE_DIR}/scripts/gen_help_html.lua
  CUSTOM_COMMAND_ARGS USES_TERMINAL)
 add_dependencies(lintdoc nvim)