[vlc-devel] [vlc-commits] doc: document Media Resource Locator

[Rémi Denis-Courmont]

On December 6, 2016 9:58:28 AM EST, git at videolan.org wrote:
>vlc | branch: master | Filip Roséen <filip at atch.se> | Mon Nov  7
>16:46:49 2016 +0100| [aca5d94f4fbd9d7e97959c96c3f6751ae70093e5] |
>committer: Thomas Guillem
>
>doc: document Media Resource Locator
>
>There has never been any documentation related to what a MRL actually
>is, these changes addresses that by (hopefully) describing the entity
>in a way that makes it easier for future developers to treat them
>correctly.
>
>Signed-off-by: Thomas Guillem <thomas at gllm.fr>
>
>>
>http://git.videolan.org/gitweb.cgi/vlc.git/?a=commit;h=aca5d94f4fbd9d7e97959c96c3f6751ae70093e5
>---
>
>doc/standalone/mrl.dox | 90
>++++++++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 90 insertions(+)
>
>diff --git a/doc/standalone/mrl.dox b/doc/standalone/mrl.dox
>new file mode 100644
>index 0000000..6d9b0fc
>--- /dev/null
>+++ b/doc/standalone/mrl.dox
>@@ -0,0 +1,90 @@
>+/**
>+ * \defgroup mrl Media Resource Locator (MRL)
>+ *
>+ * The \em MRL-specification is a VLC intrinsic extension to <a
>+ * href="https://tools.ietf.org/html/rfc3986">RFC3986</a>, providing
>means to
>+ * associate extra media-related information within the \em
>resource-identifier.
>+ *
>+ * \note \em MRLs are only used when an item is to be played by \em
>VLC,
>+ *       through a direct (or indirect) call to \ref input_Create and
>\ref
>+ *       input_CreatePreparser, which means that they are not handled
>by
>+ *       functions such as \ref vlc_UrlParse and \ref
>vlc_stream_NewURL (as
>+ *       implied by their names).
>+ *
>+ * \section mrl_introduction Introduction
>+ *
>+ * As an example, with the use of an \em MRL one can specify that a
>certain \ref
>+ * demux is to be unconditionally used for a specific resource, such
>as in the
>+ * below (forcing usage of \em demuxdump).
>+ *
>+ * \verbatim
>http/demuxdump,none://example.com/path/to/media\endverbatim
>+ *
>+ * There is also the possibility of specifying attributes related to
>the
>+ * playback behavior of the referred to resource, such as what range
>of titles
>+ * and chapters that are to be played.
>+ *
>+ * \verbatim http://example.com/media.mkv#0:1-1:5\endverbatim
>+ *
>+ * \section mrl_technical Technical Information
>+ *
>+ * The overall specification in <a
>+ * href="https://tools.ietf.org/html/rfc3986">RFC3986</a> are
>inherited by \em
>+ * MRLs, though some entities have been redefined in order to provide
>support
>+ * for additional \em media-related \em information, other entities
>(treated as
>+ * arbitrary data in a \em URI) is explicitly defined to have special
>meaning
>+ * within an \em MRL.
>+ *
>+ * \subsection mrl_technical_scheme 3.1. Scheme
>+ *
>+ * In an \em MRL, what <a
>href="https://tools.ietf.org/html/rfc3986">RFC3986</a>
>+ * refers to as `scheme` is allowed to contain a \em forward-slash,
>and if such
>+ * is present, the data prior to the slash denotes the \em scheme (as
>originally
>+ * defined by \em RFC3986), whereas the data that follows specifies a
>list of
>+ * \link demux demultiplexers\endlink to probe when dealing with the
>resource.
>+ *
>+ *     mrl-scheme   = *( %x20-7E )
>+ *     mrl-demux    = *( %x20-2B / %x2D-7E )
>+ *     mrl-demuxers = mrl-demux *( "," mrl-demux )
>+ *     scheme       =/ ( mrl-scheme [ "/" mrl-demuxers ] )
>+ *
>+ *  - `mrl-demuxers` is a \em comma-delimited list of individual \ref
>+ *    demux that will be tried in order of appearance when the
>+ *    resource requires a \ref demux to be created.
>+ *
>+ *  - If the currently processed `mrl-demux` is `"any"`
>+ *    (case-insensitive), than any \ref demux is allowed to be probed
>+ *    (and potentially used) at that stage.
>+ *
>+ *  - If no specified \ref demux specified in `mrl-demuxers` can
>+ *    handle the resource, the media shall fail to open.
>+ *
>+ * \subsection mrl_technical_fragment 3.5. Fragment
>+ *
>+ * \em MRL does not inherently change the <a
>+ * href="https://tools.ietf.org/html/rfc5234">ABNF</a> for \em
>fragment-data as
>+ * specified by <a
>href="https://tools.ietf.org/html/rfc3986">RFC3986</a>, it
>+ * does however provide special meaning to data matching the patterns
>listed in
>+ * this section.
>+ *
>+ * - \parblock
>+ *  <h4>`mrl-section`</h4>
>+ *  \verbatim
>+mrl-title   = DIGIT *DIGIT
>+mrl-chapter = DIGIT *DIGIT
>+mrl-section = mrl-title [ ":" mrl-chapter ] [ "-" mrl-title [ ":"
>mrl-chapter ] ]
>+\endverbatim
>+ *  If the data contained in the `fragmentof` an \em MRL matches
>+ *  `mrl-section`, the data denotes the offset to start, and
>conditionally stop
>+ *  (if present), the resource during playback,
>+ *
>+ *  `mrl-title` and `mrl-chapter` refers to the index of the \em title
>and \em
>+ *  chapter, respectively. Data before the optional hyphen denotes the
>starting
>+ *  position, and data following it, if any, denotes where to stop.
>+ *
>+ *  The range is specified as `[start,stop)`, meaning that playback
>will
>+ *  continue until \em stop has been reached, it does not include the
>contents
>+ *  of the entity referred to by \em stop.
>+ *
>+ *  \endparblock
>+ *
>+ **/
>
>_______________________________________________
>vlc-commits mailing list
>vlc-commits at videolan.org
>https://mailman.videolan.org/listinfo/vlc-commits

WTF guys seriously? There were MULTIPLE comments from different people and exactly zero of them were answered. It is not the first time recently that VideoLabs makes a joke of the review process.

At this point, I am blanket rejecting all patches from Filip, Thomas and Steve. This is absolutely unacceptable.
-- 
Rémi Denis-Courmont