[Monotone-devel] proper use of '...' in monotone.texi

[Stephen Leake]

There is some variance in the use of '...' in the command reference
section of monotone.texi. For example:

@item mtn add [--[no-]recursive] [--[no-]respect-ignore] @var{pathname...}
@itemx mtn commit address@hidden address@hidden address@hidden
@itemx mtn rename [--bookkeep-only] @var{src} @var{...} @var{dst/}

The intent is to indicate that the argument or option may be repeated;
'add' can take multiple 'pathnames', 'commit' can take multiple
'--message=foo' options, 'rename' can take multiple 'src' files.

This is clear with all variants, except perhaps --message; is it
'logmsg' or '--message=logmsg' that can be repeated.

The only issue is whether to include '...' within the brackets or not.

In html output, this affects the color of the '...' . This difference is
usually hard to perceive.

In info output, this affects whether the '...' is inside or outside the
quotes: `pathname...' vs `pathname'... . 

There's also the issue of refering to the argument in the command
description; for example, a fragment from 'rename' is:

    This command places @code{rename} entries for the paths specified in
    @var{src} and @var{dst} 

Should that be:

    This command places @code{rename} entries for the paths specified in
    @var{src...} and @var{dst} 

or
    This command places @code{rename} entries for the paths specified in
    @var{src}... and @var{dst} 

or 
    This command places @code{rename} entries for the paths specified in
    @var{src} @var{...} and @var{dst} 

In info, the last fragment produces "`src' `...'".

I prefer including the '...' in the reference, to make it clear we are
talking about all of them.

This is not a big issue, but since I'm cleaning up the manual, it's
bugging me.

I could not find a reference for using '...' in syntax descriptions; I
didn't look very hard. It's not in Wikipedia's description of EBNF, for
example. 

If I don't get any opinions, I'll use @var{src...}.

-- 
-- Stephe