reorder --help output

README.rst

@@ -21,7 +21,7 @@
 
 ::
 
-    instaloader [--comments] [--geotags] [--stories]
+    instaloader [--comments] [--geotags] [--stories] [--tagged]
                 [--login YOUR-USERNAME] [--fast-update]
                 profile | "#hashtag" | :stories | :feed | :saved
 

docs/basic-usage.rst

@@ -60,12 +60,20 @@ already have a valid session cookie file.
 What to Download
 ^^^^^^^^^^^^^^^^
 
+.. targets-start
+
 Instaloader supports the following targets:
 
 - ``profile``
-   Public profile, or private profile with :option:`--login`. For each profile
+   Public profile, or private profile with :option:`--login`.
-   you download, :option:`--stories` instructs Instaloader to also
+
-   **download the user's stories**.
+   If an already-downloaded profile has been renamed, Instaloader automatically
+   finds it by its unique ID and renames the folder accordingly.
+
+   Besides the profile's posts, its current profile picture is downloaded. For
+   each profile you download, :option:`--stories` instructs Instaloader to also
+   **download the user's stories**, and :option:`--tagged` to **download posts
+   where the user is tagged**.
 
 - ``"#hashtag"``
    Posts with a certain **hashtag** (the quotes are usually necessary),
@@ -88,6 +96,8 @@ Instaloader supports the following targets:
    The single **post** with the given shortcode. Must be preceeded by ``--`` in
    the argument list to not be mistaken as an option flag.
 
+.. targets-end
+
 Instaloader goes through all media matching the specified targets and
 downloads the pictures and videos and their captions. You can specify
 

docs/cli-options.rst

@@ -13,27 +13,33 @@ feed), ``:stories`` (stories of your followees) or ``:saved`` (collection of
 posts marked as saved).
 
 Here we explain the additional options that can be given to Instaloader to
-customize its behavior.  To get a list of all flags, their abbreviations and
+customize its behavior.  For an
-their descriptions, you may also run ``instaloader --help``.  For an
 introduction on how to use Instaloader, see
 :ref:`download-pictures-from-instagram`.
 
-What to Download
+To get a list of all flags, their abbreviations and
-^^^^^^^^^^^^^^^^
+their descriptions, you may also run::
 
-Specify a list of targets (profiles, #hashtags, ``:feed``, ``:stories`` or
+   instaloader --help
-``:saved``). For each of these, Instaloader creates a folder and stores all
-posts along with the pictures's captions and the current **profile picture**
-there. If an already-downloaded profile has been renamed, Instaloader
-automatically **finds it by its unique ID** and renames the folder likewise.
 
-.. option:: --profile-pic-only, -P
+Targets
+^^^^^^^
 
-   Only download profile picture.
+Specify a list of targets. For each of these, Instaloader creates a folder and
+stores all posts along with the pictures's captions there.
 
-.. option:: --no-profile-pic
+.. include:: basic-usage.rst
+   :start-after: targets-start
+   :end-before: targets-end
 
-   Do not download profile picture.
+- ``filename.json[.xz]``
+   Re-Download the given object
+
+- ``+args.txt``
+   Read targets (and options) from given textfile. See :option:`+args.txt`.
+
+What to Download of each Post
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. option:: --no-pictures
 
@@ -75,6 +81,26 @@ automatically **finds it by its unique ID** and renames the folder likewise.
    Template to write in txt file for each StoryItem. See
    :ref:`metadata-text-files`.
 
+.. option:: --no-metadata-json
+
+   Do not create a JSON file containing the metadata of each post.
+
+.. option:: --no-compress-json
+
+   Do not xz compress JSON files, rather create pretty formatted JSONs.
+
+
+What to Download of each Profile
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. option:: --profile-pic-only, -P
+
+   Only download profile picture.
+
+.. option:: --no-profile-pic
+
+   Do not download profile picture.
+
 .. option:: --stories, -s
 
    Also **download stories** of each profile that is downloaded. Requires
@@ -84,14 +110,6 @@ automatically **finds it by its unique ID** and renames the folder likewise.
 
    Also download posts where each profile is tagged.
 
-.. option:: --no-metadata-json
-
-   Do not create a JSON file containing the metadata of each post.
-
-.. option:: --no-compress-json
-
-   Do not xz compress JSON files, rather create pretty formatted JSONs.
-
 .. option:: --stories-only
 
    Rather than downloading regular posts of each specified profile, only
@@ -107,6 +125,15 @@ automatically **finds it by its unique ID** and renames the folder likewise.
 
    Download only post where each profile is tagged, not their regular posts.
 
+Which Posts to Download
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. option:: --fast-update, -F
+
+   For each target, stop when encountering the first already-downloaded picture.
+   This flag is recommended when you use Instaloader to update your personal
+   Instagram archive.
+
 .. option:: --post-filter filter, --only-if filter
 
    Expression that, if given, must evaluate to True for each post to be
