*os_ios.txt*	For Vim version 8.1.	Last change: 2020 Jan 16

			iVim REFERENCE MANUAL	by Terry Chou


							*ios* *iOS*

This file documents the particularities of the iOS port of Vim.

iVim is open source: https://github.com/terrychou/iVim, and you can find 
useful information on its wiki: https://github.com/terrychou/iVim/wiki

ACKNOWLEGEMENT

This project stands on the shoulders of two precendent projects:
1. Vim port from Applidium: https://github.com/applidium/Vim

Although it has been inactive for a while, it is a pioneer of porting Vim to 
iOS. Itself and its opened source code inspires many followers.

2. VimIOS - A port of Vim to iOS 9+: https://github.com/larki/VimIOS

Based on the above project, it includes many features to take advantage of 
the newer iOS systems. This project started from it.

==============================================================================

1.  File system				|ios-file-system|
2.  Font management			|ios-font-management|
3.  Extended keyboard			|ios-extended-keyboard|
4.  Multi-stage language support	|ios-multistage-language|
5.  Dictation				|ios-dictation|
6.  Open URL				|ios-open-url|
7.  Share				|ios-share|
8.  Settings				|ios-settings|
9.  External keyboard			|ios-external-keyboard|
10. Integrated Exuberant Ctags		|ios-exuberant-ctags|
11. Auto restore                        |ios-auto-restore|
12. External commands                   |ios-external-commands|
13. Miscellaneous			|ios-miscellaneous|

==============================================================================
1. File system				*ios-file-system*

For security purpose, an iOS app can only access files within its sandbox 
environment. Normally, user-generated contents are stored in the `Documents`
directory under its data container. Therefore, this directory is set as the 
default `$HOME` for iVim. You can find or create all the user-specific files 
under it.

The Inbox directory ~

Under the `Documents` directory, there would also be a subdirectory named 
`Inbox`. Its role is to save the files shared with iVim by other apps. As a 
result, the files in this directory are readonly. You cannot create files 
under it.

The file browser ~

Because iOS systems don't have any shell available, you cannot browse the 
file system via external Unix commands.
However, iVim comes with a `netrw` file browser plugin. You can type ":edit ."
to get started. It provides an intuitive way to navigate the file system 
structure. Type ":help netrw" to get the help on how to use it.

The Files app support ~

Newly added in iOS 11, the Files app provides a central place for users to
organize their documents. iVim adds support to it. You can now apply common
file operations such as copy, duplicate, move, create or delete easily to
files or directories under iVim's `Documents` directory.
iVim can be found under "Locations > On My ..." in Files.

Besides the file editing within its sandbox, iVim can edit text from other 
apps via |ios-share|.


==============================================================================
2. Font management			*ios-font-management*

There are two types of fonts are available: 

a. system fonts

Besides the fonts available in iOS, the font `Source Code Pro` is embedded 
into iVim.

b. user fonts

iVim also allows users to import and use their own fonts.
Currently, fonts of type `ttf` or `otf` are supported. You can copy them from 
other apps to iVim via the share extension. The imported fonts will be 
automatically moved into directory `Library/Fonts/`.

The font commands ~

iVim has added two commands to manipulate the fonts. |:ifont| is for listing 
available fonts and changing the current one. |:ideletefont| is for deleting 
user fonts. Type ":help :ifont" or ":help :ideletefont" for more information.

Note that only monospace fonts are well supported.


==============================================================================
3. Extended keyboard			*ios-extended-keyboard*

An efficient use of Vim requires quick symbol input. However, the iOS system 
keyboard 'hides' them into other pages to save the screen real-estate. 
Moreover, some necessary keys are just not available in iOS.

To offer a more productive input, iVim adds an extended keyboard.

The compact button ~

In order to cover as many keys as possible in limited space, compact buttons 
are used in the extended keyboard.
The key in the center of the button is the primary key, and a simple tapping 
will trigger its input. Some optional keys may circle around the primary one. 
To input an optional key, drag it towards the center and release. For example,
if you want to input the key sitting at the top left corner, you make a drag 
right and down. The start point doesn't really matter.

The Ctrl key ~

Some keys are sticky. For example, the Ctrl key needs to be held down while 
pressing other keys. Thus it is set up as a sticky key:

a. triggering it once will enter the one-off state. After inputting a `C-`
combination, it will restore automatically.

b. triggering it twice will make it into the held state. It will keep being
held until it is tapped again. This is good for continuous `C-` inputs.

c. tapping it in any of the above state will restore its state.

Hide and show ~ 

You can toggle the extended keyboard by one finger long pressing the screen. 
The extended keyboard will show at launch by default. You can make it hide
by default by toggle related option in |ios-settings|.

Customize ~

If the default buttons or keys on the extended keyboard don't meet your own
needs, you can customize them through command |:isetekbd|.


