ipfs: Changelog and proofreading in the docs

Author: sampsyo

docs/changelog.rst

@@ -6,6 +6,8 @@ Changelog
 
 New features:
 
+* A new :doc:`/plugins/ipfs` lets you share music via a new, global,
+  decentralized filesystem. :bug:`1397`
 * :doc:`/plugins/duplicates`: You can now merge duplicate
   track metadata (when detecting duplicate items), or duplicate album
   tracks (when detecting duplicate albums).
@@ -91,6 +93,7 @@ Fixes:
   files. :bug:`1480`
 
 .. _Python bug: http://bugs.python.org/issue16512
+.. _ipfs: http://ipfs.io
 
 
 1.3.13 (April 24, 2015)

docs/plugins/ipfs.rst

@@ -2,57 +2,71 @@ IPFS Plugin
 ===========
 
 The ``ipfs`` plugin makes it easy to share your library and music with friends.
-The plugin uses `ipfs`_ for storing the libraries and the file content.
+The plugin uses `ipfs`_ for storing the library and file content.
 
 .. _ipfs: http://ipfs.io/
 
 Installation
 ------------
 
-This plugin requires `go-ipfs`_ running as a daemon and that the ipfs command is
-in the users $PATH.
+This plugin requires `go-ipfs`_ to be running as a daemon and that the
+associated ``ipfs`` command is on the user's ``$PATH``.
 
 .. _go-ipfs: https://github.com/ipfs/go-ipfs
 
-Enable the ``ipfs`` plugin in your configuration (see :ref:`using-plugins`).
+Once you have the client installed, enable the ``ipfs`` plugin in your
+configuration (see :ref:`using-plugins`).
 
 Usage
 -----
 
-To add albums to ipfs, making them shareable, use the -a or --add flag. If used
-without arguments it will add all albums in the local library.  When added all
-items and albums will get a ipfs entry in the database containing the hash of
-that specific file/folder. Newly imported albums will be added automatically to
-ipfs unless set not to do so, see the configuration section below.
+This plugin can store and retrieve music individually, or it can share entire
+library databases.
 
-These hashes can then be given to a friend and they can ``get`` that album from
-ipfs and import it to beets using the -g or --get flag.
-If the argument passed to the -g flag isn't an ipfs hash it'll be used as a
-query instead, getting all albums matching the query.
+Adding
+''''''
 
-Using the -p or --publish flag a copy of the local library will be
+To add albums to ipfs, making them shareable, use the ``-a`` or ``--add``
+flag. If used without arguments it will add all albums in the local library.
+When added, all items and albums will get an "ipfs" field in the database
+containing the hash of that specific file/folder. Newly imported albums will
+be added automatically to ipfs by default (see below).
+
+Retrieving
+''''''''''
+
+You can give the ipfs hash for some music to a friend. They can get that album
+from ipfs, and import it into beets, using the ``-g`` or ``--get`` flag. If
+the argument passed to the ``-g`` flag isn't an ipfs hash, it will be used as
+a query instead, getting all albums matching the query.
+
+Sharing Libraries
+'''''''''''''''''
+
+Using the ``-p`` or ``--publish`` flag, a copy of the local library will be
 published to ipfs. Only albums/items with ipfs records in the database will
 published, and local paths will be stripped from the library. A hash of the
 library will be returned to the user.
 
-A friend can then import this remote library by using the -i or --import flag.
-To tag an imported library with a specific name by passing a name as the second
-argument to -i, after the hash.
-The content of all remote libraries will be combined into an additional library
-as long as the content doesn't already exist in the joined library.
+A friend can then import this remote library by using the ``-i`` or
+``--import`` flag. To tag an imported library with a specific name by passing
+a name as the second argument to ``-i,`` after the hash. The content of all
+remote libraries will be combined into an additional library as long as the
+content doesn't already exist in the joined library.
 
-When remote libraries has been imported you can search them by using the -l or
---list flag. The hash of albums matching the query will be returned, this can
-then be used with -g to fetch and import the album to the local library.
+When remote libraries has been imported you can search them by using the
+``-l`` or ``--list`` flag. The hash of albums matching the query will be
+returned, and this can then be used with ``-g`` to fetch and import the album
+to the local library.
 
 Ipfs can be mounted as a FUSE file system. This means that music in a remote
 library can be streamed directly, without importing them to the local library
-first. If the /ipfs folder is mounted then matching queries will be sent to the
-:doc:`/plugins/play` using the -m or --play flag.
+first. If the ``/ipfs`` folder is mounted then matching queries will be sent
+to the :doc:`/plugins/play` using the ``-m`` or ``--play`` flag.
 
 Configuration
 -------------
 
-The ipfs plugin will automatically add imported albums to ipfs and add those hashes
-to the database. This can be turned off by setting the ``auto`` option in the
-ipfs section of the config to ``no``.
+The ipfs plugin will automatically add imported albums to ipfs and add those
+hashes to the database. This can be turned off by setting the ``auto`` option
+in the ``ipfs:`` section of the config to ``no``.