@@ -122,20 +149,6 @@ automatically **finds it by its unique ID** and renames the folder likewise.
    evaluated to :class:`instaloader.StoryItem` attributes.
    See :ref:`filter-posts` for more examples.
 
-
-
-When to Stop Downloading
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-If none of these options are given, Instaloader goes through all pictures
-matching the specified targets.
-
-.. option:: --fast-update, -F
-
-   For each target, stop when encountering the first already-downloaded picture.
-   This flag is recommended when you use Instaloader to update your personal
-   Instagram archive.
-
 .. option:: --count COUNT, -c
 
    Do not attempt to download more than COUNT posts.  Applies only to

docs/index.rst

@@ -41,7 +41,7 @@ See :ref:`install` for more options on how to install Instaloader.
 
 ::
 
-    instaloader [--comments] [--geotags] [--stories]
+    instaloader [--comments] [--geotags] [--stories] [--tagged]
                 [--login YOUR-USERNAME] [--fast-update]
                 profile | "#hashtag" |
                 :stories | :feed | :saved

instaloader/__main__.py

@@ -18,7 +18,7 @@ def usage_string():
     argv0 = os.path.basename(sys.argv[0])
     argv0 = "instaloader" if argv0 == "__main__.py" else argv0
     return """
-{0} [--comments] [--geotags] [--stories]
+{0} [--comments] [--geotags] [--stories] [--tagged]
 {2:{1}} [--login YOUR-USERNAME] [--fast-update]
 {2:{1}} profile | "#hashtag" | :stories | :feed | :saved
 {0} --help""".format(argv0, len(argv0), '')
@@ -212,77 +212,91 @@ def main():
                                    "https://instaloader.github.io/.",
                             fromfile_prefix_chars='+')
 