==============================================================================
4. Multi-stage language support		*ios-multistage-language*

iVim adds support to multistage input languages such as Chinese or Japanese.

Multistage input means keys from the user may have different meaning than
their literal one. It requires the user to do further confirm to get the final
result. Besides the asian languages, `alt-`-enabled accentuated Latin input is 
also an example.

Input behavior ~

During a multistage input session: 

1) the cursor position will not change until the user confirms thus the final
result is ready (which also means the end of this session).

2) pressing `esc` cancels current input session and discards all keys input so 
far.

3) tapping on screen ends current input session and confirms the input result 
so far as the final result.

4) any arrow key from the extended keyboard behaves as the same as tapping on
screen. However, arrow keys from an external hardware keyboard will usually be 
taken over by the system and travel among the available choices.

Note: a. The key pressings will be translated into normal ones if it is not in 
|Insert| mode. b. Multistage input will stop working during dictation as
mentioned in |ios-dictation|.

Special highlight ~

Often, by a simple glance, the user cannot tell if a multistage input session 
is in effect or not. iVim provides a little feature to help with this: the
user can change the color of the cursor-in-multistage by setting the highlight
group CursorIM: >

        :highlight CursorIM guifg=NONE guibg=Green
<
after this, the cursor becomes green when it is in a multistage input session.


==============================================================================
5. Dictation				*ios-dictation*

iVim supports dictation input of iOS systems.

Behavior ~

In most scenarios, dictation input is live. It means that the hypothesis will 
keep updating during a dictation session. As a result, mappings will be
ignored while dictating. One exception is the |Normal| mode, as described
below.

Normal mode ~

Because of the characteristics of dictation input and |Normal| mode, the 
former needs special handling for the latter in two ways:

a. Automatical mode jumping

iVim will change the mode from |Normal| to a chosen one when dictation happens
in the |Normal| mode. The existing dictation result will be passed to the new
mode. This can be set up as described in `Dictation` part of |ios-settings|.

b. Leaving it to users

In this case, the dictation result will be passed to iVim as if users had 
typed it. For example, if the result is "insert", iVim will enter the |Insert|
mode and "nsert" will be inserted.

For a better user control in this way, the dication results will be handled
specially. A dictation result won't be counted as the input until the user
confirms by ending the session explicitly. The space characters at the ends of
the final result, if there is any, will be trimmed. Mappings will work in this
situation for users to obtain more concise commands. Example: >

	John sets a normal mode mapping from "insert mode" to "i". In the 
	normal mode, he activates the dication keyboard, says "insert mode",
	and ends the session by tapping the "Done" button. Although the 
	dictation result is actually " insert mode", the first space char is
	trimmed and "insert mode" is passed to iVim. Then iVim finds the
	existing mapping for it, and it is mapped to the target "i". As a 
	result, iVim enters the insert mode.
<
Interruptions ~

Besides the normal ways to stop a dictation session, you could interrupt it by
doing one of the followings:

a. Pressing `esc` will cancel the input. It will clean the exisitng hypothesis
and exit dictation.

b. Pressing any arrow key will stop the input. It will accept the exiting
result and exit dictation.

c. Tapping the screen will act as the arrow keys do.

d. Any other key pressing will be ignored during a session.

External hardware keyboard ~

If you have a hardware keyboard connected, some points are worth mentioning:

a. Activate dictation input

Normally, the on-screen keyboard is hidden. To activate the dictation, you
need to toggle it out first (pressing `eject` key would do). Sometimes, the 
dictation button may not appear on the on-screen keyboard. Changing to another 
keyboard then back may bring it out again.

b. Things broken

Multistage input will stop working while the dictation keyboard is present. 
And keyboard layout settings may not be respected during dictation.


==============================================================================
6. Open URL				*ios-open-url*

Another way for sharing info among apps in iOS is via URL scheme. You can put
info into an URL and open it. Then the system will launch the supporting app
if there is one, and let it handle this URL. iVim adds support of opening URLs 
in this way to communicate with or control other apps.

Example ~

URL scheme "https://" is handled by the browser Safari in iOS. When you open
an URL "https://www.example.com/search?q={expand('<cword>')%[Q}", the browser
will be launched, open the site "example.com", and do some search with the 
word under the cursor as the query. All of these actions as a workflow are
done with just this one opening of the URL.

Include information ~

iVim introduces "variable token" as a way for you to include dynamic info into 
an URL. By utilizing vim's |expression|, you can get useful info such as
clipboard contents, current file name or results of functions. In the example 
above, "{expand('<cword>')%[Q}" is one variable token which will be replaced 
with the word under the cursor when the URL is opened. 

Refer to command |:iopenurl| for the details on the usage of URL opening.


==============================================================================
7. Share				*ios-share*

