From 6117e223a7d5b8fc9fd33c9cea9e4a61135d1443 Mon Sep 17 00:00:00 2001
From: Alexander Graf <mail@agraf.me>
Date: Sun, 29 Apr 2018 16:24:55 +0200
Subject: [PATCH] Describe Metadata Text Files Feature

---
 docs/basic-usage.rst | 33 +++++++++++++++++++++++++++++++++
 docs/cli-options.rst |  5 +++--
 2 files changed, 36 insertions(+), 2 deletions(-)

diff --git a/docs/basic-usage.rst b/docs/basic-usage.rst
index f8799a9..4777b7c 100644
--- a/docs/basic-usage.rst
+++ b/docs/basic-usage.rst
@@ -199,3 +199,36 @@ defined:
 
 - :attr:`~StoryItem.expiring_utc` (datetime) / :attr:`~StoryItem.expiring_local` (datetime)
    Timestamp when StoryItem will get unavailable.
+
+.. _metadata-text-files:
+
+Metadata Text Files
+^^^^^^^^^^^^^^^^^^^
+
+Unless :option:`--no-captions` is given, Instaloader creates a ``.txt`` file
+along with each post where the Post's caption is saved.
+
+You can customize what metadata to save for each Post or StoryItem with
+:option:`--post-metadata-txt` and :option:`--storyitem-metadata-txt`. The
+default is ``--post-metadata-txt={caption}`` and no storyitem metadata txt.
+These strings are formatted similar as in the :ref:`filename-specification` and
+the result is saved in text files, unless it is empty.
+
+Specifying these options multiple times results in output having multiple lines,
+in the order they were given to Instaloader.
+
+The field names are evaluated to :class:`Post` or :class:`StoryItem` attributes,
+and as such, the same fields are supported as in :ref:`filename-specification`
+and :ref:`filter-posts`.
+
+For example, to save the current number of likes for each post, rather than
+the post's caption::
+
+   instaloader --post-metadata-txt="{likes} likes." <target>
+
+Note that with this feature, it is possible to easily and fastly extract
+additional metadata of already-downloaded posts, by reimporting their JSON
+files. Say, you now also want to export the number of comments the Posts had
+when they were downloaded::
+
+   instaloader --post-metadata-txt="{likes} likes, {comments} comments." <target>/*.json.xz
diff --git a/docs/cli-options.rst b/docs/cli-options.rst
index 12bdafa..a4fbcc3 100644
--- a/docs/cli-options.rst
+++ b/docs/cli-options.rst
@@ -58,11 +58,12 @@ automatically **finds it by its unique ID** and renames the folder likewise.
 
 .. option:: --post-metadata-txt
 
-   Template to write in txt file for each Post.
+   Template to write in txt file for each Post. See :ref:`metadata-text-files`.
 
 .. option:: --storyitem-metadata-txt
 
-   Template to write in txt file for each StoryItem.
+   Template to write in txt file for each StoryItem. See
+   :ref:`metadata-text-files`.
 
 .. option:: --stories