Merge pull request #1133 from ychin/cleanup-macvim-docs-help-menu-startup

Cleanup MacVim docs

Author: ychin

runtime/doc/gui_mac.txt

@@ -52,18 +52,14 @@ It is not possible to modify 'termencoding' in MacVim; this option is forcibly
 set to "utf-8".  The option 'encoding' also defaults to "utf-8" (as opposed to
 "latin1" in the other GUI ports).
 
-Note: UTF-8 can represent all characters defined in Unicode, which includes
-all characters in all other standard encodings, so it should be perfectly safe
-to edit files in any encoding while 'encoding' is set to "utf-8".  Of course,
-you may need to set 'fileencodings' to auto-detect the encoding of the files
-you edit, or force the detection with |++enc| on the command line.
+In generally you should keep 'encoding' set to the default ("utf-8") as that's
+what macOS uses.  It also works on any character.  Sometimes you may need to
+set 'fileencodings' to auto-detect encoding of files you edit, or force the
+detection with |++enc| on the command line.
 
 However, if you are editing files that use multiple encodings (container
-formats like MIME or Unix mbox files) or no standard encoding (binary data,
-see also |edit-binary|), you may want to prevent MacVim from re-encoding the
-file at all. In this situation, you will need to set both 'encoding' and
-'fileencodings' to a simple single-byte encoding such as Latin1 so that when
-the file is read into memory, the original bytes are left untouched.
+formats like MIME or Unix mbox files) or a binary file, you want to make sure
+'binary' is set (see |edit-binary|).
 
 							*macvim-shift-movement*
 Text editors on macOS lets the user hold down shift+movement key to extend the
@@ -91,12 +87,12 @@ The "Open files from applications" preference in the General preference pane
 gives more options on how dropped files should open, in case tabs are not
 desired.
 
-							*macvim-default-menu*
-The default menu in MacVim has been changed to conform better with the Apple
-Human Interface Guidelines (HIG).
+				    *macvim-default-menus* *macvim-help-menu*
+The default menus (|menu.vim|) in MacVim have been changed to conform better
+with the Apple Human Interface Guidelines (HIG).
 
-Note: The menus are a work in progress.  If you know something about the HIG
-and want to contribute to MacVim you could do so by making the menus better.
+The Help menu's search can be used to search Vim's documentation.  You can use
+it to quickly find the documentation you want in addition to using |:help|.
 
 							*macvim-window-title*
 The default window title does not include the argument list because it looks
@@ -156,11 +152,11 @@ behaviour, then add the line "set backspace&" to your "~/.vimrc" file.
 ==============================================================================
 2. Starting MacVim					*macvim-start*
 
-The easiest way to start MacVim is by double-clicking its icon in the Finder,
-but most users will probably prefer to use the Terminal.  First some Finder
-related ways of starting MacVim are described, then Terminal is discussed.
-Note that you can put MacVim anywhere on your hard drive, but in this help
-file it is assumed that you have put it inside your /Applications folder.
+Starting MacVim from the UI ~
+
+To start MacVim in macOS, simply double-click its icon in the Finder or click
+on the Dock icon. Usually it should be installed as
+`/Applications/MacVim.app`.
 
 MacVim automatically registers itself as an editor of several standard file
 formats.  This enables you to double-click a file to open it with MacVim (if
@@ -172,41 +168,51 @@ have files open in e.g. splits by changing the "Open files from applications"
 option in the General preference pane).  Finally, you can use macOS System
 Services to open files in MacVim, see |macvim-services|.
 
-Use |mvim| script to start MacVim from Terminal.
-
-Or use the "open" command (this method can not be used to pass parameters to
-Vim) >
+Alternatively, use the "open" command (this method can not be used to pass
+parameters to Vim) >
 	open -a MacVim file ...
 The advantage of using the latter method is that the settings relating to file
 opening in the preferences panel are respected, and files open instantly if
 |Quickstart| is enabled.
 
-Once in terminal Vim it is possible to start MacVim by using the following
-command:
-	:gui [++opt] [+cmd] [-f|-b] [files...]
-Note: Forking ("-b") currently does not work.
+Starting MacVim from a terminal~
 
