*os_riscos.txt*  For Vim version 5.2h.  Last modification: 1998 Jul 09


		  VIM REFERENCE MANUAL    by Thomas Leonard


								*riscos*
This file contains the particularities for the RISC OS version of Vim.

The RISC OS port is a completely new port and is not based on the old `archi'
port.

1.  File locations		|riscos-locations|
2.  Filename munging		|riscos-munging|
3.  Command-line use		|riscos-commandline|
4.  Desktop (GUI) use		|riscos-gui|
5.  Remote use (telnet)		|riscos-remote|
6.  Temporary files		|riscos-temp-files|
7.  Interrupting		|riscos-interrupt|
8.  Memory usage		|riscos-memory|
9.  Filetypes			|riscos-filetypes|
10. Porting new releases	|riscos-porting|

If I've missed anything, email me and I'll try to fix it.  In fact, even if I
havn't missed anything then email me anyway to give me some confidence that it
actually works!

Thomas Leonard, tal197@ecs.soton.ac.uk

Port homepage: www.ecs.soton.ac.uk/~tal197
 
==============================================================================
							*riscos-locations*
1. File locations

The Vim executable and shared resource files are all stored inside the !Vim
application directory.

When !Vim is first seen by the filer, it aliases the *vi command to run the
command-line version of Vim. (see |riscos-commandline|)

!Vim.Resources contains the files from the standard Vim distribution, but
modified slightly to work within the limits of ADFS, plus some extra files
such as the window templates.

User choices are read from `Choices:*' and are saved to `<Choices$Write>.*'.
If you have the new !Boot structure then these should be set up already. If
not, set Choices$Path to a list of directories to search when looking for
user configuration files. Set Choices$Write to the directory you want files
to be saved into (so your search patterns and marks can be remembered between
sessions).

==============================================================================
							*riscos-munging*
2. Filename munging

All pathname munging is disabled by default, so Vim should behave like a
normal RISC OS application now. So, if you want to edit `doc/html' then you
actually type `*vi doc/html'.

The only times munging is done is when:

- Searching included files from C programs, since these are always munged.
  See |[I|.
  Note: make sure you are in the right directory when you use this
	command (ie the one with subdirectories 'c' and 'h').

- Sourcing files using |:so|.
  Paths starting `$VIM/' are munged like this:

  $VIM/syntax/help.vim  ->  Vim:syntax.help

Also, files ending in `.vim' have their extensions removed, and slashes
replaced with dots.

Tag files and some script files may have to be edited to work under this port.

==============================================================================
							*riscos-commandline*
3. Command-line use

To use Vim from the command-line, use the `*vi' command.

Type `*vi -h' for a list of options.

Running the command-line version of VIM in a large high-colour mode may cause
the scrolling to be very slow. Either change to a mode with less colours or
use the GUI version.

Also, holding down Ctrl will slow it down even more, and Ctrl-Shift will
freeze it, as usual for text programs.

==============================================================================
							*riscos-gui*
4. Desktop use

The desktop version of Vim is not yet complete. The major things missing are:

- Clicking on the status bar causes the mouse to behave strangly.
  Do |CTRL-L| to reset it.
- Only the system font is supported.
- Runs rather slowly if another program is using null-polls (eg Browse)
- Right scrollbars don't work properly.
- Doesn't increase scroll speed if it gets behind.

You can resize the window by dragging the lower-right corner, even though
there is no icon shown there.

Mouse selections do work however, and the global clipboard is supported.

Clicking Menu now opens a menu like a normal RISC OS program. Hold down Shift
when clicking Menu to paste.

Dragging a file to the window replaces the CURRENT buffer (the one with the
cursor, NOT the one you dragged to) with the file.

Dragging with Shift held down causes a new Vim window to be opened for the
file (see |:sp|).

If you find the scrolling is too slow on your machine, try experimenting
with the 'scrolljump' and 'ttyscroll' options.

In particular, StrongARM users may find that:

> :set ttyscroll=0

makes scrolling faster in high-colour modes.

=============================================================================
							*riscos-remote*
5. Remote use (telnet)

I have included a built-in termcap entry, but you can edit the termcap file to
allow other codes to be used if you want to use Vim from a remote terminal. 

I cannot test this myself. If you manage to use the RISC OS port of Vim
remotely then please send me a copy of your TermCap file so I can include it
in future releases.

==============================================================================
							*riscos-temp-files*
6. Temporary files

If Vim crashes then the swap and backup files (if any) will be in the
directories set with the |'directory'| and |'bdir'| options. By default the
swap files are in <Wimp$ScrapDir> (ie inside !Scrap) and backups are in the
directory you were saving to. Vim will allow you to try and recover the file
when you next try to edit it.

To see a list of swap files, press <F12> and type `*vi -r'.

==============================================================================
							*riscos-interrupt*
7. Interrupting

To break out of a looping macro, or similar, hold down Escape in the
command-line version, or press CTRL-C in the GUI version.

==============================================================================
							*riscos-memory*
8. Memory usage

Vim will use dynamic areas on RISC OS 3.5 or later. If you can use them on
older machines then edit the !RunTxt and GVim files. I don't know what UnixLib
does by default on these machines so I'm playing safe.

It probably doesn't work terribly well without dynamic areas.

==============================================================================
							*riscos-filetypes*
9. Filetypes

You can now specify that autocommands are only executed for files of certain
types. The filetype is given in the form &xxx, when xxx is the filetype.

Filetypes must be specified by number (eg &fff for Text).

See |+filetype| for details of the filetype checking system.

==============================================================================
							*riscos-porting*
10. Porting new releases to RISC OS

Downloading everything you need:

- Get the latest source distribution (see www.vim.org)
- Get the runtime environment files (eg these help files)
- Get the `extra' archive (contains the RISC OS specific bits)
- Get the RISC OS binary distribution (if possible)


Unarchiving:

- Create a raFS disk (called VimSrc) and put the archives on it.
- Un-gzip them
- Un-tar them   (*tar xELf 50 archive/tar)


Recompiling the sources:

- Create c, s, and h directories.
- Put all the header files in 'h'            \ 
- Put all the C files in 'c'                 | And lose the extensions
- Put the assembler file ('swis/s') in 's'   /
- Rename all the files in 'proto' to 'h', like this:
    raFS::VimSrc.source.proto.file/pro
          becomes
    raFS::VimSrc.source.h.file_pro
- In the files 'h.proto' and 'c.termlib', search and replace
    .pro"
       with
    _pro.h"
- Create a simple Makefile if desired and do '*make -k'
  Use 'CC = gcc -DRISCOS -DUSE_GUI -O2 -x c' in the Makefile
- Save the binary as !Vim.Vim in the binary distribution

Updating the run-time environment:

- Replace old or missing files inside !Vim.Resources with the
  new files.
- Remove files in `doc' not ending in `/txt', except for `tags'.
- Lose the extensions from the files in `doc'.
- Edit the `doc.tags' file. Remove extensions from the second column:
  :%s/^\(.[^\t]*\t.*\)\.txt\t/\1\t/
- Remove extensions from the syntax files. Split them into two directories
  to avoid the 77 entry limit on old ADFS filesystems.
- Edit `syntax.scripts' to reference the new files:
  %s/<sfile>:p:h/$VIM\/syntax 
- Edit `syntax.syntax' to match `*.c.*' as well as `*/c' and so on.
- Edit `Vim:Menu' and remove all the keys from the menus:
  :%s/<Tab>[^ \t]*// 
  Remove menus that have no meaning under RISC OS (Open and Split-Open).

 vim:ts=8:sw=8:tw=78:
