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

[Wilawar]

I had a not-so-productive, short discussion with refp over his repeated linking to the RFC without ever directly
saying that this was the current URI RFC. He gave his preference as reason and wasn’t really considering
rethinking his position. Well, I guess some third party might have to arbitrate or else refp’s version will land
unchanged and I’ll have worked in vain again … :/

Anyways, going over the part I had left aside the last time:
4. The proposed text is (in the section Technical Information):
> “The overall specification in RFC3986 are inherited by MRLs, though some entities have been redefined in order to provide support for additional media-related information, other entities (treated as arbitrary data in a URI) is explicitly defined to have special meaning within an MRL.”
I found it somewhat hard to understand correctly and there are some minor grammatical errors (such as disagreement of some verb’s number (commonly given as singular and plural) with the one of the object.
I would suggest changing it to this:
> “MRLs are hereby specified to be like URIs, except that some of the entities are changed to support carrying additional media-related information and some others are given special meaning as part of MRLs whereas they don’t carry any when they are part of standard URIs.”
I hold it likely that there are other programs that treat some entities in URIs in a special way when no such treatment is mentioned in the standard, that’s why I wrote 'standard URIs' in the end.


5. Section '3.1 Scheme':
> “In an MRL, what RFC3986 refers to as scheme is allowed to contain a forward-slash, and if such is
present, the data prior to the slash denotes the scheme (as originally defined by RFC3986), whereas
the data that follows specifies a list of demultiplexers to probe when dealing with the resource.”
You were being very specific with the distinction of scheme in the RFC and scheme in the MRL spec. and, over that, made the sentence a bit hard to read. (Yes, again. :P)
Take my counter-proposal into consideration, please:
> “MRLs can have a scheme part similar to URIs. (It’s usually the foremost part, such as 'http', 'ftp' or 'magnet'.) In addition, MRL schemes can contain a forward slash that will cause everything in that part after it to be interpreted as a list of demuxers (seperated by commas) that should be probed in the given order when a demux must be created to deal with the resource. (This list of demuxers is referred to as mrl-demuxers in the following grammar.)”
As an aside, I’m not sure instantiating, providing or attaching demuxers should be referred to as creating them, as creating a demuxer would casually be read as coding one up and this ambiguity is easy to avoid.


6. As I have included the remark about the order of probing in the text above, I would suggest to drop the first point after the grammar:
> “`mrl-demuxers` is a \em comma-delimited list of individual demux that will be tried in order of appearance when the resource requires a demux to be created.”


7. The second point could be rewritten, from this:
> “If the currently processed mrl-demux is "any" (case-insensitive), than any demux is allowed to be probed (and potentially used) at that stage.”
to that:
> “The name "any" (case-insensitive) can be used to signify that all demuxers can be probed and any of them be picked at that point of processing the list.”
Should you decide to reject my proposal, be sure to at least replace 'than' by 'then'. ;)


8. The last one of the points:
> “If no specified demux specified in mrl-demuxers can handle the resource, the media shall fail to open.”
There is an obvious repetition in it. Having fixed this up and applyed a bit of my style, it becomes:
> “If none of the demuxers on the list can handle the resource, opening the media should fail.”


9. I think there should be another point there, perhaps before or after the last point:
> “If there is no list of demuxers at all, "any" will semantically be used as the default. If there is a list but it is empty (there is nothing in that part after the forward slash), opening the media should fail as per the next [or previous] point.”


In summary, except for perhaps the grammar, I didn’t encounter anything too technical in this section. I don’t know any better name for it either and don’t want to think about one yet, but the naming could be amended in a rewrite in the future. I would probably split the information into sections differently.


10. Going to '3.5 Fragment':
> “MRL does not inherently change the ABNF for fragment-data as specified by RFC3986, it does however provide special meaning to data matching the patterns listed in this section.”
I hope you’ll agree with me that this does not make all that much sense in its current form. ;) Let me suggest an alternative:
> “The grammar for fragment-data in MRLs is much the same as for URIs. However, some of the data will be treated in a special way if it matches the ABNF patterns below:”


11. Past the grammar:
> “If the data contained in the fragmentof an 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 title and 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 stop has been reached, it does not include the contents of the entity referred to by stop.
You did not define 'fragmentof' anywhere. I think I will rewrite the section as a whole:
> “If the data in the fragmentof part of MRLs matches the pattern named mrl-section, it is taken as a command to start and stop playback at certain entities, with it running from the start to right before the stop (the content from the stop entity is not being played back). The entities are referred to by their indices, mrl-title and mrl-chapter refer each to the index of the title and the chapter within it, respectively. If there is a hyphen, it seperates the names of the start and the stop entity from each other; if there is none, only the start entity is set.”

12. There should be more examples in the two sections I covered. Someone will have to make some up.
I do wonder about the numbering of the sections (3.1 and 3.5), is there a reason for picking those numbers?


Consolidating all my proposals into a new doxygen input file is definitely a task for another day, but I’d like to
hear feedback first, too. It’d surprise me if you were to accept all of them at once and unchanged. ;)

Despite the talk on IRC, I’ll have to thank refp for documenting something I’ve long wondered about, I’m sure it’ll come in handy. :)

-- 
http://www.fastmail.com - Or how I learned to stop worrying and
                          love email again