network/youtube-dl: Updated for version 2016.03.01.

Signed-off-by: Dimitris Zlatanidis <d.zlatanidis@gmail.com>

1 files changed, 63 insertions, 16 deletions

diff --git a/network/youtube-dl/youtube-dl.1 b/network/youtube-dl/youtube-dl.1
index 7c038b8847f00..c88d605ab6600 100644
--- a/network/youtube-dl/youtube-dl.1
+++ b/network/youtube-dl/youtube-dl.1
@@ -839,17 +839,26 @@ On Linux, the system wide configuration file is located at
 On Windows, the user wide configuration file locations are
 \f[C]%APPDATA%\\youtube\-dl\\config.txt\f[] or
 \f[C]C:\\Users\\<user\ name>\\youtube\-dl.conf\f[].
+.PP
 For example, with the following configuration file youtube\-dl will
-always extract the audio, not copy the mtime and use a proxy:
+always extract the audio, not copy the mtime, use a proxy and save all
+videos under \f[C]Movies\f[] directory in your home directory:
 .IP
 .nf
 \f[C]
-\-\-extract\-audio
+\-x
 \-\-no\-mtime
 \-\-proxy\ 127.0.0.1:3128
+\-o\ ~/Movies/%(title)s.%(ext)s
 \f[]
 .fi
 .PP
+Note that options in configuration file are just the same options aka
+switches used in regular command line calls thus there \f[B]must be no
+whitespace\f[] after \f[C]\-\f[] or \f[C]\-\-\f[], e.g.
+\f[C]\-o\f[] or \f[C]\-\-proxy\f[] but not \f[C]\-\ o\f[] or
+\f[C]\-\-\ proxy\f[].
+.PP
 You can use \f[C]\-\-ignore\-config\f[] if you want to disable the
 configuration file for a particular youtube\-dl run.
 .SS Authentication with \f[C]\&.netrc\f[] file
@@ -900,6 +909,9 @@ variable manually.
 .PP
 The \f[C]\-o\f[] option allows users to indicate a template for the
 output file names.
