From 42e9606c23eab6542678d2786e7e5819fd704e92 Mon Sep 17 00:00:00 2001 From: Anmol Sethi Date: Mon, 14 Mar 2016 05:05:28 -0400 Subject: man.vim: rewrite - Smart autocomplete. It's automatically sorted, filtered for duplicates and even formats the candidates based on what is needed. For example, `:Man 1 printf` will show the pages that are in section 1m as 'page(sect)' to let you know they are in a more specific section. - Instead of trying to unset $MANPAGER we use the -P flag to set the pager to cat - Always use the section arg '-s', it makes the code much simpler (see comment in s:man-args). - A manpage name starting with '-' is invalid. It's fine for sections because of the use of '-s'. - The tagstack is an actual stack now, makes it much simpler. - By using v:count and v:count1, the plugin can explicitly check whether the user set a count, instead of relying on a default value (0) that is actually a real manpage section. - Extraction of a manpage reference is much more simple. No giant long complicated regexes. Now, the plugin lets `man` handle the actual validation. We merely extract the section and page. Syntax regexes are a bit more specific though to prevent highlighting everything. - Multilingual support in the syntax file. Removed the cruft that was only relevent to vim. Also simplified and improved many of the regexes. - Using shellescape when sending the page and sect as arguments - In general, the code flow is much more obvious. - man#get_page has been split up into smaller functions with explicit responsibilties - ':help' behavior in opening splits and manpages - Comments explaining anything that needs explaining and isn't immediately obvious. - If a manpage has already been loaded but if it were to reloaded at the current width which is the same as the width at which it was loaded at previously, it is not reloaded. - Use substitute to remove the backspaced instead of `col -b`, as the latter doesn't work with other languages. - Open paths to manpages - It uses cWORD instead of cword to get the manpage under the cursor, this helps with files that do not have (,) in iskeyword. It also means the plugin does not set iskeyword locally anymore. - (Man) mapping for easy remapping - Switched to single quotes wherever possible. - Updated docs in $VIMRUNTIME/doc/filetype.txt (still need to update user-manual) - Always call tolower on section name. See comment in s:extract_page_and_sect_fpage - Formatting/consistency cleanup - Automatically map q to ':q' when invoked as $MANPAGER - It also fully supports being used as $MANPAGER. Setting the name and stuff automatically. - Split up the setlocals into multiple lines for easier readability - Better detection of errors by redirecting stderr to /dev/null. If an error occured, stdout will be empty. - Functions return [sect, page] not [page, sect]. Makes more sense with how man takes the arguments as sect and then page. - Pretty prints errors on a single line. - If no section is given, automatically finds the correct section for the buffer name. It also gets the correct page. See the comment in s:get_page - If $MANWIDTH is not set, do not assign directly to $MANWIDTH because then $MANWIDTH will always stay set to the same value as we only use winwidth(0) when the global $MANWIDTH is empty. Instead we set it locally for the command. - Maintainer notes on all files. --- runtime/doc/filetype.txt | 59 ++++++++++++++++++++++++++++-------------------- 1 file changed, 35 insertions(+), 24 deletions(-) (limited to 'runtime/doc') diff --git a/runtime/doc/filetype.txt b/runtime/doc/filetype.txt index 76aa3a50ce..644f7c23e1 100644 --- a/runtime/doc/filetype.txt +++ b/runtime/doc/filetype.txt @@ -500,7 +500,7 @@ Options: avoid that a Subject line with "Vim:" in it will cause an error message. 'textwidth' is set to 72. This is often recommended for e-mail. -'formatoptions' is set to break text lines and to repeat the comment leader +'formatoptions' is set to break text lines and to repeat the comment leader in new lines, so that a leading ">" for quotes is repeated. You can also format quoted text with |gq|. @@ -512,37 +512,48 @@ Local mappings: MAN *ft-man-plugin* *:Man* *man.vim* -Displays a manual page in a nice way. Also see the user manual -|find-manpage|. +View manpages from the comfort of vim. Features include syntax highlighting, +smart autocompletion, multilingual support, and manpage jumping. +Also see |find-manpage|. -To start using the ":Man" command before any manual page was loaded, source -this script from your startup vimrc file: > +You can use neovim as a manpager with > - runtime ftplugin/man.vim - -Options: -'iskeyword' the '.' character is added to be able to use CTRL-] on the - manual page name. + export MANPAGER="nvim -c 'set ft=man' -" Commands: -Man {name} Display the manual page for {name} in a window. -Man {number} {name} - Display the manual page for {name} in a section {number}. - -Global mapping: -K Displays the manual page for the word under the cursor. +Man {name} Display the manpage for {name} in a new tab. +Man {sect} {name} Same as above except specify the section. +Man {name}({sect}) Alternate syntax to above. Exists so that you can see + the section of the manpage you are completing. +Man {sect} {name}({sect}) This is used during completion to show the real section + of a manpage when the provided section is a prefix. + E.g. section 1m vs 1. + +Man {path} Open the manpage specified by path, if it's in the current + directory, specify the leading ./ +Global Mappings: +(Man) Jump to the manpage for the under the + cursor in a new tab. Takes a count as the manpage + section. Local mappings: -CTRL-] Jump to the manual page for the word under the cursor. -CTRL-T Jump back to the previous manual page. -q Same as ":quit" +CTRL-] Jump to the manpage for the under the cursor. Takes a count + as the manpage section. +K Same as CTRL-]. +CTRL-T Jump back to the previous manpage. +q Close the window. -To enable folding use this: > - let g:ft_man_folding_enable = 1 -If you do not like the default folding, use an autocommand to add your desired -folding style instead. For example: > - autocmd FileType man setlocal foldmethod=indent foldenable +Variables: +g:no_man_maps + If set, no mappings are created in man buffers. + +g:ft_man_folding_enable + If set to 1, manpages are folded with foldmethod=indent and + foldnestmax=1. +If you do not like the default folding, use an autocommand to add your desired +folding style instead. For example: > + :autocmd FileType man setlocal foldmethod=indent foldenable PDF *ft-pdf-plugin* -- cgit From 66ceb5a487eff0b856142b41ce0a95d3b1ea85e5 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Thu, 4 Aug 2016 23:22:51 -0400 Subject: man.vim: doc, UX tweaks s:error: Convention is to highlight the entire message, so stick to that. --- runtime/doc/filetype.txt | 42 +++++++++++++++++------------------------- runtime/doc/usr_12.txt | 19 ++++--------------- runtime/doc/vim_diff.txt | 1 + 3 files changed, 22 insertions(+), 40 deletions(-) (limited to 'runtime/doc') diff --git a/runtime/doc/filetype.txt b/runtime/doc/filetype.txt index 644f7c23e1..92ed9de369 100644 --- a/runtime/doc/filetype.txt +++ b/runtime/doc/filetype.txt @@ -512,44 +512,36 @@ Local mappings: MAN *ft-man-plugin* *:Man* *man.vim* -View manpages from the comfort of vim. Features include syntax highlighting, -smart autocompletion, multilingual support, and manpage jumping. -Also see |find-manpage|. +View manpages in Nvim. Supports highlighting, autocompletion, locales, and +navigation. See also |find-manpage|. -You can use neovim as a manpager with > +To use Nvim as a manpager: export MANPAGER="nvim -c 'set ft=man' -" Commands: -Man {name} Display the manpage for {name} in a new tab. -Man {sect} {name} Same as above except specify the section. -Man {name}({sect}) Alternate syntax to above. Exists so that you can see - the section of the manpage you are completing. -Man {sect} {name}({sect}) This is used during completion to show the real section - of a manpage when the provided section is a prefix. - E.g. section 1m vs 1. - -Man {path} Open the manpage specified by path, if it's in the current - directory, specify the leading ./ +Man {name} Display the manpage for {name} in a window. +Man {sect} {name} Display the manpage for {name} and section {sect}. +Man {name}({sect}) Alternate syntax which auto-completes the section. +Man {sect} {name}({sect}) Used during completion to show the real section of + when the provided section is a prefix, e.g. 1m vs 1. +Man {path} Open the manpage specified by path. Use "./" if it + is in the current directory. + Global Mappings: (Man) Jump to the manpage for the under the - cursor in a new tab. Takes a count as the manpage - section. + cursor in a new tab. Takes a count for the section. Local mappings: -CTRL-] Jump to the manpage for the under the cursor. Takes a count - as the manpage section. -K Same as CTRL-]. +K +CTRL-] Jump to the manpage for the under the + cursor. Takes a count for the section. CTRL-T Jump back to the previous manpage. q Close the window. Variables: -g:no_man_maps - If set, no mappings are created in man buffers. - -g:ft_man_folding_enable - If set to 1, manpages are folded with foldmethod=indent and - foldnestmax=1. +g:no_man_maps Do not create mappings in manpage buffers. +g:ft_man_folding_enable Fold manpages with foldmethod=indent foldnestmax=1. If you do not like the default folding, use an autocommand to add your desired folding style instead. For example: > diff --git a/runtime/doc/usr_12.txt b/runtime/doc/usr_12.txt index 237abae55f..169d886e78 100644 --- a/runtime/doc/usr_12.txt +++ b/runtime/doc/usr_12.txt @@ -237,19 +237,8 @@ simple way: Move the cursor to the word you want to find help on and press > K -Vim will run the external "man" program on the word. If the man page is -found, it is displayed. This uses the normal pager to scroll through the text -(mostly the "more" program). When you get to the end pressing will -get you back into Vim. - -A disadvantage is that you can't see the man page and the text you are working -on at the same time. There is a trick to make the man page appear in a Vim -window. First, load the man filetype plugin: > - - :runtime! ftplugin/man.vim - -Put this command in your vimrc file if you intend to do this often. Now you -can use the ":Man" command to open a window on a man page: > +Nvim will run |:Man| on the word. If the man page is found, it is displayed. +You can also use the |:Man| command to open a window on a man page: > :Man csh @@ -267,7 +256,7 @@ window. To display a man page for the word under the cursor, use this: > - \K + K (If you redefined the , use it instead of the backslash). For example, you want to know the return value of "strstr()" while editing @@ -275,7 +264,7 @@ this line: if ( strstr (input, "aap") == ) ~ -Move the cursor to somewhere on "strstr" and type "\K". A window will open +Move the cursor to somewhere on "strstr" and type "K". A window will open to display the man page for strstr(). ============================================================================== diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt index 937ed9e8ba..47380428b0 100644 --- a/runtime/doc/vim_diff.txt +++ b/runtime/doc/vim_diff.txt @@ -96,6 +96,7 @@ Options: Commands: |:CheckHealth| + |:Man| has many improvements, including auto-completion Functions: |execute()| works with |:redir| -- cgit