[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