Bug#733272: uscan: Clarify options syntax

[Kurt Roeckx]

On Sun, Jan 19, 2014 at 08:13:33PM -0500, James McCoy wrote:
> On Sat, Dec 28, 2013 at 12:20:32AM +0100, Kurt Roeckx wrote:
> > Reading the uscan manpage, it says:
> > | PER-SITE OPTIONS
> > |      A watch file line may be prefixed with `opts=options',
> > |      where options is a comma-separated list of options.  The
> > |      whole options string may be enclosed in double quotes,
> > |      which is necessary if options contains any spaces.  The
> > |      recognised options are as follows:
> > 
> > But having something as:
> > opts=pasv
> > 
> > will result in:
> > uscan warning: malformed opts=... in watchfile, skipping line:
> > opts=pasv
> > 
> > The problem is that you need to add the site after that, and
> > that's not clear from the documentation.
> 
> You're right that we don't explicitly define that the file is parsed
> line-wise, but we do use that sort of wording in the description of the
> file format, and specify that opts is the first field (emphasis added):
> 
>     There  are  two  possibilities  for the syntax of an HTTP watch file
>     __line__, and only one for an FTP __line__.  We begin with the
>     common (and simpler) format.  We describe the __optional opts=...
>     first field__ below, and ignore it in what follows.
> 
> Would it have helped to have something the accepted formats shown
> (something like below) in addition to the existing descriptions?
> 
>     [opts=...] <ftp/http URL pattern> <version> <action>
>     [opts=...] <http base URL> <pattern> <version> <action>

Yes, that would clearly make it more obvious.


Kurt