[PATCH] Document patch syntax.

[PATCH] Document patch syntax.

[Yann Dirson]

Signed-off-by: Yann Dirson <ydirson@altern.org>
---

 Documentation/stg.txt |   25 +++++++++++++++++++++++++
 1 files changed, 25 insertions(+), 0 deletions(-)

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
 -------
 

Re: [PATCH] Document patch syntax.

[Karl Hasselström]

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

Re: [PATCH] Document patch syntax.

[Yann Dirson]

On Sat, May 12, 2007 at 03:56:44PM +0200, Karl Hasselström wrote:
> 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 ?


> > +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.

Re: [PATCH] Document patch syntax.

[Karl Hasselström]

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.

-- 
Karl Hasselström, kha@treskal.com
      www.treskal.com/kalle

Re: [PATCH] Document patch syntax.

[Junio C Hamano]

Karl Hasselström <kha@treskal.com> writes:

> 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.

Re: [PATCH] Document patch syntax.

[Jeff King]

On Sat, May 12, 2007 at 12:02:24PM -0700, Junio C Hamano wrote:

> 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

Re: [PATCH] Document patch syntax.

[Jeff King]

On Sat, May 12, 2007 at 04:38:27PM +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 ?

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."

> 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