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

Thomas Hartman thomashartman1 at googlemail.com
Sat May 2 00:29:32 UTC 2009


One thing about that last patch: I *think* it is true based on how I have
observed it to behave, but haven't actually checked this in the code.

If it's not true, this definitely should be documented!

On Fri, May 1, 2009 at 7:28 PM, Thomas Hartman <
thomashartman1 at googlemail.com> wrote:

> >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
>



-- 
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/ca81a0b4/attachment.htm>


More information about the darcs-users mailing list