-							*mvim*
-The "mvim" shell script bundled with MacVim. >
+					    *mvim* *macvim-PATH* *macvim-cmdline*
+MacVim comes bundled with a shell script called "mvim" that can be used to
+launch MacVim from the terminal. It's located at: >
 	/Applications/MacVim.app/Contents/bin/mvim
-This is a wrapper script to launch Vim executable in the bundle.  Put this
-folder >
+
+To be able to easily use it, put this folder in your path: >
 	/Applications/MacVim.app/Contents/bin
-in your path and then simply type "mvim" to start MacVim from Terminal. >
+For example, if you use zsh, you can put the following in `~/.zprofile`: >
+	export PATH="/Applications/MacVim.app/Contents/bin:$PATH"
+
+After that, type "mvim" to start MacVim from Terminal. >
 	$ mvim
 You can also specify files to open with. >
 	$ mvim file ...
 Also the bin folder has convenient scripts for diffing and opening file as the file is read-only. >
 	* Diff:		mvimdiff
 	* Read-only:	mview
 
-You can use "vim", "vimdiff", and "view" if you want to use non-GUI Vim.
+You can still use the normal "vim", "vimdiff", and "view" commands if you want
+to use non-GUI Vim, and "gvim" to launch MacVim ("gvim" works the same way as
+"mvim").
+
+Going from terminal to GUI mode~
+
+Once in terminal Vim it is possible to start the MacVim GUI by using the
+following command (see |:gui|):
+	:gui [++opt] [+cmd] [-f|-b] [files...]
+Note: Forking ("-b") currently does not work.
 
 							*Quickstart*
-Quickstart ensures that new windows open instantaneously e.g. when <D-n> is
-pressed.  This feature can be enabled from the Advanced preferences pane (it
-is disabled by default).  Note that this setting does not affect the speed
-with which windows open when using the |mvim| command.
+Quickstart ensures that new windows open quickly e.g. when <D-n> is
+pressed.  It works by keeping a Vim process in the background that will
+immediately become active when you open a window.  This feature can be enabled
+from the Advanced preferences pane (it is disabled by default).  Note that
+this setting does not affect the speed with which windows open when using the
+|mvim| command.
 
 Note that any changes to runtime files that are kept in a non-standard
 location (i.e. not in ~/.vim) will not be picked up for the first window that
@@ -256,6 +262,7 @@ KEY				VALUE ~
 *MMFullScreenFadeTime*		fade delay for non-native fullscreen [float]
 *MMLoginShellArgument*		login shell parameter [string]
 *MMLoginShellCommand*		which shell to use to launch Vim [string]
+*MMNativeFullScreen*		use native full screen mode [bool]
 *MMNoFontSubstitution*		disable automatic font substitution [bool]
 				(Deprecated: Non-CoreText renderer only)
 *MMNoTitleBarWindow*		hide title bar [bool]
@@ -314,6 +321,13 @@ color scheme while system preferences are configured to use light mode. It's
 also the recommended setting when title bar is configured to be "Transparent"
 (see |MMTitlebarAppearsTransparent|).
 
+							*macvim-full-screen*
+There are two types of full screen modes.  By default, MacVim uses macOS'
+native full screen functionality, which creates a separate space in Mission
+Control.  MacVim also provides a non-native full screen mode, which can be set
+by disabling native full screen in the preference panel, or by setting
+|MMNativeFullScreen| to `NO` manually.
+
 ==============================================================================
 5. Special colors					*macvim-colors*
 
@@ -367,6 +381,12 @@ highlight color when a window becomes inactive.
 ==============================================================================
 6. Menus						*macvim-menus*
 
+Default Menus~
+
+See |macvim-default-menus|.
+
+Customization~
+
 Menus in macOS behave slightly different from other platforms.  For that
 reason two new commands have been added to Vim.  To understand what these
 commands do you must first understand how menus work on macOS.
@@ -537,10 +557,13 @@ that items after it will be right-aligned, and is specified by names that
 begin with "-flexspace" and ends with "-".
 
 						*macvim-touchbar-icon*
