Issue 1216 improve documentation of matchers

Title improve documentation of matchers
Priority wishlist Status resolved
Milestone Resolved in
Superseder Nosy List btcoburn, darcs-devel, dmitry.kurochkin, kowey, thorkilnaur, twb
Assigned To twb

Created on 2008-11-10.09:32:15 by dagit, last changed 2009-12-08.15:10:30 by twb.

msg6630 (view) Author: dagit Date: 2008-11-10.09:32:12
Please make matchers into an easier to find section.

Matchers are very powerful, but finding them in the manual can be a bit tricky.
 For example, the interactive help just says:
             --matches=PATTERN               select patches matching PATTERN

Going to the darcs manual there is no clearly marked section for learning about
what makes up a valid PATTERN.

To find patterns you have to go here:

They are defined in the section "Match".

I think this section is mostly adequate.  It would be nice if there was a table
that listed all the matches in a nice simple format with an example.

Probably the easiest and more important change we can make is to make
matches/patterns be mentioned in the table of contents and have the interactive
help suggest the user go look there.
msg6657 (view) Author: btcoburn Date: 2008-11-12.01:23:00
I just spent ~20 minutes looking for this part of the manual yesterday! I know
this sounds stupid on my part, but I KNEW that section was in there and didn't
have it bookmarked. A user that's just getting used to darcs would likely miss
out on this great feature.

I think patch selection of all kinds should be called out in a section apart
from the commands. Good examples of useful regular expressions, match patterns,
and interactive strategies would help a lot. References to this section should
be mentioned regularly in the documentation for commands that do patch selection.
msg7719 (view) Author: twb Date: 2009-04-18.10:08:44
In the manual, the subsubsections are marked up using named paragraphs,
which is why \paragraph{Match} doesn't show up in ToC.  I guess I could
change that...

Different, but similar, text is available from "darcs help --match".
For a while this has been included in the manpage, and as a result of the
following patch it should also be referred to at the bottom of "darcs help".

Sat Apr 18 13:30:44 EST 2009  Trent W. Buck <trentbuck@gmail.com>
  * Advertise help --match in "darcs help".
msg9561 (view) Author: twb Date: 2009-12-08.15:10:23
The following patch updated the status of issue1216 to be resolved:

* Resolve issue1216: list Match section in ToC. 
Ignore-this: edebeeefc69d60a18c13a7c2358da57
Date User Action Args
2008-11-10 09:32:15dagitcreate
2008-11-12 01:23:03btcoburnsetstatus: unread -> unknown
nosy: + btcoburn
messages: + msg6657
2009-04-18 10:08:48twbsetnosy: kowey, dagit, simon, twb, thorkilnaur, btcoburn, dmitry.kurochkin
messages: + msg7719
2009-08-10 23:51:09adminsetnosy: - dagit
2009-08-20 02:53:44twbsetstatus: unknown -> needs-reproduction
nosy: kowey, simon, twb, thorkilnaur, btcoburn, dmitry.kurochkin
2009-08-25 17:34:08adminsetnosy: + darcs-devel, - simon
2009-08-27 14:28:29adminsetnosy: kowey, darcs-devel, twb, thorkilnaur, btcoburn, dmitry.kurochkin
2009-12-08 15:10:30twbsetstatus: needs-reproduction -> resolved
messages: + msg9561