Welcome to Iris
=-=-=-=-=-=-=-=

This is a beta version of the Iris browser.  It is a full port
of a modern (late 2020) build of WebKit (2.30.3 at the time of
writing), the engine that powers browsers such as Apple's Safari.

This means it includes full JavaScript and also HTML 5 support,
over regular and SSL/TLS links.  Being a huge project, WebKit
isn't the fastest of engines, but it opens up vast swathes of the
Web to RISC OS.

Since this release is a beta, please do not expect "finished 
product" levels of presentation, reliability or performance.
This is a work-in-progress release, and many things may be 
incomplete or unfinished (including this documentation). 
However, we believe that the browser has advanced to a point
where it offers meaningful advantages over other alternatives.


IMPORTANT
---------

If you have run a previous version of Iris, please shift double
click on !Boot and go to "Choices", then "WWW" and delete the
"Iris" folder.   (Note - probably not necessary if your previous
version was dated January 2021 or later)

If you have unexpected behaviour with Iris, we recommend deleting
!Iris and installing a fresh copy from the zip.  Some users have
reported issues when copying a new !Iris over the top of an older
version.

Copy the enclosed !Boot over your existing one.  It contains a
Choices folder called "icons" which contains some common open
source icons used by the cross platform WebKit engine that
powers Iris.

For further troubleshooting, please see the "Resolving Issues"
section below.


Facilities
----------

Iris supports multiple windows, and tabbed browsing.

It has good Javascript compatibility and page rendering.
Javascript JIT now implemented for performance gains

Bookmarks are possible

Copy/Paste via Ctrl-C / Ctrl-V (RISC OS 5.28+ recommended)

File downloads are possible, and use a pleasant RISC OS
download window.

Search pages with F4

Save pages as Sprite or text

Zoom in/out (Ctrl-Up/Down)

Scroll via scroll wheel

Resizeable main window

RISC OS URL/URI launch protocols

RISC OS HTML / JavaScript / URL files as follows:
    
   Double click file - load file in new window
      Supported filetypes:
        HTML, JSScript, AntURL, AcornURI
   Drag to icon bar - load file in new window
   Drag to browser window - load file in to current tab
   Drag to tab on tab bar - load file to that tab
   Drag to tab bar, but not a tab - load file to new tab
      Supported filetypes:
        HTML, JSScript, AntURL, AcornURI, PNG, GIF, JPG
   Drag to Choices window, New Tab URI, Home URL
      Replace text with path of dragged file.
      For AcornURI and AntURL files, extract URL from file and
      use that as file path.


Keyboard shortcuts
------------------
CTRL+1-8 - Switch to tab 1-8. Note that there are some key clashes, e.g., CTRL+1 is
the same as CTRL+A.
CTRL+9 - Switch to last tab.
CTRL+TAB - Switch to next tab (right of current).
CTRL+SHIFT+TAB - Switch to previous tab (left of current).
F4 - Open find window
CTRL+Up - Zoom in
CTRL+Down - Zoom out
CTRL+W/CTRL+F4 - Close current tab
CTRL+T - Open new tab
CTRL+N - Open new window
CTRL+Left - Go back a page. Note that writable icons also use this.
CTRL+Right - Go forward a page. Note that writable icons also use this.
F5 - Reload tab
CTRL+F5 - Reload tab bypassing the cache
CTRL+Home - Load configured home URI
Escape - Stop current page load

System variables
----------------
WebKit$ProcessToStderr - If set redirect stderr/stdout to file, otherwise to null:
WebKit$DebugMessages - If set print IPC messages to reporter
Iris$WebInspector - If set add Inspector to browser menu.

File Upload Selection Window
----------------------------

Generated by HTML 'input' tag with type 'file'.
Supports the 'multiple' flag. If present, multiple files can be selected
including directories. If the 'multiple' tag is missing, then only one
file can be selected and directories are rejected. Attempts to select a
second file will replace the one already present.
The filter tag is not currently supported.
Top buttons are 'remove selected', 'select all' and 'clear selection'.


Password Manager
----------------
PasswordSave Window is shown when a form is submitted that contains username
and password and there isn't already an entry stored in the passwords file.
PasswordViewer is opened from iconbar menu or utilities menu.
Passwords are not shown initially.
Double click entry to open password editor.
Username and password can be edited or the entry can be deleted.
Passwords are stored on disc in an encoded format that is tied to the machine ID.
Password files can not be moved from one machine to another.
Attempts are made to minimise plain text passwords in memory.
Toolbox fields are overwritten before window is closed.
Where passwords are decoded to strings for display, the strings are overwritten
before being destroyed.


New Bookmark manager
--------------------
Uses XML file for storage.
Supports drag and drop of entries to move/copy.
Drag and drop copies by default - press shift at end of drag to move.
Hovering over a folder whilst dragging will open that folder after 1 sec.
  (Hovering is now restricted to the sprite only and not the text to aid in
  auto-scrolling)
Tabs are used to represent "Bookmark bar" and "Other bookmarks".
Hovering over a tab will switch to that tab.
All folders except the base ones have a parent entry at the top to allow navigation
  back up.
Dragging out of the window is not yet supported.
Dragging AcornURI/ANTURL files to a folder will open the new bookmark dialogue.
Bookmark dialogue boxes have a location entry that can be changed via a menu.
A location bar shows the location of the current folder and each element
  of that location is clickable to navigate to that folder.
