Adding some basic documentation

Author: IzzySoft

doc/hints.md

@@ -0,0 +1,94 @@
+# Miscellaneous hints for Adebar usage
+
+## General
+*Adebar* only creates the scripts, it doesn't backup stuff itself. There are two
+exceptions to this rule currently:
+
+* it pulls the `packages.xml` (as it requires this to obtain additional details)
+* it pulls the `wpa_supplicant.conf` directly.
+
+Both actions are relative fast. But once you run the scripts to create the real
+backups, things are different: especially pulling the "Shared Storage" (see
+below) might take quite a while, as your SD cards might hold gigabytes of data.
+At the same time, it puts quite a strain on your battery, as it needs to transfer
+all those data. So make sure to have a power source connected to your device
+during the backup process (you probably will have that, as ADB is mostly used
+via USB – but you could also use "ADB wireless", and the *TiBu* stuff is using
+WiFi as well – so I'd thought to better point this out).
+
+### When running the real backup
+* as pointed out above: have a power source connected
+* with the "ADB Backups": always wait for the "complete" toast before confirming
+  the next backup (or ADB might choke, backup won't continue)
+* if ADB "chokes" (and the backup stalls): Check your backup directory for how
+  far the process already went, adjust the script accordingly to start there,
+  disconnect and reconnect your device, and re-start the modified script.
+
+
+## Installation
+Simply unpack into an empty directory, and run the script from there. No special
+installation-steps required.
+
+
+## Configuration
+When running, *Adebar* checks for a file called `config` in the directory where
+it resides itself. A sample configuration file is included as `config.sample`,
+which you simply can copy and adjust. Your `config` file has only to contain the
+settings you wish to change; this will usually be the DEVICE_IP (which is not
+set by default).
+
+What the settings are standing for is:
+
+* `USERDIR="userApps"`: sub-directory where the backup scripts will place the
+  ADB backups of your user-apps into
+* `SYSDIR="sysApps"`: Similar, for the data backups of your system apps
+* `DEVICE_IP="192.168.101.111"`: IP address of your device (for *TiBu*)
+* `TIBU_PORT="8080"`: port the *TiBu* web server listens on
+* `TIBU_SDINT="/storage/INTERNAL/Storage-ALL.zip"`: URL path of the internal SD
+* `TIBU_SDEXT="/storage/SAMSUNG_EXT_SD_CARD/Storage-ALL.zip":` URL path of the external SD
+* `TIBU_BACKUPS="/TitaniumBackup-ALL.zip"`: URL path to the *TiBu* backups
+
+
+## Shared Storage
+This term refers to your SD card(s). *Adebar* offers two ways to retrieve data
+from those:
+
+* `com.android.sharedstoragebackup.ab` (for abbreviation issues, I'll refer to
+  this as *SSB* from now on)
+* [Titanium Backup](http://play.google.com/store/apps/details?id=com.keramidas.TitaniumBackup)
+  (abbreviated as *TiBu* here)
+
+Scripts generated by *Adebar* cover both, so it's up to you which to use.
+
+### SSB
+As you might have already guessed from the above, *SSB* is offered via ADB
+without the need of additional apps. It is simply triggered when backing up
+data from its package. These data include everything from your device's
+SD cards – both internal (`/0`) and external (`/1`). Timestamps of files
+and directories are kept, but most files seem to come as "0775" (i.e. the
+execute flag is set for user and group) – a condition you might have seen
+when accessing FAT formatted drives in general.
+
+While I'd prefer this backup to the one *TiBu* creates, specifically for
+the timestamps, on some devices it has a little draw-back: My *LG Optimus 4X HD*
+e.g. mounts the external SD card *inside* the internal one (`/sdcard/external_sd`),
+which results in its contents backed up twice: once as part of the internal SD
+(in the `/0` subdirectory), and another time as external SD in the `/1`
+subdirectory. This not only makes the resulting backup file unnecessary huge,
+but also takes much longer to backup.
+
+### TiBu
+*TiBu* offers an internal web server, which you can start manually via its options
+menu. If running, you can pull 3 kinds of backups via HTTP:
+
+* contents of the internal SD card (http://<DEVICE_IP>:8080/storage/INTERNAL/Storage-ALL.zip)
+* contents of the external SD card (http://<DEVICE_IP>:8080/storage/SAMSUNG_EXT_SD_CARD/Storage-ALL.zip)
+* all your *TiBu* created backups (http://<DEVICE_IP>:8080/TitaniumBackup-ALL.zip).
+
+In case of my above mentioned *LG Optimus 4X HD* I just had to pull the contents
+of the internal card, and had them all: As noted, the external card is mounted
+inside – and of course the backups reside on one of the two.
+
+Disadvantage here is that *TiBu* touches the timestamps of all files, so the
+original timestamps are lost: All files appear as if they would have been created
+at the time the backup was made.

doc/known_issues.md

@@ -0,0 +1,27 @@
+# Known Issues
+
+## Some apps simply don't want to be backed up via ADB
+At least on my P880 I've encountered several apps which seem to simply refuse
+being backed up via ADB. In those cases, backups result in a 41 byte file (which
+is just the backup file header). So watch out for those, and see to have them
+backed up by other means; as *Adebar* here is no more than a "front-end" to the
+`adb backup` command, I don't see what it could fix here.
+
+Apps which I found having this issue include the following:
+
+* installed as system apps:
+  - GMail
+  - SuperSU
+* installed as user apps:
+  - AppMonster Pro
+  - DavDroid
+  - JuiceSSH
+  - MobilityMap
+  - WakeLockDetector
+
+
+## Backup of each app has to be confirmed separately
+Yes. That's a security measure so no stranger could simply connect an USB cable
+to your device and steal your data. I didn't yet check whether it's possible to
+at least temporarily disable that. If I do and find a way, you will find it with
+the other hints :)