[darcs-users] darcs patch: Advertise help --match in "darcs help".

[Thomas Hartman]

>Removes documentation for --patches.  Does this break issue449?  Are
EREs and --patches documented somewhere else?  If not, should be moved
instead of removed.

The attached patch addresses this issue.

On Thu, Apr 30, 2009 at 6:32 AM, Trent W. Buck <trentbuck at gmail.com> wrote:

> Summary: there are some good ideas here, but I'd like it to be polished
> further before applying it.  Specifically, I approve of explaining the
> difference between --match, --matches, --to-match and --from-match (and
> their --patch counterparts),  and I approvide of adding some examples
> that employ the logic operators ((), and, or, not).
>
> Thomas Hartman <thomashartman1 at googlemail.com> writes:
> > How's this? Removed the darcs --help stuff, and tweaked the darcs help
> > --match message a bit as well.
>
> > [improve darcs help --match
> > Thomas Hartman <thomashartman1 at gmail.com>**20090428040315
> >  Ignore-this: 874a0b3b08ac036139da23ecd1287c80
> > ] hunk ./src/Darcs/Patch/Match.lhs 261
> >  helpOnMatchers = unlines $
> >    ["Selecting Patches:",
> >     "",
> > -   "The --patches option yields patches with names matching an
> `extended'",
> > -   "regular expression.  See regex(7) for details.  The --matches
> option",
>
> Removes documentation for --patches.  Does this break issue449?  Are
> EREs and --patches documented somewhere else?  If not, should be moved
> instead of removed.
>
> Is there a more appropriate place to explain --patch and friends?
> I'm inclined to have a "darcs help matching" which explains all of the
> --tag, --patch and --match (and variants).
>
> > -   "yields patches that match a logical (Boolean) expression: one or
> more",
> > -   "primitive expressions combined by grouping (parentheses) and the",
> > -   "complement (not), conjunction (and) and disjunction (or)
> operators.",
> > -   "The C notation for logic operators (!, && and ||) can also be
> used.",
> > +   "The --matches, --from-match, and to-match options yield patches
> > that match a logical (Boolean) expression made up of primitive
> > expressions.",
>
> Removes hard wrapping.  This is bad, because the output is displayed on
> a terminal, and most (all?) terminals will soft wrap at the character,
> rather than at the word.  I feel that using soft wrapping in this
> context is both unconventional and difficult to read.  Currently I'm
> standardizing on wrapping at 70 characters (as it appears on the
> terminal, i.e. not counting the < "",> part) in help text.
>
> Adds mention of --from-match and --to-match (good), but doesn't explain
> how they differ from --matches (bad).  Doesn't mention --match (bad) and
> is missing the leading hyphens in --to-match (inconsistent).
>
> > +   "The --match option works similarly, for commands that take a single
> patch rather than a range",
> > +
> > +   "A primitive expression is an expression type plus a string, eg
> \"date 20070101\" or \"hash
> 20040403105958-53a90-c719567e92c3b0ab9eddd5290b705712b8b918ef\"",
>
> This text is also included in the manpage, so roff style `smart quotes'
> should be used, rather than "double quotes", because the latter renders
> incorrectly as ”smart quotes”, i.e. BOTH are right double quotes.  Sorry
> about that, it'll be sorted out properly, eventually.
>
> I'm not sure this paragraph adds much value, because examples of
> primitive expressions are already given in a separate list.  For the
> manpage, including the long hash example in a paragraph may also result
> in ugly wrapping.
>
> > +   "Supported expression types are: " ]
> > +
> > +   ++ keywords ++
>
> This is duplicated below.  Is this a patch incomplete?
>
> > +
> > +   [
> > +
> > +   "Primitive expressions can be combined combined by ",
> > +   " -- grouping (parentheses)" ,
> > +   " -- negation (not)",
> > +   " -- conjunction (and)",
> > +   " -- disjunction (or) operators.",
> > +   " -- Note: (!, && and ||) can be used instead of (not, and, and
> > or)",
>
> (This is duplicated above.)  I'm not convinced that splitting the
> paragraph up into an itemized list is an improvement.  In particular,
> the last item looks quite out of place.
>
> > +   "",
> > +   " darcs changes --matches='name documentation and not author=gwern'",
>
> Adds an example using logic operators.  Good.  Multiple examples would
> be better, built from a list as is done for the examples of primitives
> bound to 'keywords'.
>
> >     "",
> >     "The following primitive Boolean expressions are supported:"]
> >    ++ keywords
>
> _______________________________________________
> darcs-users mailing list
> darcs-users at darcs.net
> http://lists.osuosl.org/mailman/listinfo/darcs-users
>



-- 
Thomas Hartman

Darcs hosting: patch-tag.com
Build a webapp with haskell: happstack.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osuosl.org/pipermail/darcs-users/attachments/20090501/2dbd6b3b/attachment-0001.htm>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: addDocumentationForPatchesFromPatchAndToPatch.patch
Type: text/x-patch
Size: 58167 bytes
Desc: not available
URL: <http://lists.osuosl.org/pipermail/darcs-users/attachments/20090501/2dbd6b3b/attachment-0001.bin>