[FFmpeg-devel] [PATCH] doc/protocols/file: document general file protocol URL syntax

[Stefano Sabatini]

On date Saturday 2014-01-04 20:44:33 +0100, Alexander Strasser encoded:
> On 2014-01-04 14:51 +0100, Stefano Sabatini wrote:
> > Also drop confusing ff* tools reference about exceptions to the
> > file:FILENAME syntax, which is not ff* tool specific.
> > ---
> >  doc/protocols.texi | 16 ++++++++++++----
> >  1 file changed, 12 insertions(+), 4 deletions(-)
> > 
> > diff --git a/doc/protocols.texi b/doc/protocols.texi
> > index de157f7..9c50dc1 100644
> > --- a/doc/protocols.texi
> > +++ b/doc/protocols.texi
> > @@ -119,16 +119,24 @@ File access protocol.
> >  
> >  Allow to read from or read to a file.
> 
>   OT: This should be "write to", no?

Uh sure, will fix in a different commit.

> > +A file URL can have the form:
> > + at example
> > +file:@var{filename}
> > + at end example
> > +
> > +where @var{filename} is the path of the file to read.
> > +
> 
> 
> > +A filename not containing the special character ":", or in the form
> > + at var{X}:@var{filename} (for a Windows filename where @var{X} is the
> > +drive name) is automatically recognized as a file protocol URL, so
> > +that no file protocol prefix is required.
> 
>   This is not fully accurate. All paths that contain characters not
> allowed in a protocol name before the colon will work. Actually there
> is even more to it: nested protocols and stuff.
> 
>   Maybe we should write it this way:
> 
>   All URLs that do not have a protocol prefix will be assumed to be
>   file URLs. Depending on the build, URLs that look like Windows paths
>   with the drive letter at the beginning will also be assumed to be
>   file URLs (usually not the case in builds for unix-like systems).

Your version is more accurate, thus I adopted it (but changed to
singular form for grammatical consistency with the first sentence).

> 
>   The rules on determining the protocol portion of an URL should
> probably be documented at some other place (if they not already are).
> And a link to that place should be added here.
> 
>   I personally dislike that we do the DOS path treatment depending
> on the build environment: Is HAVE_DOS_PATHS defined?
>   
> 
> > +
> >  For example to read from a file @file{input.mpeg} with @command{ffmpeg}
> >  use the command:
> >  @example
> >  ffmpeg -i file:input.mpeg output.mpeg
> >  @end example
> >  
> > -The ff* tools default to the file protocol, that is a resource
> > -specified with the name "FILE.mpeg" is interpreted as the URL
> > -"file:FILE.mpeg".
> > -
> >  This protocol accepts the following options:
> >  
> >  @table @option
> 
>   I like the patch, so I am fine if you want to push it the
> way it is. Improvements are still possible afterwards.

Thanks for the review, will push it soon.
-- 
FFmpeg = Furious and Fantastic Most Perennial Erudite Glue