Documentation Improvements

- Fix Spelling
- codesnippets: Improve introduction texts; Write subsection about
  metadata JSON files

docs/basic-usage.rst

@@ -68,7 +68,7 @@ Instaloader supports the following targets:
    **download the user's stories**.
 
 - ``"#hashtag"``
-   Posts with a certain **hashtag** (the quotes are usually neccessary),
+   Posts with a certain **hashtag** (the quotes are usually necessary),
 
 - ``:stories``
    The currently-visible **stories** of your followees (requires
@@ -158,7 +158,7 @@ Filter Posts
 .. py:currentmodule:: instaloader
 
 The options :option:`--post-filter` and :option:`--storyitem-filter`
-allows to specify criterias that posts or story items have to
+allows to specify criteria that posts or story items have to
 meet to be downloaded. If not given, all posts are downloaded.
 
 The filter string must be a

docs/codesnippets.rst

@@ -11,8 +11,8 @@ Advanced Instaloader Examples
    :backlinks: none
 
 Here we present code examples that use the :ref:`python-module-instaloader` for
-more advanced tasks than what is possible with the Instaloader command line
+more advanced Instagram downloading or metadata mining than what is possible
-interface.
+with the Instaloader command line interface.
 
 .. For each code snippet:
    - title
@@ -21,12 +21,12 @@ interface.
    - link to discussion issue
    - link used methods
 
-Download Posts in a specific period
+Download Posts in a Specific Period
 -----------------------------------
 
-To collect pictures (and metadata) only from a specific period, you can play
+To only download Instagram pictures (and metadata) that are within a specific
-around with :func:`~itertools.dropwhile` and :func:`~itertools.takewhile` from
+period, you can play around with :func:`~itertools.dropwhile` and
-:mod:`itertools` like in this snippet.
+:func:`~itertools.takewhile` from :mod:`itertools` like in this snippet.
 
 .. literalinclude:: codesnippets/121_since_until.py
 
@@ -37,8 +37,8 @@ Discussed in :issue:`121`.
 Likes of a Profile / Ghost Followers
 ------------------------------------
 
-To store inactive followers, i.e. followers that did not like any of your
+To obtain a list of your inactive followers, i.e. followers that did not like
-pictures, into a file you can use this approach.
+any of your pictures, into a file you can use this approach.
 
 .. literalinclude:: codesnippets/120_ghost_followers.py
 
@@ -51,10 +51,10 @@ Discussed in :issue:`120`.
 Track Deleted Posts
 -------------------
 
-This script uses Instaloader to obtain a list of currently-online posts, and
+This script uses Instaloader to obtain a list of currently-online Instagram and
-generates the matching filename of each post. It outputs a list of posts which
+compares it with the set of posts that you already have downloaded.  It outputs
-are online but not offline (i.e. not yet downloaded) and a list of posts which
+a list of posts which are online but not offline (i.e. not yet downloaded) and a
-are offline but not online (i.e. deleted in the profile).
+list of posts which are offline but not online (i.e. deleted in the profile).
 
 .. literalinclude:: codesnippets/56_track_deleted.py
 
@@ -68,9 +68,9 @@ Only one Post per User
 
 To download only the one most recent post from each user, this snippet creates a
 :class:`set` that contains the users of which a post has already been
-downloaded. When iterating the posts, check whether the post's owner already is
+downloaded. While iterating the posts, it checks whether the post's owner
-in the set. If so, skip the post. Otherwise, download it and add the user to
+already is in the set. If not, the post is downloaded from Instagram and the
-that set.
+user is added to that set.
 
 .. literalinclude:: codesnippets/113_only_one_per_user.py
 
@@ -79,23 +79,23 @@ See also :class:`Post`, :meth:`Instaloader.download_post`,
 
 Discussed in :issue:`113`.
 
-Upgrade Images by local Copies
+Upgrade Images by Local Copies
 ------------------------------
 
 The following script finds local versions of images fetched by Instaloader, in
-order to ugprade the downloaded images by locally-found versions with better
+order to upgrade the downloaded images by locally-found versions with better
 quality. It uses image hashing to identify similar images.
 
 `updgrade-instaloader-images.py <https://gist.github.com/pavelkryukov/15f93d19a99428a284a8bcec27e0187b>`__ (external link to GitHub Gist)
 
 Discussed in :issue:`46`.
 
-Render Captions to downloaded Images
+Add Captions to Images
-------------------------------------
+----------------------
 
 Instaloader does not modify the downloaded JPEG file. However, one could combine
-it with an imaging library such as Pillow or PIL to render the
+it with an imaging library such as Pillow or PIL to render the caption on
-:attr:`Post.caption` on pictures.  The following shows an approach.
+Instagram pictures.  The following shows an approach.
 
 .. literalinclude:: codesnippets/110_pil_captions.py
 
@@ -103,3 +103,26 @@ See also :attr:`Post.caption`, :attr:`Post.url`, :meth:`Post.from_shortcode`,
 :func:`load_structure_from_file`.
 
 Discussed in :issue:`110`.
+
+Metadata JSON Files
+-------------------
+
+The JSON files Instaloader saves along with each Post contain all the metadata
+that has been retrieved from Instagram while downloading the picture and
+associated required information.
+
+With `jq <https://stedolan.github.io/jq/>`__, a command-line JSON processor, the
+metadata can be easily post-processed. For example, Instaloader's JSON files can
+be pretty-formatted with:
+
+.. code-block:: none
+
+   xzcat 2018-05-13_11-18-45_UTC.json.xz | jq .node
+
+However, Instaloader tries to do as few metadata requests as possible, so,
+depending on how Instaloader has been invoked, it may occur that these files do
+not contain the complete available metadata structure. Nevertheless, the file
+can be loaded into Instaloader with :func:`load_structure_from_file` and the
+required metadata then be accessed via the :class:`Post` or :class:`Profile`
+attributes, which trigger an Instagram request if that particular information is
+not present in the JSON file.

docs/contributing.rst

@@ -28,7 +28,7 @@ following in mind:
   opening a new issue. However, if unsure, please create a new issue.
 
 - State **how the bug can be reproduced**, i.e. how Instaloader was invoked
-  when the problem occured (of course, you may anonymize profile names etc.).
+  when the problem occurred (of course, you may anonymize profile names etc.).
 
 - Include all **error messages and tracebacks** in the report.
 
@@ -54,7 +54,7 @@ few things to consider:
   warning rather than adapting the code to Pylint's desires.
 
 - The documentation source is located in the ``docs`` folder. The file
-  ``cli-options.rst`` is merely an RST-formatted copy of ``ìnstaloader --help``
+  ``cli-options.rst`` is merely an RST-formatted copy of ``instaloader --help``
   output, of which the source is in ``instaloader/__main__.py``.
 
 - Feel free to contact us, even if you "only" have Proof-of-Concepts or