Merge branch 'mac-installer' into 'master'

Updated the macOS installation guide

See merge request openlp/documentation!21

manual/source/install_mac.rst

@@ -2,45 +2,58 @@ Installing OpenLP on macOS
 ==========================
 
 If you have not already downloaded the correct file from the `OpenLP website`_, download it now. Then double click on
-the .dmg file. This will open a window with two icons: An OpenLP icon and an Applications Folder icon. To install
-OpenLP, simply drag the OpenLP icon over to the Applications folder icon and you will be ready to use OpenLP. OpenLP
-will be available in your Applications folder.
+the .dmg file. This will open a window with two icons: An OpenLP icon and an Applications Folder icon. 
 
 .. image:: pics/install-macos-01-dnd-install.png
 
-With the release of Mac OS X 10.7.5, applications that are not signed by a developer registered with Apple will not run
-by default. In order to run OpenLP the first time after installation, you will need to "teach" your computer to trust
-the OpenLP application.
+To install OpenLP, simply drag the OpenLP icon over to the Applications folder icon. A window will show the installation
+progress.
 
-First, go to the :guilabel:`Applications` folder and right-click on OpenLP (two-finger click on touch pads, or
-:kbd:`Control+click` if you don't have a right mouse button). This will bring up a context menu as shown. Select "Open"
-from that menu.
+.. image:: pics/install-macos-02-install-progress.png
 
-.. image:: pics/install-macos-02-open.png
-   :width: 40%
-   :align: center
-
-Your computer may then verify the application, which will take a few seconds.
+Since OpenLP is an Open Source project we do not have the finacial means to buy an official Apple Developer certificate,
+which means that macOS will refuse to open OpenLP because it has not been signed by an official Apple Developer
+certificate. We do assure you that if you downloaded OpenLP from the `OpenLP website`_, it is safe to install and run.
+To start OpenLP open the :guilabel:`Applications` folder, find the OpenLP icon an click it. The first time you start
+OpenLP a window will open showing the verification progress.
 
 .. image:: pics/install-macos-03-verifying.png
 
-You will see a prompt asking whether you are sure you want to open "OpenLP", noting that it is from an unidentified
-developer. It will look very similar to the pictured dialog.
+The verification will fail and show this warning:
 
-To run OpenLP you simply need to click "Open". In future, you can simply run OpenLP just like any other application
-(double-click in Applications, or keep it in the Dock for easy access) without going through these steps.
+.. image:: pics/install-macos-04-verification-failed.png
 
-.. image:: pics/install-macos-04-unidentified-developer.png
+Click :guilabel:`OK` to close the window. You will now have to tell macOS to trust OpenLP despite this.
+Open the Apple menu and choose :guilabel:`System Preferences...`. Now click :guilabel:`Security & Privacy` as marked
+below.
 
-You may need to repeat similar steps when you upgrade OpenLP (once per upgrade).
+.. image:: pics/install-macos-05-system-pref.png
 
-If the steps above don't work, you may need to set your GateKeeper settings (under :guilabel:`Security && Privacy`) to
-"Mac App Store and identified developers", as seen below.
+In the default :guilabel:`General` tab you should now see a window similar to the one below. Click the
+:guilabel:`Open Anyway` button to open OpenLP.
 
-.. image:: pics/install-macos-05-system-menu.png
+.. image:: pics/install-macos-06-security-privacy.png
 
-.. image:: pics/install-macos-06-settings.png
+macOS will now try to open OpenLP again. Again a window will open showing the verification progress.
 
-.. image:: pics/install-macos-07-security-and-privacy.png
+.. image::  pics/install-macos-07-verifying-again.png
+
+A window will now open with a warning that OpenLP is unsafe. Click :guilabel:`Open` to open OpenLP.
+
+.. image::  pics/install-macos-08-open-anyway.png
+
+The first time OpenLP runs you will be prompted about granting some extra rights to OpenLP. OpenLP uses these rights to
+control PowerPoint and Keynote presentation programs. Click :guilabel:`OK` to allow this.
+
+.. image::  pics/install-macos-09-allow-finder-access.png
+
+.. image::  pics/install-macos-10-allow-system-event-access.png
+
+The first time you start a PowerPoint or Keynote presentation from OpenLP you will also be asked to grant rights to
+those applications as can be seen below. Again click :guilabel:`OK` to allow this.
+
+.. image::  pics/install-macos-11-allow-powerpoint-access.png
+
+.. image::  pics/install-macos-12-allow-keynote-access.png
 
 .. _OpenLP website: https://openlp.org/