Changes are immediate and saved to disc when the window is closed.
Adjust double click edits the entry.
New User sort type; User can place entries in any order using drag and drop.
Editing Bookmark bar entries forces User sort type.
Star button on toolbar allows current page to be added/removed, turns yellow if
  bookmark is already present.

Bookmark bar
------------
Entries are added/edited/deleted from the "Bookmark bar" tab of the bookmark manager.
Any entries that don't fit the window width are added to a menu at the right hand
  side of the bookmark bar.
Entries are shown in the order they appear in the bookmark manager (custom sorting
  is enforced to ensure this).



Alignment Exceptions
--------------------

Iris is a hugely complex and cutting edge (beta) piece of software
that makes use of technologies never seen/used before on RISC OS.
It is probably (one of) the most ambitious project(s) ever to be
released for our beloved OS.

In order to be able to track real-world developments, Iris is (as
you have read above) based on the cross-platform WebKit project.
Some elements of Webkit, most notably the half-word Thumb2 
JavaScript JIT (Just In Time) compiler, require alignment
exceptions to be disabled to function correctly.

Whilst we intend to investigate this further in the fulness of
time, for now (if you have enabled Alignment Exceptions on your
machine) you will be prompted when running Iris whether it 
should disable exceptions for correct operation, or continue 
unchanged, which may result in unexpected failures (eg. sites
failing to render) when using Iris.

Note that a majority of RISC OS computers run with alignment
exceptions disabled all the time, as it allows some older
application to work on modern RISC OS CPUs (and indeed, ROOL
provide a !Configure plugin called "CPU Setup" to control
this behaviour).  That being said, we know a portion of users
feel very strongly that alignment exceptions should always
be enabled.

For now, please understand that if the WebKit developers choose
to write code in this manner, Iris has little choice but to
co-operate, and for now that means we strongly recommend 
disabling alignment exceptions.  Thanks for understanding.
        


Known issues
------------

Iris takes time to load, and needs a fairly fast computer
(ARMX6 minimum recommended spec).

Scrolling doesn't use RISC OS scrollbars etc.



Resolving issues
----------------

If Iris won't load, try running KillSOM obey file.

If it still won't load, try finding !SharedLibs in !Boot.Resources
and moving it out of there into a temporary folder that isn't seen
at startup.  Then reboot.

!Iris should be self-contained.

Make sure you're running RISC OS 5.28+ in 16 million colours, and
have at least 1GB of RAM.  Yes, you read that right, 1GB RAM.
Resolution should be 1920x1080 ideally.

Note - Iris should now run in most colour depths and resolutions.

DO NOT RUN AEMULOR.

If you receive an error about other SharedUnixLib tasks running,
it is because Iris needs to load a new version of that module to
support its cutting-edge tech (this is also why it is stored in
Iris, rather than updating your !System with a beta version).
Common programs that use that module include NetSurf and other
ported programs.  If problems persist, you can copy the SharedULib
module from !Iris.Resources into !Boot.Resources.!System.310.Modules


Iris seems more stable if Alignment Exceptions are turned off.
To check this, double click on !Boot on your main drive, to
bring up the Configure screen.  You should see a section called
"AlignEx", "Alignment" or "CPU".  Click this, and make sure
that Alignment Exceptions are disabled, and (if given the
choice) your CPU is in ARMv7 mode.



Reporting problems
------------------

Please think twice before reporting issues - if you do, collate
things together so that we aren't bombarded.

DO NOT EXPECT A REPLY.  This is not us being discourteous, but
support for Iris is an unpaid role, and a time consuming one.
Rest assured that we *do* read emails, and pass them on to
programmers as necessary.

We don't have the resources/time to handle a lot of feedback yet. 
A bug-reporting web database (powered by RISC OS) is under
development, but is not yet ready for public use.  Expect more
info on this in a future update.

We're well aware of issues, and are working to make things better
all the time.  For now, please just enjoy it for what it is. 
We'll let you know when we're at a feedback stage.

If you absolutely can't get it to run at all, then we can try and
help with that.  Remember to include machine spec, OS version and
date, and a list of other programs currently running/seen.



Dedication
----------

Iris is dedicated to the memory of our friend and colleague Mr
Edward "Ted" Olley.  Ted was instrumental in the founding of
RISC OS Developments, and RISC OS / Iris wouldn't be where it is
today without his belief, support and vision. Ted, you are missed.


Licence acknowledgments
-----------------------

Iris uses icons derived from the Tango Desktop icon project at
http://tango.freedesktop.org


Unixlib library.
Copyright (c) 1995-2009 UnixLib Developers
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
3. The name of the author may not be used to endorse or promote products
   derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


UnixLib has been updated with VFP/NEON routines.
Copyright (c) 2019, RISC OS Open Ltd
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
     * Redistributions of source code must retain the above copyright
       notice, this list of conditions and the following disclaimer.
     * Redistributions in binary form must reproduce the above copyright
       notice, this list of conditions and the following disclaimer in the
       documentation and/or other materials provided with the distribution.
     * Neither the name of the copyright holder nor the
       names of its contributors may be used to endorse or promote products
       derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.



WebKit open source web browser engine.
Copyright (C) 2015 Apple, Inc.

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Library General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Library General Public License for more details.

You should have received a copy of the GNU Library General Public
License along with this library; if not, write to the
Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
Boston, MA 02110-1301, USA.

BSD License
Copyright (C) 2009 Apple Inc. All rights reserved.

Redistribution and use in source and binary forms, with or
without modification, are permitted provided that the following
conditions are met:

Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in
the documentation and/or other materials provided with the
distribution.

THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.