threads / patch / 8107

patchDocument patch syntax.

Subject: [PATCH] Document patch syntax.

## tl;dr

7 messages between May 12, 2007 and May 13, 2007. Diffs are folded; open one to read it.

replies: 6people: 4as markdown or json

Yann Dirson· May 12, 2007, 12:07 UTC · lore
Signed-off-by: Yann Dirson <ydirson@altern.org>
---
 Documentation/stg.txt |   25 +++++++++++++++++++++++++
 1 files changed, 25 insertions(+), 0 deletions(-)
Show changes to Documentation/stg.txt +25 −0
diff --git a/Documentation/stg.txt b/Documentation/stg.txt
index af57c37..3ea51c3 100644
--- a/Documentation/stg.txt
+++ b/Documentation/stg.txt
@@ -51,6 +51,31 @@ Development branch::
 In such a setup, not all commits on your branch need to be StGIT
 patches; there may be regular GIT commits below your stack base.
 
+Patches
+~~~~~~~
+
+Many StGIT commands take references to StGIT patches as arguments.
+Patches in the stack are identified with a short name, which must be
+unique in the stack.
+
+Patches in the current stack are just refered to by their name.  Some
+commands allow to specify a patch in another stack of the repository;
+this is done by suffixing the patch name with a '@' sign followed by the
+branch name (eg. 'thispatch@otherbranch').
+
+A number of position in the stack related to the patch are also
+accessible through '//' suffixes.  For example, 'patch//top'' is
+equivalent to 'patch', and 'patch//bottom' refers to the commit below
+'patch' (ie. the patch below, or the stack base if this is the
+bottom-most patch).  Similarly ''//top.old'' and ''//bottom.old''
+refer to the previous version of the patch (before the last
+stglink:push[] or stglink:refresh[] operation).  When refering to the
+current patch, its name can be omitted (eg. 'currentpatch//bottom.old'
+can be abbreviated as 'bottom.old').
+
+If you need to pass a given StGIT reference to a git command,
+stglink:id[] will convert it to a git commit id.
+
 OPTIONS
 -------
Karl Hasselström· May 12, 2007, 13:56 UTC · re: Yann Dirson · lore

Re: [PATCH] Document patch syntax.

On 2007-05-12 14:07:04 +0200, Yann Dirson wrote:
> +Patches in the stack are identified with a short name, which must be
> +unique in the stack.
s/a short name/short names/, maybe.
> +Patches in the current stack are just refered to by their name.  Some
> +commands allow to specify a patch in another stack of the repository;

s/allow to/allow you to/. Or "allows one to", but I prefer the second person here.

> +this is done by suffixing the patch name with a '@' sign followed by the
> +branch name (eg. 'thispatch@otherbranch').
s/a '@'/an '@'/; "'@'" begins with a vowel sound. :-)
> +A number of position in the stack related to the patch are also
s/position/positions/.
> +accessible through '//' suffixes.  For example, 'patch//top'' is
> +equivalent to 'patch', and 'patch//bottom' refers to the commit below
> +'patch' (ie. the patch below, or the stack base if this is the
s/ie./i.e./.
> +bottom-most patch).  Similarly ''//top.old'' and ''//bottom.old''

You use double quotes here, and single quotes above. What's the distinction?

> +refer to the previous version of the patch (before the last
> +stglink:push[] or stglink:refresh[] operation).  When refering to the
s/refering/referring/.
Otherwise,
Acked-by: Karl Hasselström <kha@treskal.com>
Yes, I'm too picky.
-- 
Karl Hasselström, kha@treskal.com
      www.treskal.com/kalle
Yann Dirson· May 12, 2007, 14:38 UTC · re: Karl Hasselström · lore

Re: [PATCH] Document patch syntax.

On Sat, May 12, 2007 at 03:56:44PM +0200, Karl Hasselström wrote:
Show 6 quoted lines
> On 2007-05-12 14:07:04 +0200, Yann Dirson wrote:
> 
> > +Patches in the stack are identified with a short name, which must be
> > +unique in the stack.
> 
> s/a short name/short names/, maybe.

Hm, not sure how that would play with the end of the sentence - any native english speaker with an opinion ?

Show 5 quoted lines
> > +Patches in the current stack are just refered to by their name.  Some
> > +commands allow to specify a patch in another stack of the repository;
> 
> s/allow to/allow you to/. Or "allows one to", but I prefer the second
> person here.