-You can specify icons for Touch Bar buttons the same way for toolbar icons.
-Touch Bar icons should ideally be 36x36 pixels, and no larger than 44x44
-pixels. You can also use default template icons provided by Apple by using
-their template names. An example: >
+You can specify icons for Touch Bar buttons the same way for toolbar icons
+(see |macvim-toolbar|).  When a button has an icon, it won't show the menu
+name.  Touch Bar icons should ideally be 36x36 pixels, and no larger than
+44x44 pixels. >
+	:an icon=/home/foo/bar.png TouchBar.DoSomething :echo 'Do'<CR>
+You can also use default template icons provided by Apple by using their
+template names. An example: >
 	:an icon=NSTouchBarListViewTemplate TouchBar.ShowList :ls<CR>
 <
 						*macvim-touchbar-title*
@@ -806,17 +829,18 @@ prominent bugs/missing features.
 - Printing.  As a temporary solution <D-p> creates a PostScript file which is
   then opened in Preview where it may be printed. See |hardcopy|.
 
-Other bugs and issues are tracked on Github.  If you find new bugs or have
+General bugs and issues are tracked on Github.  If you find new bugs or have
 feature requests then please file an issue there: >
 	https://github.com/macvim-dev/macvim/issues
 
+For general discussions, asking questions, you could use the Github
+discussions page: >
+	https://github.com/macvim-dev/macvim/discussions
+
 There is also a vim_mac mailing list.  You can also post your findings of bugs
 and issues there as well:				*vim_mac_group*   >
 	http://groups.google.com/group/vim_mac
 
-This is also the best place for making feature requests as well as for asking
-general questions about MacVim.
-
 ==============================================================================
 16. Hints						*macvim-hints*
 

runtime/doc/tags

@@ -5018,6 +5018,7 @@ MMDisableLaunchAnimation	gui_mac.txt	/*MMDisableLaunchAnimation*
 MMFullScreenFadeTime	gui_mac.txt	/*MMFullScreenFadeTime*
 MMLoginShellArgument	gui_mac.txt	/*MMLoginShellArgument*
 MMLoginShellCommand	gui_mac.txt	/*MMLoginShellCommand*
+MMNativeFullScreen	gui_mac.txt	/*MMNativeFullScreen*
 MMNoFontSubstitution	gui_mac.txt	/*MMNoFontSubstitution*
 MMNoTitleBarWindow	gui_mac.txt	/*MMNoTitleBarWindow*
 MMShareFindPboard	gui_mac.txt	/*MMShareFindPboard*
@@ -7788,23 +7789,27 @@ mac-vimfile	os_mac.txt	/*mac-vimfile*
 macintosh	os_mac.txt	/*macintosh*
 macro	map.txt	/*macro*
 macvim	gui_mac.txt	/*macvim*
+macvim-PATH	gui_mac.txt	/*macvim-PATH*
 macvim-appearance	gui_mac.txt	/*macvim-appearance*
 macvim-appearance-mode	gui_mac.txt	/*macvim-appearance-mode*
 macvim-autocommands	gui_mac.txt	/*macvim-autocommands*
 macvim-backspace	gui_mac.txt	/*macvim-backspace*
 macvim-clientserver	remote.txt	/*macvim-clientserver*
+macvim-cmdline	gui_mac.txt	/*macvim-cmdline*
 macvim-colors	gui_mac.txt	/*macvim-colors*
 macvim-colorscheme	gui_mac.txt	/*macvim-colorscheme*
 macvim-commands	gui_mac.txt	/*macvim-commands*
 macvim-dark-mode	gui_mac.txt	/*macvim-dark-mode*
-macvim-default-menu	gui_mac.txt	/*macvim-default-menu*
+macvim-default-menus	gui_mac.txt	/*macvim-default-menus*
 macvim-delete	gui_mac.txt	/*macvim-delete*
 macvim-dialogs	gui_mac.txt	/*macvim-dialogs*
 macvim-differences	gui_mac.txt	/*macvim-differences*
 macvim-drag-n-drop	gui_mac.txt	/*macvim-drag-n-drop*
 macvim-encoding	gui_mac.txt	/*macvim-encoding*
 macvim-find	gui_mac.txt	/*macvim-find*
+macvim-full-screen	gui_mac.txt	/*macvim-full-screen*
 macvim-gestures	gui_mac.txt	/*macvim-gestures*
+macvim-help-menu	gui_mac.txt	/*macvim-help-menu*
 macvim-hints	gui_mac.txt	/*macvim-hints*
 macvim-international	gui_mac.txt	/*macvim-international*
 macvim-login-shell	gui_mac.txt	/*macvim-login-shell*