+.PP
+\f[B]tl;dr:\f[] navigate me to examples (#output-template-examples).
+.PP
 The basic usage is not to set any template arguments when downloading a
 single file, like in
 \f[C]youtube\-dl\ \-o\ funny_video.flv\ "http://some/video"\f[].
@@ -1046,9 +1058,9 @@ or &, such as when transferring the downloaded filename to a Windows
 system or the filename through an 8bit\-unsafe channel.
 In these cases, add the \f[C]\-\-restrict\-filenames\f[] flag to get a
 shorter title:
+.SS Output template examples
 .PP
-Examples (note on Windows you may need to use double quotes instead of
-single):
+Note on Windows you may need to use double quotes instead of single.
 .IP
 .nf
 \f[C]
@@ -1061,6 +1073,9 @@ youtube\-dl_test_video_.mp4\ \ \ \ \ \ \ \ \ \ #\ A\ simple\ file\ name
 #\ Download\ YouTube\ playlist\ videos\ in\ separate\ directory\ indexed\ by\ video\ order\ in\ a\ playlist
 $\ youtube\-dl\ \-o\ \[aq]%(playlist)s/%(playlist_index)s\ \-\ %(title)s.%(ext)s\[aq]\ https://www.youtube.com/playlist?list=PLwiyx1dc3P2JR9N8gQaQN_BCvlSlap7re
 
+#\ Download\ all\ playlists\ of\ YouTube\ channel/user\ keeping\ each\ playlist\ in\ separate\ directory:
+$\ youtube\-dl\ \-o\ \[aq]%(uploader)s/%(playlist)s/%(playlist_index)s\ \-\ %(title)s.%(ext)s\[aq]\ https://www.youtube.com/user/TheLinuxFoundation/playlists
+
 #\ Download\ Udemy\ course\ keeping\ each\ chapter\ in\ separate\ directory\ under\ MyVideos\ directory\ in\ your\ home
 $\ youtube\-dl\ \-u\ user\ \-p\ password\ \-o\ \[aq]~/MyVideos/%(playlist)s/%(chapter_number)s\ \-\ %(chapter)s/%(title)s.%(ext)s\[aq]\ https://www.udemy.com/java\-tutorial/
 
@@ -1091,6 +1106,8 @@ expression\f[], i.e.
 an expression that describes format or formats you would like to
 download.
 .PP
+\f[B]tl;dr:\f[] navigate me to examples (#format-selection-examples).
+.PP
 The simplest case is requesting a specific format, for example with
 \f[C]\-f\ 22\f[] you can download the format with format code equal to
 22.
@@ -1183,7 +1200,8 @@ than 480 you can use \f[C]\-f\ \[aq](mp4,webm)[height<480]\[aq]\f[].
 .PP
 Since the end of April 2015 and version 2015.04.26 youtube\-dl uses
 \f[C]\-f\ bestvideo+bestaudio/best\f[] as default format selection (see
-#5447, #5456).
+#5447 (https://github.com/rg3/youtube-dl/issues/5447),
+#5456 (https://github.com/rg3/youtube-dl/issues/5456)).
 If ffmpeg or avconv are installed this results in downloading
 \f[C]bestvideo\f[] and \f[C]bestaudio\f[] separately and muxing them
 together into a single file giving the best overall quality available.
@@ -1209,9 +1227,9 @@ you want to download the best available quality media served as a single
 file, you should explicitly specify your choice with \f[C]\-f\ best\f[].
 You may want to add it to the configuration file (#configuration) in
 order not to type it every time you run youtube\-dl.
+.SS Format selection examples
 .PP
-Examples (note on Windows you may need to use double quotes instead of
-single):
+Note on Windows you may need to use double quotes instead of single.
 .IP
 .nf
 \f[C]
@@ -1455,9 +1473,10 @@ means you\[aq]re using an outdated version of Python.
 Please update to Python 2.6 or 2.7.
 .SS What is this binary file? Where has the code gone?
 .PP
-Since June 2012 (#342) youtube\-dl is packed as an executable zipfile,
-simply unzip it (might need renaming to \f[C]youtube\-dl.zip\f[] first
-on some systems) or clone the git repository, as laid out above.
+Since June 2012 (#342 (https://github.com/rg3/youtube-dl/issues/342))
+youtube\-dl is packed as an executable zipfile, simply unzip it (might
+need renaming to \f[C]youtube\-dl.zip\f[] first on some systems) or
+clone the git repository, as laid out above.
 If you modify the code, you can run it by executing the
 \f[C]__main__.py\f[] file.
 To recompile the executable, run \f[C]make\ youtube\-dl\f[].
@@ -1644,8 +1663,15 @@ zip
 nosetests
 .SS Adding support for a new site
 .PP
-If you want to add support for a new site, you can follow this quick
-list (assuming your service is called \f[C]yourextractor\f[]):
+If you want to add support for a new site, first of all \f[B]make
+sure\f[] this site is \f[B]not dedicated to copyright
+infringement (#can-you-add-support-for-this-anime-video-site-or-site-which-shows-current-movies-for-free)\f[].
+youtube\-dl does \f[B]not support\f[] such sites thus pull requests
+adding support for them \f[B]will be rejected\f[].
+.PP
+After you have ensured this site is distributing it\[aq]s content
+legally, you can follow this quick list (assuming your service is called
+\f[C]yourextractor\f[]):
 .IP " 1." 4
 Fork this repository (https://github.com/rg3/youtube-dl/fork)
 .IP " 2." 4
@@ -1720,12 +1746,33 @@ Have a look at
 \f[C]youtube_dl/extractor/common.py\f[] (https://github.com/rg3/youtube-dl/blob/master/youtube_dl/extractor/common.py)
 for possible helper methods and a detailed description of what your
 extractor should and may
-return (https://github.com/rg3/youtube-dl/blob/master/youtube_dl/extractor/common.py#L62-L200).
+return (https://github.com/rg3/youtube-dl/blob/58525c94d547be1c8167d16c298bdd75506db328/youtube_dl/extractor/common.py#L68-L226).
 Add tests and code for as many as you want.
 .IP " 8." 4
-If you can, check the code with
-flake8 (https://pypi.python.org/pypi/flake8).
+Keep in mind that the only mandatory fields in info dict for successful
+extraction process are \f[C]id\f[], \f[C]title\f[] and either
+\f[C]url\f[] or \f[C]formats\f[], i.e.
+these are the critical data the extraction does not make any sense
+without.
+This means that any
+field (https://github.com/rg3/youtube-dl/blob/58525c94d547be1c8167d16c298bdd75506db328/youtube_dl/extractor/common.py#L138-L226)
+apart from aforementioned mandatory ones should be treated \f[B]as
+optional\f[] and extraction should be \f[B]tolerate\f[] to situations
+when sources for these fields can potentially be unavailable (even if
+they always available at the moment) and \f[B]future\-proof\f[] in order
+not to break the extraction of general purpose mandatory fields.
+For example, if you have some intermediate dict \f[C]meta\f[] that is a
+source of metadata and it has a key \f[C]summary\f[] that you want to
+extract and put into resulting info dict as \f[C]description\f[], you
+should be ready that this key may be missing from the \f[C]meta\f[]
+dict, i.e.
+you should extract it as \f[C]meta.get(\[aq]summary\[aq])\f[] and not
+\f[C]meta[\[aq]summary\[aq]]\f[].
+Similarly, you should pass \f[C]fatal=False\f[] when extracting data
+from a webpage with \f[C]_search_regex/_html_search_regex\f[].
 .IP " 9." 4
+Check the code with flake8 (https://pypi.python.org/pypi/flake8).
+.IP "10." 4
 When the tests pass, add (http://git-scm.com/docs/git-add) the new files
 and commit (http://git-scm.com/docs/git-commit) them and
 push (http://git-scm.com/docs/git-push) the result, like this:
@@ -1740,7 +1787,7 @@ $\ git\ push\ origin\ yourextractor
 \f[]
 .fi
 .RE
-.IP "10." 4
+.IP "11." 4
 Finally, create a pull
 request (https://help.github.com/articles/creating-a-pull-request).
 We\[aq]ll then review and merge it.