No strong opinion here. However, that makes me think we should probably use guideline for the docs - here comes the question of which convention to use when refering to the user. Do we address her directly ("you"), indirectly ("the user", "her" - don't remember where the "female user" use comes from, but we could maybe follow this), even more indirectly ("one"), or any other way ?

> s/a '@'/an '@'/; "'@'" begins with a vowel sound. :-)
> s/position/positions/.
> s/ie./i.e./.
> s/refering/referring/.
OK
> > +bottom-most patch).  Similarly ''//top.old'' and ''//bottom.old''
> 
> You use double quotes here, and single quotes above. What's the
> distinction?

Er... is "typo" a distinction ? :) Confusion induced by wiki markups, probably :(

> Yes, I'm too picky.
Not a problem, I tend to be quite picky too :)
Best regards,
-- 
Yann.
Karl Hasselström· May 12, 2007, 18:32 UTC · re: Yann Dirson · lore

Re: [PATCH] Document patch syntax.

On 2007-05-12 16:38:27 +0200, Yann Dirson wrote:
Show 6 quoted lines
> However, that makes me think we should probably use guideline for
> the docs - here comes the question of which convention to use when
> refering to the user. Do we address her directly ("you"), indirectly
> ("the user", "her" - don't remember where the "female user" use
> comes from, but we could maybe follow this), even more indirectly
> ("one"), or any other way ?

I'd go with "you", or possibly "one" (but I strongly prefer "you"). Talking about the user in the third person ("the user", "her", etc.) seems actively wrong when we are instructing the user on how to do things.

-- 
Karl Hasselström, kha@treskal.com
      www.treskal.com/kalle
Junio C Hamano· May 12, 2007, 19:02 UTC · re: Karl Hasselström · lore

Re: [PATCH] Document patch syntax.

Karl Hasselström <kha@treskal.com> writes:
Show 13 quoted lines
> On 2007-05-12 16:38:27 +0200, Yann Dirson wrote:
>
>> However, that makes me think we should probably use guideline for
>> the docs - here comes the question of which convention to use when
>> refering to the user. Do we address her directly ("you"), indirectly
>> ("the user", "her" - don't remember where the "female user" use
>> comes from, but we could maybe follow this), even more indirectly
>> ("one"), or any other way ?
>
> I'd go with "you", or possibly "one" (but I strongly prefer "you").
> Talking about the user in the third person ("the user", "her", etc.)
> seems actively wrong when we are instructing the user on how to do
> things.

With the context in question, I find 'the user' is the most natural and neutral.

I think the "female user" use is not so widely accepted. I always found it to be a sign that the author, a lonely male nerd developer, is wishing to live in a dream world where he becomes a hero by helping an attractive female user that he would never have chance to interact with otherwise in his real life ;-).

For tutorial/walkthru type of documentation, my usual preference is "we", not "you". "Now our little repository should be in this shape." "Let's change our Makefile to do a bit more." That sets the tone that a slightly more knowledgeable friend is helping the user by working together with him, instead of an expert talking to a stupid user from a high place, but that is a bit offtopic.

Jeff King· May 13, 2007, 08:28 UTC · re: Junio C Hamano · lore

Re: [PATCH] Document patch syntax.

On Sat, May 12, 2007 at 12:02:24PM -0700, Junio C Hamano wrote:
Show 7 quoted lines
> For tutorial/walkthru type of documentation, my usual preference
> is "we", not "you".  "Now our little repository should be in
> this shape."  "Let's change our Makefile to do a bit more."
> That sets the tone that a slightly more knowledgeable friend is
> helping the user by working together with him, instead of an
> expert talking to a stupid user from a high place, but that is a
> bit offtopic.

I like that, too, but I don't think "we're" following it very well. Try grepping through git/Documentation.

-Peff
Jeff King· May 13, 2007, 08:27 UTC · re: Yann Dirson · lore

Re: [PATCH] Document patch syntax.

On Sat, May 12, 2007 at 04:38:27PM +0200, Yann Dirson wrote:
Show 5 quoted lines
> > > +Patches in the stack are identified with a short name, which must be
> > > +unique in the stack.
> > s/a short name/short names/, maybe.
> Hm, not sure how that would play with the end of the sentence - any
> native english speaker with an opinion ?

Karl's version is more correct (but your version might be used by many native speakers). The second half of the sentence is correct because 'must' conjugates the same for singular and plural use; however, it might be more clear to say "...short name, each of which must be unique in the stack."

Show 6 quoted lines
> No strong opinion here.  However, that makes me think we should
> probably use guideline for the docs - here comes the question of which
> convention to use when refering to the user.  Do we address her
> directly ("you"), indirectly ("the user", "her" - don't remember where
> the "female user" use comes from, but we could maybe follow this),
> even more indirectly ("one"), or any other way ?

Most of the git docs already use direct address (just grep for 'you' in Documentation). It's less formal, but it tends to read much more easily.

-Peff

← back to recent threads