Improve documentation

README.md

@@ -2,17 +2,31 @@
 
 This is a collection of utilities dealing with Tumblr blogs.
 
-- `tumble.py` creates new posts from RSS or Atom feeds
+#### 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

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,18 +30,19 @@ 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/).
-   If you need HTTP cookies to download, use an appropriate browser plugin to
-   extract the cookie(s) into a file and use option `--cookiefile=file`. See
-   [issue 132](https://github.com/bbolli/tumblr-utils/issues/132).
+1. [youtube-dl](https://rg3.github.io/youtube-dl/) is used to backup external video.
+    - Install the Python 2 _module_, not the main youtube-dl program.
+    - If you need HTTP cookies to download, use an appropriate browser plugin to
+      extract the cookie(s) into a file and use option `--cookiefile=file`. See
+      [issue 132](https://github.com/bbolli/tumblr-utils/issues/132).
 2. To enable EXIF tagging, install [pyexiv2](https://github.com/escaped/pyexiv2).
 
 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, build and install from the links above.
 
 
-## 2. Usage
+## 3. Usage
 
 ### Synopsis
 
@@ -120,7 +125,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.
 
@@ -280,15 +285,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