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

[Richard Levitte]

In message <address@hidden> on Wed, 12 Jan 2011 06:58:48 -0500, Stephen Leake 
<address@hidden> said:

stephen_leake> The only issue is whether to include '...' within the brackets 
or not.
stephen_leake> 
stephen_leake> In html output, this affects the color of the '...' . This 
difference is
stephen_leake> usually hard to perceive.
stephen_leake> 
stephen_leake> In info output, this affects whether the '...' is inside or 
outside the
stephen_leake> quotes: `pathname...' vs `pathname'... . 

For that reason (the info quotes) alone, my vote goes for having ...
outside of the braces.  Otherwise, I'm inclined to think it's actual
(perhaps literal) part of the argument.

stephen_leake> There's also the issue of refering to the argument in the command
stephen_leake> description; for example, a fragment from 'rename' is:
stephen_leake> 
stephen_leake>     This command places @code{rename} entries for the paths 
specified in
stephen_leake>     @var{src} and @var{dst} 
stephen_leake> 
stephen_leake> Should that be:
stephen_leake> 
stephen_leake>     This command places @code{rename} entries for the paths 
specified in
stephen_leake>     @var{src...} and @var{dst} 
stephen_leake> 
stephen_leake> or
stephen_leake>     This command places @code{rename} entries for the paths 
specified in
stephen_leake>     @var{src}... and @var{dst} 
stephen_leake> 
stephen_leake> or 
stephen_leake>     This command places @code{rename} entries for the paths 
specified in
stephen_leake>     @var{src} @var{...} and @var{dst}

None of them.  I find the current description of this command lacking;
it very clearly describes the second form, but not the first form.
I'm guessing the first paragraph is meant to describe the first form,
but the way it's written, it's really quite confusing.
I'd suggest it gets rewritten in much clearer language.

Cheers,
Richard

-- 
Richard Levitte                         address@hidden
                                        http://richard.levitte.org/

"Life is a tremendous celebration - and I'm invited!"
-- from a friend's blog, translated from Swedish