Sharing makes iVim's editing power available to more apps. 

Importing ~

If an app supports sharing text files or selected text, you can find iVim in 
its share panel. See |share-with-ivim| and |copy-to-ivim|.

Through the document picker invoked by ":idocuments import", you can also 
import text files from iCloud Drive or other document providers. This way,
you don't have to leave iVim to do the importing.

The imported file or text will be opened in a new tab for further editing.

Exporting ~

You can invoke iVim's share panel via the command |:ishare|, therefore share 
files or text with other apps.

Editing in place ~

The document picker |:idocuments| also allows you to edit files directly in 
iCloud Drive or other document provider apps. All the modifications will be 
saved back to the original files even though this is normally not allowed 
because they are in different sandbox environments.

iVim also supports opening directories. After you select and open a directory 
from the document picker, besides file editing, you can do all the supported 
filesystem operations within it. Such as create or rename subdirectories or 
files, delete files, etc. iVim monitors changes in this root directory and
syncs them back to the original directory. Note that operations on the root
directory itself break this mechanism therefore would be better avoided.

To provide better safety, iVim puts deleted items in the opened directory
into its related trash bin. Users can choose to restore them later through
command |:idocuments-trash|. Note that the trash bin will be cleaned up
together with its associated directory after the latter is closed.

Also see |open-in-ivim|.

Items in the share panel ~

a. Share with iVim					*share-with-ivim*

This item share text with iVim. When invoked, a floating box appears with the
text to be shared. The text may come from:

1) selected text

when the shared item is the selected text in the sharing app, the text is
right the selected text. 

2) content of files

when the shared items are files, it tries to get text content from each file
and concatenate them in order. If any file (e.g. an image file) fails to 
provide valid text content, it aborts and shows the error. Note that at max 
10 files at once is supported in this way, and it does not affect the original
files.

After the text becomes available in the box, you can do some more simple 
editing to it. Tapping `Share` opens iVim and puts the text into a new buffer 
in a new tab.

Note that any invalid share items disables the `Share` button.

b. Copy to iVim						*copy-to-ivim*

It will copy the shared file into the `Documents` directory. When invoked, it
will open iVim and the copied file in a new tab. Note that if there had been
a file with the same name as the shared one, it will be renamed to avoid the
conflict.

c. Open in iVim						*open-in-ivim*

It will open the shared file directly in iVim. In another word, it lets iVim
edit the target file in place. Note that it needs the sharing app's support
for this feature.

Note that supported font files are always copied for installation.

Old Documents ~						*ivim-old-documents*

Once an edit-in-place file or directory is opened in iVim, it will be 
bookmarked as one of the old documents. Therefore you can open it later
directly from the record. iVim provides the command |:iolddocs| to support
this function. Refer to it for the related details. 

Type ":help :ishare" or ":help :idocuments" for more detailed information.


==============================================================================
8. Settings						*ios-settings*

Because there are scenarios where vim's options cannot cover, iVim also
provides some setting options in the system's Settings app.

Launch Option ~

This settings group allows users indicate launch arguments for vim.

a. Arguments
You can give the arguments in this field. When iVim launches, this line will 
be parsed and taken by vim as its command line arguments.

b. Always
This switch tells iVim about the term of validity of the launch arguments.
If YES, iVim will take the arguments every time it launches.
If NO, iVim will only launch with the arguments once, then remove them.

Extended Keyboard ~

Hide By Default
It controls whether iVim hides the extended keyboard by default or not.

Hardware Keyboard ~

a. Map [caps lock] to
If you have an external hardware keyboard connected, you can map its less used
`caps_lock` key to either `esc` or `ctrl` in this option. Note that it has 
caveats as mentioned at g. in |ios-external-keyboard|.

b. Enable [alt] Mapping
When enabled, it will map keystrokes with modifier `alt` to |<A-| chords in 
iVim. Otherwise, they will be handled by iOS system for extended symbols 
input.

c. Key Repeating
The held key will repeat itself if this option is enabled. It is on by default.
Note that it has some caveats as mentioned in |ios-external-keyboard|.

Dictation ~

Force normal mode to
Dictation input is handled specially in |Normal| mode. This option tells iVim
the target mode to jump to when dictation happens in |Normal| mode. 

`insert_mode` means iVim will enter |Insert| mode; `command_line_mode` targets
|Cmdline| mode; `none` will not do mode jumping at all. Refer to `Normal_mode`
part of |ios-dictation| for details.

Auto Restore ~

Enable
This option toggles the `Auto restore` feature of iVim. See |ios-auto-restore|
for details.


==============================================================================
9. External keyboard				*ios-external-keyboard*

iVim supports the external hardware keyboard. You can connect the keyboard to
your iOS device and start typing in iVim.

