Finalize docs

.gitattributes

@@ -14,3 +14,4 @@ chromeos/** binary
 *.jar binary
 *.exe binary
 *.apk binary
+*.png binary

docs/README.MD

@@ -1,14 +1,11 @@
 # Magisk Documentations
-
+(Updated on 2017.8.16) ([Changelog](changelog.md))
-## Document Changelog
-- 2017.8.15
-    - Initial version for Magisk v13.5+
 
 ## Table of Content
 
 - [Introduction](#introduction)
-- [Magisk Details](details.md)
 - [Procedure Diagram](https://cdn.rawgit.com/topjohnwu/Magisk/cc1809688299f1f8b5db494a234850852712c0c9/docs/procedures.html)
+- [Magisk Details](details.md)    
     - [Boot Stages](details.md#boot-stages)
     - [Magic Mount Details](details.md#magic-mount-details)
     - [Simple Mount Details](details.md#simple-mount-details)
@@ -27,6 +24,4 @@
 
     
 ## Introduction
-Magisk is a suite of open source tools for devices running Android version higher than 5.0 Lollipop (API 21). It provides an environment which covers most Android aftermarket customization like root, boot scripts, SELinux patches, and also acts as a **Systemless Interface** to alter the system (or vendor) arbitrarily while the actual partitions stay completely intact, all of which accomplished by only patching the boot image, and adding some files into `/data`.
+Magisk is a suite of open source tools for devices running Android version higher than 5.0 Lollipop (API 21). It establishes an environment which covers most Android aftermarket customization needs, such as root, boot scripts, SELinux patches, dm-verity/forceencrypt patches etc.. Furthermore, Magisk also provides a **Systemless Interface** to alter the system (or vendor) arbitrarily while the actual partitions stay completely intact, all of which accomplished by only patching the boot image, and adding some files into `/data`. With its systemless nature along with several other hacks, Magisk can hide modifications from device integrity verifications, one of the main target is to hide from [Google's SafetyNet API](https://developer.android.com/training/safetynet/index.html).
-
-

docs/applets.md

@@ -2,7 +2,7 @@
 Magisk has a core binary which acts as a multi-call program with many applets. Here is an introduction to all available applets.
 
 ### magisk
-The magisk binary provides a lot of utility functions used in both Magisk installation and also module installation. It is also the entry point for `init` to invoke magisk's boot procedures.
+The magisk binary itself provides a lot of utility functions when called with the name `magisk`. They are used in both Magisk installation and module installation. The entry point for `init` to invoke magisk's boot procedures are also listed here.
 
 Command help message:
 
@@ -37,7 +37,7 @@ Supported applets:
 ```
 
 ### su
-The MagiskSU entrypoint. Call `su` to gain a root shell. **MagiskSU** has done several optimizations, check them out in the procedure diagram.
+The MagiskSU entrypoint. Call `su` to gain a root shell.
 
 Command help message:
 
@@ -60,16 +60,16 @@ Options:
                                 use if you need to publicly apply mounts
 ```
 
-Note: the `-Z --context` option still exists, but the option will do nothing since it's not needed anymore. It's still there because some apps requires specific context to work properly on legacy root implementations, and I don't want them to break.
+Note: even though the `-Z, --context` option is not listed above, it actually still exists. However MagiskSU will silently ignore the option since it's not needed anymore. It is still left over because some apps still request root shell with specific contexts as an option.
 
 ### resetprop
-An advanced system prop manipulation utility; using this tool, you can arbitrarily alter system props. Here's some background knowledge:
+An advanced system prop manipulation utility; you can arbitrarily alter system props using this tool. Here's some background knowledge:
 
-> System props are stored in a hybrid trie/binary tree data structure; it is originally designed to only support adding nodes, and no nodes will be removed. Props can be read by many processes (e.g. via the `getprop` command); however, only the `init` process can write to the data. `init` provides a `property_service` to accept property update requests, so all property changes are monitored and controlled by `init`. The restrictions of **read-only** props (props that starts with `ro.`), which they can only be set once and cannot be changed afterwards, is therefore implemented in `init`.
+> System props are stored in a hybrid trie/binary tree data structure in memory; it was originally designed to only support adding nodes, and no nodes should be removed. Props can be read by many processes (e.g. via the `getprop` command); however, only the `init` process have write access to the property data. `init` provides a `property_service` to accept property update requests, so all property changes are monitored and controlled by `init` Restrictions such as **read-only** props (props that starts with `ro.`), which can only be set once and cannot be changed afterwards, is therefore implemented in `init`.
 
-**resetprop** mimics what `init` is doing: directly accessing the data structure. This bypasses the whole `property_service` part, so we gain **arbitrary modification** power. Deleting properties, which was stated *"forbidden"* in the data structure is also implemented in resetprop through some tricks.
+**resetprop** acts just like `init`: directly access the data structure, bypassing the whole `property_service` part. Doing so, we gain **arbitrary modification** power, including altering read-only props and deleting properties. Delete properties, which was stated *"forbidden"* in the data structure, is implemented through some tricks in the data structure.
 
-One subtle thing to be aware of is that if we change props by directly modifying the data structure, `on property:foo=bar` triggers registered in `*.rc` scripts will not be triggered properly. This may be a good thing or a bad thing, depending on what result you want. I made the default behavior to match the original setprop command, which **will** trigger events, but still I provide a flag to disable it if you needed it.
+One subtle thing to be aware of is that if we change props by directly modifying the data structure, `on property:foo=bar` triggers registered in `*.rc` scripts will not be triggered properly. This may be a good thing or a bad thing, depending on what behavior you expect. I made the default behavior to match the original setprop command, which **WILL** trigger events, but of course I provide a flag (`-n`) to disable it if you need this special behavior.
 
 Command help message:
 
@@ -100,7 +100,7 @@ The built in patches are split to 3 parts: minimal, medium, and large. The full
 
 What this all means is that **only late_start service mode is guaranteed to run in a fully patched environment**. If any script is not time critical, it is **highly recommended to run those scripts in late_start service mode**.
 
-Command help message (very helpful):
+Command help message:
 
 ```
 Usage: magiskpolicy [--options...] [policystatements...]
@@ -154,7 +154,7 @@ allow source2 target2 permission-class { all-permissions }
 ```
 
 ### magiskhide
-This is the command-line tool to control the state of MagiskHide.
+This is the CLI to control the state of MagiskHide.
 
 Command help message: 
 

docs/changelog.md

@@ -0,0 +1,3 @@
+# Changelog
+- 2017.8.16
+    - Initial version for Magisk v13.5+

docs/details.md

@@ -10,7 +10,7 @@ If you are working on complicated projects, you shall need more control to the w
     - **This stage is BLOCKING. Boot process will NOT continue until everything is done, or 60 seconds has passed**
     - Happens after `/data` is ready (including the case when `/data` is encrypted)
     - Happens before Zygote and system servers are started (which means pretty much everything)
-    - Mirrors will be mounted. These mirrors play a critical part in **Magic Mount**
+    - Mirrors will be mounted. These mirrors play a critical role in **Magic Mount**
     - `/data/magisk.img` will be merged, trimmed, and mounted to `/magisk`
     - Magisk will run scripts under `/magisk/.core/post-fs-data.d`
     - Magisk will run scripts: `/magisk/$MODID/post-fs-data.sh` (placed in each module directory)
@@ -49,12 +49,12 @@ Directories containing a file named `.replace` will NOT be merged into the syste
 
 ### Notes
 - Sometimes, completely replacing a folder is inevitable. For example you want to replace `/system/priv-app/SystemUI` in your stock rom. In stock roms, system apps usually comes with pre-optimized files. If your replacement `SystemUI.apk` is deodexed (which is most likely the case), you would want to replace the whole `/system/priv-app/SystemUI` to make sure the folder only contains the modified `SystemUI.apk` and **NOT** merge with the pre-optimized files.
-- If you are using the [Magisk Module Template](https://github.com/topjohnwu/magisk-module-template), you can create a list of folders you want to directly replace in `config.sh`, the installation scripts will handle the creation of `.replace` files for you.
+- If you are using the [Magisk Module Template](https://github.com/topjohnwu/magisk-module-template), you can create a list of folders you want to replace in the file `config.sh`. The installation scripts will handle the creation of `.replace` files into the listed folders for you.
-- Adding non-existing target items is a relatively expensive operation. Magisk would need to do **MANY** under-the-hood tasks to achieve it. Replacing a whole folder is recommended if viable, it reduces the complexity of the generation of the mounting tree and could speed up the booting time
+- Adding non-existing target items is a relatively expensive operation. Magisk would need to do **MANY** under-the-hood tasks to achieve it. Replacing a whole folder is recommended if viable, it reduces the complexity of the construction of the mounting tree and could speed up the booting time
 
 ## Simple Mount Details
-Some files require to be mounted much earlier in the boot process, currently known are bootanimation and some libs (most users won't change them). You can simply just place your files into the corresponding path under `/cache/magisk_mount`. At boot time, Magisk will **clone all the attributes of the target file**, including selinux contexts, permission mode, owner/group to the file, and bind mount to the target. You don't need to worry about the metadatas for files placed under `/cache/magisk_mount`.
+Some files require to be mounted much earlier in the boot process, currently known are bootanimation and some libs (most users won't change them). You can simply place your modified files into the corresponding path under `/cache/magisk_mount`. At boot time, Magisk will **clone all the attributes from the target file**, which includes selinux context, permission mode, owner, group. It'll then bind mount the file to the target. This means you don't need to worry about the metadatas for files placed under `/cache/magisk_mount`: copy the file to the correct place, reboot then you're done!
 
-This mode does not feature the same complex Magic Mount implementation, it will only cover the case when a source leaf's target item exists in `/system`.
+This mode does not feature the same complex Magic Mount implementation, it will mount a source leaf to an existing target item under `/system`.
 
 For example, you want to replace `/system/media/bootanimation.zip`, copy your new boot animation zip to `/cache/magisk_mount/system/media/bootanimation.zip,` Magisk will mount your files in the next reboot.

docs/module_repo.md

@@ -31,13 +31,13 @@ magisk
 ## Magisk Module Template
 The **Magisk Module Template** is hosted **[here](https://github.com/topjohnwu/magisk-module-template)**.
 
-It is a template to create a flashable zip to install Magisk Modules. It is created to be simple to use so that anyone can create their own modules easily. The template itself contains minimal scripting for installation; most of the functions are located externally in [util_functions.sh](https://github.com/topjohnwu/Magisk/blob/master/scripts/util_functions.sh), which will be installed along with Magisk, and can be upgraded through a Magisk upgrade instead of a template update.
+It is a template to create a flashable zip to install Magisk Modules. It is created to be simple to use so that anyone can create their own modules easily. The template itself contains minimal scripting for installation; most of the functions are located externally in [util_functions.sh](https://github.com/topjohnwu/Magisk/blob/master/scripts/util_functions.sh), which will be installed along with Magisk, and can be upgraded through a Magisk upgrade without the need of a template update.
 
-The template can cover most modules' needs: you can add files into `system`, which will be cloned into `/system` by Magisk after installing the module. In addition to module files, `system.prop`, `post-fs-data.sh`, `service.sh` are also installable through this template.
+The template should meet most modules' needs. Add files into `system`, which will be cloned into `/system` by Magisk after installing the module, and in addition to module files, `system.prop`, `post-fs-data.sh`, `service.sh` are also installable through this template.
 
 Here are some files you would want to know:
 
-- `config.sh`: A simple script used as a configuration file for the actual installation file to correctly install you module. It is the place you can select which features your module needs/disables.
+- `config.sh`: A simple script used as a configuration file for the actual installation file to correctly install your module. It is the place you can select which features your module needs/disables.
 - `module.prop`: This file contains your module's indentity and properties, including name and versions etc.. This file will be used to identify your module on an actual device and in the [Magisk Modules Repo](https://github.com/Magisk-Modules-Repo)
 - `common/*`: These files will be installed to the module with the correspond role
 - `META-INF/com/google/android/update-binary`: The actual installation script. Modify this file for advanced custom behavior
@@ -45,29 +45,32 @@ Here are some files you would want to know:
 ## Create a Magisk Module With The Template
 1. Clone / download [this repo](https://github.com/topjohnwu/magisk-module-template)
 1. Open `config.sh` and carefully read the fully documented file. Follow the instructions within the script
-1. You should at least modified `config.sh` and `module.prop`
+1. You should at least have `config.sh` and `module.prop` modified
-1. Directly zip your files, and the result zip file is a flashable zip for both Magisk Manager and custom recoveries
+1. Directly zip all files; the result zip file is a flashable zip that can be used in both Magisk Manager and custom recoveries
-1. Please check **Notes** for precautions
+1. Please check [**Notes**](#notes) for several precautions
 
 ## Submit Your Module to Magisk Modules Repo
-If you want to share your module with others, you can submit your modules to [Magisk Modules Repo](https://github.com/Magisk-Modules-Repo). In order to submit a module, you will need to know how to use some basic `git`.
+If you want to share your module with others, you can submit your modules to [Magisk Modules Repo](https://github.com/Magisk-Modules-Repo). You would need some basic `git` knowledge here.
 
-1. Create a module as stated [here](module.md), and test if it works properly
+1. Create a module as stated above, and test if it works properly
 1. Fork [this repo](https://github.com/topjohnwu/magisk-module-template) to your account
 1. Commit and push your changes to your forked repo
 1. Open an issue in [topjohnwu/Magisk_Repo_Central](https://github.com/topjohnwu/Magisk_Repo_Central/issues/new) with your repo link
-1. I will review your module, and once accepted, your repo should be cloned into [Magisk-Modules-Repo](https://github.com/Magisk-Modules-Repo), and you should receive an email to become the collaborator so you can edit the repo in the future.
+1. I will review your module, and once accepted, your repo should be cloned into [Magisk-Modules-Repo](https://github.com/Magisk-Modules-Repo)
+1. You should receive an email to become the collaborator so you can edit the repo in the future.
 
 #### Once your module is live on the Modules Repo, the description of your repo should be the ID of your module. Please do NOT change the description, repeat, do NOT change the description.
 
-## Notes
+![repo_description.png](repo_description.png)
-- The Module Template depends on external scripts installed by Magisk, so it each version of template will has its own minimal Magisk version requirement.
-- **Windows users please aware!!** The line endings on all text files should be the **Unix format**. Please use advanced text editors like Sublime, Atom, Notepad++ etc., **NEVER** use Windows Notepad.
-- In `module.prop`, `version` can be an arbitrary string, so any fancy version name (e.g. ultra-beta-v1.1.1.1) is allowed. However, `versionCode` **MUST** be an integer. The value is used for version comparison.
-- Make sure your module ID **doesn't contain any spaces**.
 
-## For Repo Developers
+## Notes
+- The Module Template depends on external scripts, be aware of the minimal required Magisk version of the template.
+- **Windows users please check here!!** The line endings of all text files should be in the **Unix format**. Please use advanced text editors like Sublime, Atom, Notepad++ etc. to edit **ALL** text files, **NEVER** use Windows Notepad.
+- In `module.prop`, `version` can be an arbitrary string, so any fancy version name (e.g. ultra-beta-v1.1.1.1) is allowed. However, `versionCode` **MUST** be an integer. The value is used for version comparison.
+- Make sure your module ID **does not contain any spaces**.
+
+## Notes For Repo Developers
 
 - Magisk Manager monitors all repo's `master` branch. Any changes to the branch `master` will be reflected to all users immediately. If you are working on an update for a module, please work on another branch, make sure it works, then finally merge the changes back to `master`.
-- Once you finished upgrading your repo, bump up at least the `versionCode` in `module.prop`, so Magisk Manager will know you module is updated!
+- Once you finished upgrading your repo, increase at least the `versionCode` in `module.prop`. Magisk Manager uses this value to compare with the local installed module to determine whether an update is availible.
 - The description of your repo should be the same as your module ID. If you changed your description, Magisk Manager will fail to identify your repo, and cannot relate installed module to the online repo together.