-    g_what = parser.add_argument_group('What to Download',
+    g_targets = parser.add_argument_group("What to Download",
-                                       'Specify a list of profiles or #hashtags. For each of these, Instaloader '
+                                          "Specify a list of targets. For each of these, Instaloader creates a folder "
-                                       'creates a folder and '
+                                          "and downloads all posts. The following targets are supported:")
-                                       'downloads all posts along with the pictures\'s '
+    g_targets.add_argument('profile', nargs='*',
-                                       'captions and the current profile picture. '
+                           help="Download profile. If an already-downloaded profile has been renamed, Instaloader "
-                                       'If an already-downloaded profile has been renamed, Instaloader automatically '
+                                "automatically finds it by its unique ID and renames the folder likewise.")
-                                       'finds it by its unique ID and renames the folder likewise.')
+    g_targets.add_argument('_at_profile', nargs='*', metavar="@profile",
-    g_what.add_argument('profile', nargs='*', metavar='profile|#hashtag',
+                           help="Download all followees of profile. Requires --login. "
-                        help='Name of profile or #hashtag to download. '
+                                "Consider using :feed rather than @yourself.")
-                             'Alternatively, if --login is given: @<profile> to download all followees of '
+    g_targets.add_argument('_hashtag', nargs='*', metavar='"#hashtag"', help="Download #hashtag.")
-                             '<profile>; the special targets '
+    g_targets.add_argument('_feed', nargs='*', metavar=":feed",
-                             ':feed to download pictures from your feed; '
+                           help="Download pictures from your feed. Requires --login.")
-                             ':stories to download the stories of your followees; or '
+    g_targets.add_argument('_stories', nargs='*', metavar=":stories",
-                             ':saved to download the posts marked as saved.')
+                           help="Download the stories of your followees. Requires --login.")
-    g_what.add_argument('-P', '--profile-pic-only', action='store_true',
+    g_targets.add_argument('_saved', nargs='*', metavar=":saved",
+                           help="Download the posts that you marked as saved. Requires --login.")
+    g_targets.add_argument('_singlepost', nargs='*', metavar="-- -shortcode",
+                           help="Download the post with the given shortcode")
+    g_targets.add_argument('_json', nargs='*', metavar="filename.json[.xz]",
+                           help="Re-Download the given object.")
+    g_targets.add_argument('_fromfile', nargs='*', metavar="+args.txt",
+                           help="Read targets (and options) from given textfile.")
+
+    g_post = parser.add_argument_group("What to Download of each Post")
+
+    g_prof = parser.add_argument_group("What to Download of each Profile")
+
+    g_prof.add_argument('-P', '--profile-pic-only', action='store_true',
                         help='Only download profile picture.')
-    g_what.add_argument('--no-profile-pic', action='store_true',
+    g_prof.add_argument('--no-profile-pic', action='store_true',
                         help='Do not download profile picture.')
-    g_what.add_argument('--no-pictures', action='store_true',
+    g_post.add_argument('--no-pictures', action='store_true',
                         help='Do not download post pictures. Cannot be used together with --fast-update. '
                              'Implies --no-video-thumbnails, does not imply --no-videos.')
-    g_what.add_argument('-V', '--no-videos', action='store_true',
+    g_post.add_argument('-V', '--no-videos', action='store_true',
                         help='Do not download videos.')
-    g_what.add_argument('--no-video-thumbnails', action='store_true',
+    g_post.add_argument('--no-video-thumbnails', action='store_true',
                         help='Do not download thumbnails of videos.')
-    g_what.add_argument('-G', '--geotags', action='store_true',
+    g_post.add_argument('-G', '--geotags', action='store_true',
                         help='Download geotags when available. Geotags are stored as a '
                              'text file with the location\'s name and a Google Maps link. '
                              'This requires an additional request to the Instagram '
                              'server for each picture, which is why it is disabled by default.')
-    g_what.add_argument('-C', '--comments', action='store_true',
+    g_post.add_argument('-C', '--comments', action='store_true',
                         help='Download and update comments for each post. '
                              'This requires an additional request to the Instagram '
                              'server for each post, which is why it is disabled by default.')
-    g_what.add_argument('--no-captions', action='store_true',
+    g_post.add_argument('--no-captions', action='store_true',
                         help='Do not create txt files.')
-    g_what.add_argument('--post-metadata-txt', action='append',
+    g_post.add_argument('--post-metadata-txt', action='append',
                         help='Template to write in txt file for each Post.')
-    g_what.add_argument('--storyitem-metadata-txt', action='append',
+    g_post.add_argument('--storyitem-metadata-txt', action='append',
                         help='Template to write in txt file for each StoryItem.')
-    g_what.add_argument('--no-metadata-json', action='store_true',
+    g_post.add_argument('--no-metadata-json', action='store_true',
                         help='Do not create a JSON file containing the metadata of each post.')
-    g_what.add_argument('--metadata-json', action='store_true',
+    g_post.add_argument('--metadata-json', action='store_true',
                         help=SUPPRESS)
-    g_what.add_argument('--no-compress-json', action='store_true',
+    g_post.add_argument('--no-compress-json', action='store_true',
                         help='Do not xz compress JSON files, rather create pretty formatted JSONs.')
-    g_what.add_argument('-s', '--stories', action='store_true',
+    g_prof.add_argument('-s', '--stories', action='store_true',
                         help='Also download stories of each profile that is downloaded. Requires --login.')
-    g_what.add_argument('--stories-only', action='store_true',
+    g_prof.add_argument('--stories-only', action='store_true',
                         help='Rather than downloading regular posts of each specified profile, only download '
                              'stories. Requires --login. Does not imply --no-profile-pic.')
-    g_what.add_argument('--tagged', action='store_true',
+    g_prof.add_argument('--tagged', action='store_true',
                         help='Also download posts where each profile is tagged.')
-    g_what.add_argument('--tagged-only', action='store_true',
+    g_prof.add_argument('--tagged-only', action='store_true',
                         help='Download only post where each profile is tagged, not their regular posts.')
-    g_what.add_argument('--post-filter', '--only-if', metavar='filter',
+
+    g_cond = parser.add_argument_group("Which Posts to Download")
+
+    g_cond.add_argument('-F', '--fast-update', action='store_true',
+                        help='For each target, stop when encountering the first already-downloaded picture. This '
+                             'flag is recommended when you use Instaloader to update your personal Instagram archive.')
+
+    g_cond.add_argument('--post-filter', '--only-if', metavar='filter',
                         help='Expression that, if given, must evaluate to True for each post to be downloaded. Must be '
                              'a syntactically valid python expression. Variables are evaluated to '
                              'instaloader.Post attributes. Example: --post-filter=viewer_has_liked.')
-    g_what.add_argument('--storyitem-filter', metavar='filter',
+    g_cond.add_argument('--storyitem-filter', metavar='filter',
                         help='Expression that, if given, must evaluate to True for each storyitem to be downloaded. '
                              'Must be a syntactically valid python expression. Variables are evaluated to '
                              'instaloader.StoryItem attributes.')
 
-    g_stop = parser.add_argument_group('When to Stop Downloading',
+    g_cond.add_argument('-c', '--count',
-                                       'If none of these options are given, Instaloader goes through all pictures '
-                                       'matching the specified targets.')
-    g_stop.add_argument('-F', '--fast-update', action='store_true',
-                        help='For each target, stop when encountering the first already-downloaded picture. This '
-                             'flag is recommended when you use Instaloader to update your personal Instagram archive.')
-    g_stop.add_argument('-c', '--count',
                         help='Do not attempt to download more than COUNT posts. '
                              'Applies only to #hashtag and :feed.')