[vlc-devel] [RFC 02/10] doc: document Media Resource Locator

[Wilawar]

This is what I’ve found so far (I’ve omitted the formatting codes to make the text easier to compare):
1. I suggest rewording the first paragraph from
> “The MRL-specification is a VLC intrinsic extension to RFC3986, providing means to associate extra media-related information within the resource-identifier.”
to
> V1: “MRLs are an extension to URIs as defined in RFC3986. They are used by VLC in certain situations to supply extra media-related information within the resource identifier.”
> V2: “MRLs are an extension to URIs (defined in RFC3986) that was developed by the VLC project. They provide a means to supply extra media-related information within the resource identifier.”

I’m not sure if what you wanted to say with ‘VLC intrinsic’ is that the MRL scheme is something you’ve come up
with inside the VLC _project_ (and not that they are used by the program, VLC Media Player) and whether you wanted to keep this fact, so I’ve written two versions.


2. “[…]through a direct (or indirect) call to[…]” – Since it doesn’t matter whether the call is direct or indirect
and you needn’t draw attention to it working both ways, just leave the adjective out: “[…]through a call to[…]”


3. I think that this sentence is not really wrong, but it doesn’t read fluently to me:
> “As an example, with the use of an MRL one can specify that a certain demux is to be unconditionally used for a specific resource, such as in the below (forcing usage of demuxdump).”
So I would have rephrased it like this:
> “To give just one example, MRLs allow to encode that a specific demuxer must be used for some resource under all circumstances, as shown by the MRL below, which would force VLC to use demuxdump:”
Then it occured to me (while thinking about the wording) that what you’ve written there is rather odd
for an introduction. In fact, what has been written above it, between ‘/defgroup mrl’ and
‘/section mrl_introduction’, resembles their style much closer.
Additionally, take note that, as written, the text is actually misleading. The MRL doesn’t allow to specify that
the demux must be used for the resource under all circumstances. Instead, it’s only about _this one instance_. Reopening the resource with a suitably different MRL will make VLC use a different demuxer.
Therefore, I suggest instead of the above to rename the section to ‘Some examples of their use’
(or something akin). This would entail resolving the repetitions that arise. While at it, I would convert this
section to a list (with bullet points) and give the first point as
> “MRLs allow to encode that a selected demuxer be used for a playback operation under all circumstances, as shown by the following MRL, which would force VLC to use demuxdump:”


Ok, so much for now, the sunlight on my screen has become a problem and it’s also taken long enough. I’ll go over the rest either later today or in a few days, if you don’t object. This time around, since you didn’t give
me any feedback on my mail formatting proposals, I’ve just inserted a line break around the edge of the writing
area but omitted these for the text proposals. Hope it works.

-- 
http://www.fastmail.com - A no graphics, no pop-ups email service