a. besides the `ctrl` key chords |<C-|, the `command` key chords |<D-| are
now at your disposal.

b. chords `<D-s>`, `<D-h>` and `<D-.>` are reserved by iOS system.

c. by default, the `alt` key is preserved to input the extended symbols.
But you can enable `alt` key mapping in |ios-settings| to map it to the |<A-| 
chords handled by iVim.

d. special keys `esc`, `arrows`, `tab` and `enter` combined with modifier keys 
`ctrl`, `command`, `alt` and `shift` respectively are supported. However, 
`<C-CR>` is not working now.

e. function keys such as `F1` is not available due to the API limitation.

f. multiple modifiers chords such as `<D-C->` are not supported.

g. you can map `caps_lock` key to either `esc` or `ctrl` in |ios-settings|.
Note that due to the API limitation, only English keyboards are supported and 
will be disabled otherwise; after mapped, the default `alt` extended symbol 
input will be ignored; for an alternative to extended symbol input, you may 
refer to |digraph|; however, the `alt` mapping mentioned in c. will still work 
if enabled.

h. there are some caveats worth noting when it comes to |ios-dictation|.

Key repeating ~

If you are inputting in English, iVim repeats certain held keys for you. The
supported keys include:

a. alphabeta keys: "abcdefghijklmnopqrstuvwxyz" and their upper case ones.
b. numeric keys: "1234567890"
c. symbol keys: "`-=~!@#$%^&*()_+[]\\{}|;':\",./<>?"

Note that: 1) you need to switch on iOS system's related setting for this to
work; 2) it will be disabled automatically when inputting in a language other 
than English; 3) you can enable or disable it in |ios-settings|.


==============================================================================
10. Integrated Exuberant Ctags			*ios-exuberant-ctags*

Exuberant Ctags |Exuberant_ctags| is a great tool to generate tags for
programming languages. Its resulting tags are directly supported by vim. 

For better source code browsing experience, iVim integrates Exuberant Ctags
into its own environment. You can use it like the shell command via the Ex 
command |:ictags|.

Also, the integrated Exuberant Ctags shares the home directory with iVim. You
can put your `.ctags` config file under it and ctags will read it every time
it is invoked.

Type ":help :ictags" for details about the command.


==============================================================================
11. Auto restore                                *ios-auto-restore*

With `Auto-restore` enabled, iVim automatically restores the last editing 
session on launch, after an app termination.

Because it is implemented based on vim's |session| feature, `Auto-restore`'s 
basic behavior goes in that way.

Although iVim tries its best to make a restore look as normal as possible, 
there are some points worth mentioning:

a. instead of saving a changed buffer directly for the user, iVim caches it
for each file but leaves the original file alone. 

In another word, iVim will restore the latest content for each file in the
windows, but the user still needs an explicit `write` operation to save the 
changes, if there is any, back to the respective file.

1) a changed buffer without a file name will be saved as a temporary file
automatically, and it is up to the user to save it as a formal file or just 
drop it.

2) while a changed buffer with a file name keeps its changed state, its undo 
history is lost.

3) if a file is newer than its cached changes (e.g. it has been edited
elsewhere before the restore), the latter is dropped.

b. buffers in the buffer list will be cached. To exclude buffers from the next
restore, delete them from the buffer list.

c. unlike default vim sessions, opened directories by |netrw| will also be 
restored. However, their cursor position information is not kept.

d. other useful information such as marks or register contents is stored in
the |viminfo-file|, and also restored. Its details can be customized via the 
'viminfo' option.
 
e. `Auto-restore` can be disabled in |ios-settings|. Note that iVim will clear 
all the cached information when this happens.


==============================================================================
12. External commands                   *ios-external-commands*

In order to enhance some plugins and its editing workflow, iVim includes some
useful external commands and manages to make them work seemlessly with itself.

See |ios-external-cmds| for related details.


==============================================================================
13. Miscellaneous			*ios-miscellaneous* *ios-misc*

Touch support ~

iVim adds support to basic touch gestures to make operations more intuitive 
and efficient.

a. Single tapping is like mouse left click on computers: it can change cursor 
position, window or select specific tab.

b. Single finger dragging can select text within a window, or resize a window 
when the fingers are on its status bar.

c. Two fingers dragging will scroll text in a window.

d. While one finger long pressing toggles the extended keyboard, two fingers
long pressing hides the system keyboard, and a single tap to bring it back.

Swap file cleaning ~

Due to the sudden app termination mechanism of the iOS system, there would be
leftover swap files in the filesystem. iVim will try and clean them on each
launch automatically.

The viminfo file ~

The default writing timing for the |viminfo-file| is when vim exits. However,
that does not happen so often in iVim. Therefore, iVim takes over and records
the file when necessary.


 vim:tw=78:ts=8:noet:ft=help:norl:
