runtime/doc/os_risc.txt

   1 *os_risc.txt*   For Vim version 7.1.  Last change: 2005 Mar 29
   2
   3
   4                   VIM REFERENCE MANUAL    by Thomas Leonard
   5
   6
   7                                                 *riscos* *RISCOS* *RISC-OS*
   8 This file contains the particularities for the RISC OS version of Vim.
   9
  10 The RISC OS port is a completely new port and is not based on the old `archi'
  11 port.
  12
  13 1.  File locations              |riscos-locations|
  14 2.  Filename munging            |riscos-munging|
  15 3.  Command-line use            |riscos-commandline|
  16 4.  Desktop (GUI) use           |riscos-gui|
  17 5.  Remote use (telnet)         |riscos-remote|
  18 6.  Temporary files             |riscos-temp-files|
  19 7.  Interrupting                |riscos-interrupt|
  20 8.  Memory usage                |riscos-memory|
  21 9.  Filetypes                   |riscos-filetypes|
  22 10. The shell                   |riscos-shell|
  23 11. Porting new releases        |riscos-porting|
  24
  25 If I've missed anything, email me and I'll try to fix it.  In fact, even if I
  26 haven't missed anything then email me anyway to give me some confidence that it
  27 actually works!
  28
  29 Thomas Leonard <tal197@ecs.soton.ac.uk>
  30
  31         [these URLs no longer work...]
  32  Port homepage: http://www.ecs.soton.ac.uk/~tal197/
  33         or try: http://www.soton.ac.uk/~tal197/
  34
  35 ==============================================================================
  36                                                         *riscos-locations*
  37 1. File locations
  38
  39 The Vim executable and shared resource files are all stored inside the !Vim
  40 application directory.
  41
  42 When !Vim is first seen by the filer, it aliases the *vi and *ex commands to
  43 run the command-line versions of Vim (see |riscos-commandline|).
  44
  45 !Vim.Resources and !Vim.Resources2 contain the files from the standard Vim
  46 distribution, but modified slightly to work within the limits of ADFS, plus
  47 some extra files such as the window templates.
  48
  49 User choices are read from `Choices:*' and are saved to `<Choices$Write>.*'.
  50 If you have the new !Boot structure then these should be set up already.  If
  51 not, set Choices$Path to a list of directories to search when looking for
  52 user configuration files.  Set Choices$Write to the directory you want files
  53 to be saved into (so your search patterns and marks can be remembered between
  54 sessions).
  55
  56 ==============================================================================
  57                                                         *riscos-munging*
  58 2. Filename munging
  59
  60 All pathname munging is disabled by default, so Vim should behave like a
  61 normal RISC OS application now.  So, if you want to edit `doc/html' then you
  62 actually type `*vi doc/html'.
  63
  64 The only times munging is done is when:
  65
  66 - Searching included files from C programs, since these are always munged.
  67   See |[I|.
  68   Note: make sure you are in the right directory when you use this
  69         command (i.e. the one with subdirectories 'c' and 'h').
  70
  71 - Sourcing files using |:so|.
  72   Paths starting `$VIM/' are munged like this:
  73
  74   $VIM/syntax/help.vim  ->  Vim:syntax.help
  75
  76   Also, files ending in `.vim' have their extensions removed, and slashes
  77   replaced with dots.
  78
  79 Some tag files and script files may have to be edited to work under this port.
  80
  81 ==============================================================================
  82                                                         *riscos-commandline*
  83 3. Command-line use
  84
  85 To use Vim from the command-line use the `*vi' command (or '*ex' for
  86 |Ex-mode|).
  87
  88 Type `*vi -h' for a list of options.
  89
  90 Running the command-line version of Vim in a large high-color mode may cause
  91 the scrolling to be very slow.  Either change to a mode with fewer colors or
  92 use the GUI version.
  93
  94 Also, holding down Ctrl will slow it down even more, and Ctrl-Shift will
  95 freeze it, as usual for text programs.
  96
  97 ==============================================================================
  98                                                         *riscos-gui*
  99 4. Desktop use
 100
 101 Limitations:
 102
 103 - Left scrollbars don't work properly (right and bottom are fine).
 104 - Doesn't increase scroll speed if it gets behind.
 105
 106 You can resize the window by dragging the lower-right corner, even though
 107 there is no icon shown there.
 108
 109 You can use the --rows and --columns arguments to specify the initial size of
 110 the Vim window, like this: >
 111
 112   *Vi -g --rows 20 --columns 80
 113
 114 The global clipboard is supported, so you can select some text and then
 115 paste it directly into another application (provided it supports the
 116 clipboard too).
 117
 118 Clicking Menu now opens a menu like a normal RISC OS program.  Hold down Shift
 119 when clicking Menu to paste (from the global clipboard).
 120
 121 Dragging a file to the window replaces the CURRENT buffer (the one with the
 122 cursor, NOT the one you dragged to) with the file.
 123
 124 Dragging with Ctrl held down causes a new Vim window to be opened for the
 125 file (see |:sp|).
 126
 127 Dragging a file in with Shift held down in insert mode inserts the pathname of
 128 the file.
 129
 130 :browse :w opens a standard RISC OS save box.
 131 :browse :e opens a directory viewer.
 132
 133 For fonts, you have the choice of the system font, an outline font, the system
 134 font via ZapRedraw and any of the Zap fonts via ZapRedraw: >
 135
 136   :set guifont=
 137 <                       To use the system font via the VDU drivers.  Supports
 138                         bold and underline.
 139 >
 140   :set guifont=Corpus.Medium
 141 <                       Use the named outline font.  You can use any font, but
 142                         only monospaced ones like Corpus look right.
 143 >
 144   :set guifont=Corpus.Medium:w8:h12:b:i
 145 <                       As before, but with size of 8 point by 12 point, and
 146                         in bold italic.
 147                         If only one of width and height is given then that
 148                         value is used for both.  If neither is given then 10
 149                         point is used.
 150
 151 Thanks to John Kortink, Vim can use the ZapRedraw module.  Start the font name
 152 with '!' (or '!!' for double height), like this: >
 153
 154   :set guifont=!!
 155 <                       Use the system font, but via ZapRedraw.  This gives a
 156                         faster redraw on StrongARM processors, but you can't
 157                         get bold or italic text.  Double height.
 158 >
 159   :set guifont=!script
 160 <                       Uses the named Zap font (a directory in VimFont$Path).
 161                         The redraw is the same speed as for '!!', but you get
 162                         a nicer looking font.
 163                         Only the "man+" and "script" fonts are supplied
 164                         currently, but you can use any of the Zap fonts if
 165                         they are in VimFont$Path.
 166                         Vim will try to load font files '0', 'B', 'I' and 'IB'
 167                         from the named directory.  Only '0' (normal style) MUST
 168                         be present.  Link files are not currently supported.
 169
 170 Note that when using ZapRedraw the edit bar is drawn in front of the character
 171 you are on rather than behind it.  Also redraw is incorrect for screen modes
 172 with eigen values of 0.  If the font includes control characters then you can
 173 get Vim to display them by changing the 'isprint' option.
 174
 175 If you find the scrolling is too slow on your machine, try experimenting
 176 with the 'scrolljump' and 'ttyscroll' options.
 177
 178 In particular, StrongARM users may find that: >
 179
 180   :set ttyscroll=0
 181
 182 makes scrolling faster in high-color modes.
 183
 184 =============================================================================
 185                                                         *riscos-remote*
 186 5. Remote use (telnet)
 187
 188 I have included a built-in termcap entry, but you can edit the termcap file to
 189 allow other codes to be used if you want to use Vim from a remote terminal.
 190
 191 Although I do not have an internet connection to my Acorn, I have managed to
 192 run Vim in a FreeTerm window using the loopback connection.
 193
 194 It seems to work pretty well now, using '*vi -T ansi'.
 195
 196 ==============================================================================
 197                                                         *riscos-temp-files*
 198 6. Temporary files
 199
 200 If Vim crashes then the swap and backup files (if any) will be in the
 201 directories set with the 'directory' and 'bdir' options.  By default the swap
 202 files are in <Wimp$ScrapDir> (i.e. inside !Scrap) and backups are in the
 203 directory you were saving to.  Vim will allow you to try and recover the file
 204 when you next try to edit it.
 205
 206 To see a list of swap files, press <F12> and type `*vi -r'.
 207
 208 Vim no longer brings up ATTENTION warnings if you try to edit two files with
 209 the same name in different directories.
 210
 211 However, it also no longer warns if you try to edit the same file twice (with
 212 two copies of Vim), though you will still be warned when you save that the
 213 datestamp has changed.
 214
 215 ==============================================================================
 216                                                         *riscos-interrupt*
 217 7. Interrupting
 218
 219 To break out of a looping macro, or similar, hold down Escape in the
 220 command-line version, or press CTRL-C in the GUI version.
 221
 222 ==============================================================================
 223                                                         *riscos-memory*
 224 8. Memory usage
 225
 226 Vim will use dynamic areas on RISC OS 3.5 or later.  If you can use them on
 227 older machines then edit the !RunTxt and GVim files.  I don't know what UnixLib
 228 does by default on these machines so I'm playing safe.
 229
 230 It doesn't work at all well without dynamic areas, since it can't change its
 231 memory allocation once running.  Hence you should edit `!Vim.GVim' and
 232 `!Vim.!RunTxt' to choose the best size for you.  You probably need at least
 233 about 1400K.
 234
 235 ==============================================================================
 236                                                         *riscos-filetypes*
 237 9. Filetypes
 238
 239 You can now specify that autocommands are only executed for files of certain
 240 types.  The filetype is given in the form &xxx, when xxx is the filetype.
 241
 242 Filetypes must be specified by number (e.g. &fff for Text).
 243
 244 The system has changed from version 5.3.  The new sequence of events is:
 245
 246 - A file is loaded. |'osfiletype'| is set to the RISC OS filetype.
 247 - Based on the filetype and pathname, Vim will try to set |'filetype'| to the
 248   Vim-type of the file.
 249 - Setting this option may load syntax files and perform other actions.
 250 - Saving the file will give it a filetype of |'osfiletype'|.
 251
 252 Some examples may make this clearer:
 253
 254   Kind of file loaded   osfiletype      filetype ~
 255   C code 'c.hellow'     Text (&fff)     C
 256   LaTeX document        LaTeX (&2a8)    TeX
 257   Draw document         DrawFile (&aff) (not changed)
 258
 259 ==============================================================================
 260                                                         *riscos-shell*
 261 10. The shell
 262
 263 - Bangs (!s) are only replaced if they are followed by a space or end-of-line,
 264   since many pathnames contain them.
 265
 266 - You can prefix the command with '~', which stops any output from being
 267   displayed.  This also means that you don't have to press <Enter> afterwards,
 268   and stops the screen from being redrawn. {only in the GUI version}
 269
 270 ==============================================================================
 271                                                         *riscos-porting*
 272 11. Porting new releases to RISC OS
 273
 274 Downloading everything you need:
 275
 276 - Get the latest source distribution (see www.vim.org)
 277 - Get the runtime environment files (e.g. these help files)
 278 - Get the `extra' archive (contains the RISC OS specific bits)
 279 - Get the RISC OS binary distribution (if possible)
 280
 281
 282 Unarchiving:
 283
 284 - Create a raFS disk and put the archives on it
 285 - Un-gzip them
 286 - Un-tar them   (*tar xELf 50 archive/tar)
 287
 288
 289 Recompiling the sources:
 290
 291 - Create c, s, and h directories.
 292 - Put all the header files in 'h'.           \
 293 - Put all the C files in `c'.                | And lose the extensions
 294 - Put the assembler file (`swis/s') in 's'.  /
 295 - Rename all the files in `proto' to `h', like this:
 296     raFS::VimSrc.source.proto.file/pro
 297           becomes
 298     raFS::VimSrc.source.h.file_pro
 299 - In the files `h.proto' and `c.termlib', search and replace
 300     .pro"
 301        with
 302     _pro.h"
 303 - Create a simple Makefile if desired and do '*make -k'.
 304   Use 'CC = gcc -DRISCOS -DUSE_GUI -O2 -x c' in the Makefile.
 305 - Save the binary as !Vim.Vim in the binary distribution.
 306
 307
 308 Updating the run-time environment:
 309
 310 - Replace old or missing files inside !Vim.Resources with the
 311   new files.
 312 - Remove files in `doc' not ending in `/txt', except for `tags'.
 313 - Lose the extensions from the files in `doc'.
 314 - Edit the `doc.tags' file.  Remove extensions from the second column: >
 315         :%s/^\(.[^\t]*\t.*\)\.txt\t/\1\t/
 316 - Remove extensions from the syntax files.  Split them into two directories
 317   to avoid the 77 entry limit on old ADFS filesystems.
 318 - Edit `Vim:FileType' to match `*.c.*' as well as `*/c' and so on.
 319   Add filetype checking too.
 320 - Edit `Vim:Menu' and remove all the keys from the menus: >
 321         :%s/<Tab>[^ \t]*//
 322 <
 323  vim:tw=78:ts=8:ft=help:norl: