On Sun, Aug 30, 2009 at 18:16:20 +1000, Trent W.Buck wrote: > Sun Aug 30 13:54:55 EST 2009 Trent W. Buck <[email protected]> > * Rewrite "darcs changes" help. > Unlike earlier work, this aims to just make the literate documentation > visible via "darcs help". Improving the readability and coverage will > have to wait for a later patch.
I think I'll just push this and hope for future patches, thanks. Rewrite "darcs changes" help. ----------------------------- > + "The --last and --max-count options both limit the number of patches\n" ++ > + "listed. The former applies BEFORE other filters, whereas the latter\n" ++ > + "applies AFTER other filters. For example `darcs changes foo.c\n" ++ > + "--max-count 3' will print the last three patches that affect foo.c,\n" ++ > + "whereas `darcs changes --last 3 foo.c' will, of the last three\n" ++ > + "patches, print only those that affect foo.c.\n" ++ New doc on --max-count. Thanks. > -When given the \verb!--context! flag, darcs changes outputs sufficient > -information to allow the current state of the repository to be > -recreated at a later date. This information should generally be piped to a > -file, and then can be used later in conjunction with > -\verb!darcs get --context! to recreate the current version. > + "Three output formats exist. The default is --human-readable. You can\n" > ++ > + "also select --context, which is the internal format (as seen in patch\n" ++ > + "bundles) that can be re-read by Darcs (e.g. `darcs get --context').\n" ++ > + "\n" ++ I think the old documentation on --context is a bit clearer Also, I'd expect --context to be documented in a separate paragraph from the default format, as it's really quite a different creature. I tend to think of human readable and XML as being just variants of each other, and --context as something that really ought to be a different command as per your http://bugs.darcs.net/issue1258 > + "Finally, there is --xml-output, which emits valid XML... unless a the\n" ++ > + "patch metadata (author, name or description) contains a non-ASCII\n" ++ > + "character and was recorded in a non-UTF8 locale.\n" ++ I don't know if this is bad practice, but this could point to the bug tracker http://bugs.darcs.net/issue33 or perhaps give some indication that this is considered a bug to be fixed in the long term. > + -- FIXME: can't we just disallow the following usage? > + "Note that while the --context flag may be used in conjunction with\n" ++ > + "--xml-output or --human-readable, in neither case will darcs get be\n" ++ > + "able to read the output. On the other hand, sufficient information\n" ++ > + "WILL be output for a knowledgeable human to recreate the current state\n" > ++ > + "of the repository.\n" ++ See http://bugs.darcs.net/issue995 (which we could always revisit) -- Eric Kow <http://www.nltg.brighton.ac.uk/home/Eric.Kow> PGP Key ID: 08AC04F9
pgpn2Gv7Bd8Px.pgp
Description: PGP signature
_______________________________________________ darcs-users mailing list [email protected] http://lists.osuosl.org/mailman/listinfo/darcs-users
