Bug#733272: uscan: Clarify options syntax

[James McCoy]

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>

Cheers,
-- 
James
GPG Key: 4096R/331BA3DB 2011-12-05 James McCoy <jamessan at debian.org>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: Digital signature
URL: <http://lists.alioth.debian.org/pipermail/devscripts-devel/attachments/20140119/2c0bdfba/attachment.sig>