From 878f3ab22d854d39f7677b42e47278cde26de69e Mon Sep 17 00:00:00 2001 From: Cebtenzzre Date: Fri, 14 Dec 2018 18:33:05 -0500 Subject: [PATCH] Improve documentation --- README.md | 24 +++++++++++++++++++----- tumblr_backup.md | 31 ++++++++++++++----------------- 2 files changed, 33 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 4d4fe95..9be5385 100644 --- a/README.md +++ b/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 diff --git a/tumblr_backup.md b/tumblr_backup.md index f1bab29..d5e3fb2 100644 --- a/tumblr_backup.md +++ b/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,10 +30,11 @@ 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 @@ -37,7 +42,7 @@ 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