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

[Alexander Strasser]

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?

>  
> +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).

  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.

  Alexander
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 181 bytes
Desc: not available
URL: <http://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20140104/06dbe6b4/attachment.asc>