{"thread":{"id":"8107","subject":"[PATCH] Document patch syntax.","startedAt":"2007-05-12T12:07:04Z","lastAt":"2007-05-13T08:28:50Z","messageCount":7,"participants":["Yann Dirson","Karl Hasselström","Junio C Hamano","Jeff King"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"41917","messageId":"20070512120704.22970.45140.stgit@gandelf.nowhere.earth","threadId":"8107","inReplyTo":null,"subject":"[PATCH] Document patch syntax.","fromName":"Yann Dirson","fromEmail":"ydirson@altern.org","sentAt":"2007-05-12T12:07:04Z","receivedAt":"2007-05-12T12:07:04Z","isPatch":true,"sender":{"key":"ydirson@altern.org","avatar":"https://avatars.githubusercontent.com/u/1190950?v=4"},"body":"\n\n\nSigned-off-by: Yann Dirson <ydirson@altern.org>\n---\n\n Documentation/stg.txt |   25 +++++++++++++++++++++++++\n 1 files changed, 25 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/stg.txt b/Documentation/stg.txt\nindex af57c37..3ea51c3 100644\n--- a/Documentation/stg.txt\n+++ b/Documentation/stg.txt\n@@ -51,6 +51,31 @@ Development branch::\n In such a setup, not all commits on your branch need to be StGIT\n patches; there may be regular GIT commits below your stack base.\n \n+Patches\n+~~~~~~~\n+\n+Many StGIT commands take references to StGIT patches as arguments.\n+Patches in the stack are identified with a short name, which must be\n+unique in the stack.\n+\n+Patches in the current stack are just refered to by their name.  Some\n+commands allow to specify a patch in another stack of the repository;\n+this is done by suffixing the patch name with a '@' sign followed by the\n+branch name (eg. 'thispatch@otherbranch').\n+\n+A number of position in the stack related to the patch are also\n+accessible through '//' suffixes.  For example, 'patch//top'' is\n+equivalent to 'patch', and 'patch//bottom' refers to the commit below\n+'patch' (ie. the patch below, or the stack base if this is the\n+bottom-most patch).  Similarly ''//top.old'' and ''//bottom.old''\n+refer to the previous version of the patch (before the last\n+stglink:push[] or stglink:refresh[] operation).  When refering to the\n+current patch, its name can be omitted (eg. 'currentpatch//bottom.old'\n+can be abbreviated as 'bottom.old').\n+\n+If you need to pass a given StGIT reference to a git command,\n+stglink:id[] will convert it to a git commit id.\n+\n OPTIONS\n -------\n \n"},{"id":"41921","messageId":"20070512135644.GA28039@diana.vm.bytemark.co.uk","threadId":"8107","inReplyTo":"20070512120704.22970.45140.stgit@gandelf.nowhere.earth","subject":"Re: [PATCH] Document patch syntax.","fromName":"Karl Hasselström","fromEmail":"kha@treskal.com","sentAt":"2007-05-12T13:56:44Z","receivedAt":"2007-05-12T13:56:44Z","isPatch":true,"sender":{"key":"kha@treskal.com","avatar":"https://gravatar.com/avatar/f0120c734b5279b345075a28521e1ac66acb20c9913ffe9bf6ae97e53f7f3f13?d=mp&s=160"},"body":"On 2007-05-12 14:07:04 +0200, Yann Dirson wrote:\n\n> +Patches in the stack are identified with a short name, which must be\n> +unique in the stack.\n\ns/a short name/short names/, maybe.\n\n> +Patches in the current stack are just refered to by their name.  Some\n> +commands allow to specify a patch in another stack of the repository;\n\ns/allow to/allow you to/. Or \"allows one to\", but I prefer the second\nperson here.\n\n> +this is done by suffixing the patch name with a '@' sign followed by the\n> +branch name (eg. 'thispatch@otherbranch').\n\ns/a '@'/an '@'/; \"'@'\" begins with a vowel sound. :-)\n\n> +A number of position in the stack related to the patch are also\n\ns/position/positions/.\n\n> +accessible through '//' suffixes.  For example, 'patch//top'' is\n> +equivalent to 'patch', and 'patch//bottom' refers to the commit below\n> +'patch' (ie. the patch below, or the stack base if this is the\n\ns/ie./i.e./.\n\n> +bottom-most patch).  Similarly ''//top.old'' and ''//bottom.old''\n\nYou use double quotes here, and single quotes above. What's the\ndistinction?\n\n> +refer to the previous version of the patch (before the last\n> +stglink:push[] or stglink:refresh[] operation).  When refering to the\n\ns/refering/referring/.\n\nOtherwise,\n\nAcked-by: Karl Hasselström <kha@treskal.com>\n\nYes, I'm too picky.\n\n-- \nKarl Hasselström, kha@treskal.com\n      www.treskal.com/kalle\n"},{"id":"41925","messageId":"20070512143827.GE16903@nan92-1-81-57-214-146.fbx.proxad.net","threadId":"8107","inReplyTo":"20070512135644.GA28039@diana.vm.bytemark.co.uk","subject":"Re: [PATCH] Document patch syntax.","fromName":"Yann Dirson","fromEmail":"ydirson@altern.org","sentAt":"2007-05-12T14:38:27Z","receivedAt":"2007-05-12T14:38:27Z","isPatch":true,"sender":{"key":"ydirson@altern.org","avatar":"https://avatars.githubusercontent.com/u/1190950?v=4"},"body":"On Sat, May 12, 2007 at 03:56:44PM +0200, Karl Hasselström wrote:\n> On 2007-05-12 14:07:04 +0200, Yann Dirson wrote:\n> \n> > +Patches in the stack are identified with a short name, which must be\n> > +unique in the stack.\n> \n> s/a short name/short names/, maybe.\n\nHm, not sure how that would play with the end of the sentence - any\nnative english speaker with an opinion ?\n\n\n> > +Patches in the current stack are just refered to by their name.  Some\n> > +commands allow to specify a patch in another stack of the repository;\n> \n> s/allow to/allow you to/. Or \"allows one to\", but I prefer the second\n> person here.\n\nNo strong opinion here.  However, that makes me think we should\nprobably use guideline for the docs - here comes the question of which\nconvention to use when refering to the user.  Do we address her\ndirectly (\"you\"), indirectly (\"the user\", \"her\" - don't remember where\nthe \"female user\" use comes from, but we could maybe follow this),\neven more indirectly (\"one\"), or any other way ?\n\n\n> s/a '@'/an '@'/; \"'@'\" begins with a vowel sound. :-)\n> s/position/positions/.\n> s/ie./i.e./.\n> s/refering/referring/.\n\nOK\n\n> > +bottom-most patch).  Similarly ''//top.old'' and ''//bottom.old''\n> \n> You use double quotes here, and single quotes above. What's the\n> distinction?\n\nEr... is \"typo\" a distinction ? :)\nConfusion induced by wiki markups, probably :(\n\n\n> Yes, I'm too picky.\n\nNot a problem, I tend to be quite picky too :)\n\nBest regards,\n-- \nYann.\n"},{"id":"41944","messageId":"20070512183255.GD28039@diana.vm.bytemark.co.uk","threadId":"8107","inReplyTo":"20070512143827.GE16903@nan92-1-81-57-214-146.fbx.proxad.net","subject":"Re: [PATCH] Document patch syntax.","fromName":"Karl Hasselström","fromEmail":"kha@treskal.com","sentAt":"2007-05-12T18:32:55Z","receivedAt":"2007-05-12T18:32:55Z","isPatch":true,"sender":{"key":"kha@treskal.com","avatar":"https://gravatar.com/avatar/f0120c734b5279b345075a28521e1ac66acb20c9913ffe9bf6ae97e53f7f3f13?d=mp&s=160"},"body":"On 2007-05-12 16:38:27 +0200, Yann Dirson wrote:\n\n> However, that makes me think we should probably use guideline for\n> the docs - here comes the question of which convention to use when\n> refering to the user. Do we address her directly (\"you\"), indirectly\n> (\"the user\", \"her\" - don't remember where the \"female user\" use\n> comes from, but we could maybe follow this), even more indirectly\n> (\"one\"), or any other way ?\n\nI'd go with \"you\", or possibly \"one\" (but I strongly prefer \"you\").\nTalking about the user in the third person (\"the user\", \"her\", etc.)\nseems actively wrong when we are instructing the user on how to do\nthings.\n\n-- \nKarl Hasselström, kha@treskal.com\n      www.treskal.com/kalle\n"},{"id":"41948","messageId":"7vodkpzwzj.fsf@assigned-by-dhcp.cox.net","threadId":"8107","inReplyTo":"20070512183255.GD28039@diana.vm.bytemark.co.uk","subject":"Re: [PATCH] Document patch syntax.","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2007-05-12T19:02:24Z","receivedAt":"2007-05-12T19:02:24Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Karl Hasselström <kha@treskal.com> writes:\n\n> On 2007-05-12 16:38:27 +0200, Yann Dirson wrote:\n>\n>> However, that makes me think we should probably use guideline for\n>> the docs - here comes the question of which convention to use when\n>> refering to the user. Do we address her directly (\"you\"), indirectly\n>> (\"the user\", \"her\" - don't remember where the \"female user\" use\n>> comes from, but we could maybe follow this), even more indirectly\n>> (\"one\"), or any other way ?\n>\n> I'd go with \"you\", or possibly \"one\" (but I strongly prefer \"you\").\n> Talking about the user in the third person (\"the user\", \"her\", etc.)\n> seems actively wrong when we are instructing the user on how to do\n> things.\n\nWith the context in question, I find 'the user' is the most\nnatural and neutral.\n\nI think the \"female user\" use is not so widely accepted.  I\nalways found it to be a sign that the author, a lonely male nerd\ndeveloper, is wishing to live in a dream world where he becomes\na hero by helping an attractive female user that he would never\nhave chance to interact with otherwise in his real life ;-).\n\nFor tutorial/walkthru type of documentation, my usual preference\nis \"we\", not \"you\".  \"Now our little repository should be in\nthis shape.\"  \"Let's change our Makefile to do a bit more.\"\nThat sets the tone that a slightly more knowledgeable friend is\nhelping the user by working together with him, instead of an\nexpert talking to a stupid user from a high place, but that is a\nbit offtopic.\n"},{"id":"42005","messageId":"20070513082710.GA12712@coredump.intra.peff.net","threadId":"8107","inReplyTo":"20070512143827.GE16903@nan92-1-81-57-214-146.fbx.proxad.net","subject":"Re: [PATCH] Document patch syntax.","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2007-05-13T08:27:10Z","receivedAt":"2007-05-13T08:27:10Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sat, May 12, 2007 at 04:38:27PM +0200, Yann Dirson wrote:\n\n> > > +Patches in the stack are identified with a short name, which must be\n> > > +unique in the stack.\n> > s/a short name/short names/, maybe.\n> Hm, not sure how that would play with the end of the sentence - any\n> native english speaker with an opinion ?\n\nKarl's version is more correct (but your version might be used by many\nnative speakers). The second half of the sentence is correct because\n'must' conjugates the same for singular and plural use; however, it\nmight be more clear to say \"...short name, each of which must be unique\nin the stack.\"\n\n> No strong opinion here.  However, that makes me think we should\n> probably use guideline for the docs - here comes the question of which\n> convention to use when refering to the user.  Do we address her\n> directly (\"you\"), indirectly (\"the user\", \"her\" - don't remember where\n> the \"female user\" use comes from, but we could maybe follow this),\n> even more indirectly (\"one\"), or any other way ?\n\nMost of the git docs already use direct address (just grep for 'you' in\nDocumentation). It's less formal, but it tends to read much more easily.\n\n-Peff\n"},{"id":"42006","messageId":"20070513082850.GB12712@coredump.intra.peff.net","threadId":"8107","inReplyTo":"7vodkpzwzj.fsf@assigned-by-dhcp.cox.net","subject":"Re: [PATCH] Document patch syntax.","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2007-05-13T08:28:50Z","receivedAt":"2007-05-13T08:28:50Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sat, May 12, 2007 at 12:02:24PM -0700, Junio C Hamano wrote:\n\n> For tutorial/walkthru type of documentation, my usual preference\n> is \"we\", not \"you\".  \"Now our little repository should be in\n> this shape.\"  \"Let's change our Makefile to do a bit more.\"\n> That sets the tone that a slightly more knowledgeable friend is\n> helping the user by working together with him, instead of an\n> expert talking to a stupid user from a high place, but that is a\n> bit offtopic.\n\nI like that, too, but I don't think \"we're\" following it very well. Try\ngrepping through git/Documentation.\n\n-Peff\n"}]}