Improve documentation

README.md

@@ -2,17 +2,32 @@
 
 This is a collection of utilities dealing with Tumblr blogs.
 
-- `tumble.py` creates new posts from RSS or Atom feeds
+#### IMPORTANT!  Before creating an issue, please read the documentation!
+ 
+#### There are 3 utilities:
+
 - `tumblr_backup.py` makes a local backup of posts and images
+    - Documentation is [here](tumblr_backup.md)
+    - A step-by-step guide for beginners is [here](tumblr_backup_for_beginners.md)
+- `tumble.py` creates new posts from RSS or Atom feeds
 - `mail_export.py` mails tagged links to a recipient list
 
-These scripts are or have been useful to me over the years.
+Documentation for `tumble.py` and `mail_export.py` can be found in each script's docstring.
 
-More documentation can be found in each script's docstring or in
-[tumblr_backup.md](https://github.com/bbolli/tumblr-utils/blob/master/tumblr_backup.md).
+Python 2.7 is required for these scripts.  Do not use Python 3!
 
-The utilities run under Python 2.7.
+ 
+#### Features of tumblr_backup:
+- Backs up images, both inline and photo posts
+- Backs up videos (including YouTube and others with youtube-dl)
+- Backs up audio (including SoundCloud)
+- Backs up reblogs by default
+- Supports downloading a blog's likes (experimental)
+- Posts are backed up as minimally styled HTML5
+- Indexing by month and by tag
 
+***
+ 
 ### Notice
 
 On 2015-06-04, I made the v2 API the default on the master branch. The former
@@ -23,4 +38,4 @@ a password in Tumblr's v2 API.
 
 ### License
 
-[GPL3](http://www.gnu.org/licenses/gpl-3.0.txt).
+[GPL3](http://www.gnu.org/licenses/gpl-3.0.txt)

tumblr_backup.md

@@ -1,4 +1,4 @@
-## 0. Description
+## 1. Description
 
 `tumblr_backup.py` is a script that backs up your [Tumblr](http://tumblr.com)
 blog locally.
@@ -12,8 +12,12 @@ By default, all posts of a blog are backed up in minimally styled HTML5.
 
 You can see an example of its output [on my home page](http://drbeat.li/tumblr).
 
+### Important Notes:
+- Dashboard-only (hidden) blogs are not currently supported
+- On OS X, you may get SSL errors.  `-S` can be used to ignore them.
 
-## 1. Installation
+
+## 2. Installation
 
 1. Download and unzip
    [tumblr-utils.zip](https://github.com/bbolli/tumblr-utils/zipball/master)
@@ -26,15 +30,15 @@ You can see an example of its output [on my home page](http://drbeat.li/tumblr).
 
 There are two optional dependencies that enable additional features:
 
-1. To backup audio and video, install [youtube-dl](https://rg3.github.io/youtube-dl/).
+1. To backup audio and video, install the [youtube-dl](https://rg3.github.io/youtube-dl/) _python module_.
+    - You should install it with pip: `pip install --upgrade youtube_dl`.
+        - If Python 3 is the default (such as on Arch Linux), use `pip2` instead
+        - If you get permission errors on Linux or OS X, run it with `sudo` or add `--user`.
+    - You can also install it using a package manager, but make sure that you install the Python 2 module.
 2. To enable EXIF tagging, install [pyexiv2](http://tilloy.net/dev/pyexiv2/).
+    - Available via pip or your package manager
 
-The fastest option to install these packages is via the package manager of
-your operating system (apt-get, synaptic, yum, brew, etc). If this is not
-feasible, download and install from the links above.
-
-
-## 2. Usage
+## 3. Usage
 
 ### Synopsis
 
@@ -116,7 +120,7 @@ been backed up, 2 on invocation errors, 3 if the backup was interrupted, or 4
 on HTTP errors.
 
 
-## 3. Operation
+## 4. Operation
 
 By default, `tumblr_backup` backs up all posts in HTML format.
 
@@ -276,15 +280,7 @@ posts matching all criteria will be backed up.
 All options use only public Tumblr APIs, so you can use the program to backup
 blogs that you don’t own.
 
-`tumblr_backup` is developed and tested on Linux and OS X. If you want to run
-it under Windows, I suggest to try the excellent [Cygwin](http://cygwin.com)
-environment.
-
-
-## 4. Changelog
-
-See [here](https://github.com/bbolli/tumblr-utils/commits/master/tumblr_backup.py).
-There are no formal releases so check back often!
+`tumblr_backup` is developed and tested on Linux and OS X.
 
 
 ## 5. Acknowledgments