From 5742127dff8ed9fee478bdba938072463ca0eb00 Mon Sep 17 00:00:00 2001
From: Hugo Locurcio <hugo.locurcio@hugo.pro>
Date: Wed, 30 Mar 2022 18:08:02 +0200
Subject: [PATCH] Improve formatting in README, add note about running from
 editor

---
 README.md | 96 +++++++++++++++++++++++++++++++------------------------
 1 file changed, 55 insertions(+), 41 deletions(-)

diff --git a/README.md b/README.md
index 31b0ab8..2e3656e 100644
--- a/README.md
+++ b/README.md
@@ -1,55 +1,69 @@
 # Godot iOS plugins
 
-`master` branch is current development branch and can introduce breaking changes to plugin's public interface. 
-`3.3` branch aim is to provide same public interface as it was before switch to new iOS plugin system. 
+[`master` branch](https://github.com/godotengine/godot-ios-plugins/tree/master) is the current development branch and can introduce breaking changes to plugin's public interface.
+[`3.3` branch](https://github.com/godotengine/godot-ios-plugins/tree/3.3)'s aim is to provide same public interface as it was before the switch to new iOS plugin system.
+
+**Note:** iOS plugins are only effective on iOS (either on a physical device or
+in the Xcode simulator). Their singletons will *not* be available when running
+the project from the editor, so you need to export your project to test your changes.
 
 ## Instructions
 
-* Clone this repository and it's submodules:
-  ```
-  git clone --recurse-submodules https://github.com/godotengine/godot-ios-plugins
-  ```
-  You might require to update `godot` submodule in case you require latest (unreleased) Godot changes. To do this run:
-  ```
-  cd godot
-  git fetch
-  git checkout origin/<branch you want to use>
-  ```
-
-* Alternatively you can use pre-extracted Godot headers that will be provided with release tag at [Releases page](https://github.com/godotengine/godot-ios-plugins/releases).  
-  To do this clone this repo without submodules:
-  ```
-  git clone https://github.com/godotengine/godot-ios-plugins
-  ```
-  Then place extracted Godot headers in `godot` directory.  
-  If you choose this option you can skip next step to genarate of Godot headers.
-
-* To generate Godot headers you need to run compilation command inside `godot` submodule directory. 
-  Example:
-  ```
-  scons platform=iphone target=debug
-  ```
-  You don't have to wait for full engine compilation as header files are generated first, so once an actual compilation starts you can stop this command.
-
-* Running
-  ```
-  scons target=<debug|release|release_debug> arch=<arch> simulator=<no|yes> plugin=<plugin_name> version=<3.x|4.0>
-  ```
-  will generate `.a` static library for chosen target.  
-  Do note, that Godot's default `debug` export template is compiled with `release_debug` target.
+- Clone this repository and its submodules:
 
-## Building a `.a` library
+```bash
+git clone --recursive https://github.com/godotengine/godot-ios-plugins.git
+```
 
-* Run `./scripts/generate_static_library.sh <plugin_name> <debug|release|release_debug> <godot_version>` to generate `fat` static library with specific configuration.
+You might have to the update `godot` submodule in case you require latest (unreleased) Godot changes. To do this, run:
 
-* The result `.a` binary will be stored in `bin` folder.
+```bash
+cd godot
+git fetch
+git checkout origin/<branch you want to use>
+```
 
-## Building a `.xcframework` library
+- Alternatively, you can use pre-extracted Godot headers that will be provided
+  with release tag on the [Releases page](https://github.com/godotengine/godot-ios-plugins/releases).
+  To do this, clone this repository without submodules:
+
+```bash
+git clone https://github.com/godotengine/godot-ios-plugins.git
+```
+
+Then place the extracted Godot headers in the `godot/` directory.
+If you choose this option, you can skip next the step which generates Godot headers.
+
+- To generate Godot headers, you need to run the compilation command inside the `godot` submodule directory:
+
+```bash
+scons platform=iphone target=debug
+```
+
+You don't have to wait for full engine compilation, as header files are generated first.
+Once the actual compilation starts, you can stop this command by pressing <kbd>Ctrl + C</kbd>.
 
-* Run `./scripts/generate_xcframework.sh <plugin_name> <debug|release|release_debug> <godot_version>`  to generate `xcframework` with specific configuration. `xcframework` allows plugin to support both `arm64` device and `arm64` simulator.
+- Run the command below to generate an `.a` static library for chosen target:
+
+```bash
+scons target=<debug|release|release_debug> arch=<arch> simulator=<no|yes> plugin=<plugin_name> version=<3.x|4.0>
+```
+
+**Note:** Godot's official `debug` export templates are compiled with the `release_debug` target, *not* the `debug` target.
+
+## Building a `.a` library
+
+- Run `./scripts/generate_static_library.sh <plugin_name> <debug|release|release_debug> <godot_version>`
+  to generate `fat` static library with specific configuration.
+- The result `.a` binary will be stored in the `bin/` folder.
+
+## Building a `.xcframework` library
 
-* The result `.xcframework` will be stored in `bin` folder as well as intermidiate `.a` binaries.
+- Run `./scripts/generate_xcframework.sh <plugin_name> <debug|release|release_debug> <godot_version>`
+  to generate `xcframework` with specific configuration.
+  `xcframework` allows plugin to support both `arm64` device and `arm64` simulator.
+- The result `.xcframework` will be stored in the `bin/` folder as well as intermidiate `.a` binaries.
 
 ## Documentation
 
-Each plugin provides a `README.md` file which contains a documentation and examples.
\ No newline at end of file
+Each plugin provides a `README.md` file which contains documentation and examples.