Re: checkout extra files

[Jeff King <peff@peff.net>]

On Mon, Sep 10, 2012 at 10:09:43AM -0700, Junio C Hamano wrote:

> > Does it make sense to join that final paragraph into what is now the
> > third bullet, and then add your new text (the fourth bullet) after?
> 
> I am not sure.  After re-reading it, I do not think the fileglob
> discussion belongs to the existing "Here are the rules" list in the
> first place.

I had a vague feeling that it did not quite belong, too, but I was not
sure where it should go.

> It should probably be the extended description for the
> first point (revisions then paths) to explain what kind of "paths"
> we accept there.

I do not think so. That point is about the order of revisions and paths,
and has nothing to do with the syntax of paths. Really, every element of
that list is about handling revisions versus paths. I think this content
does not necessarily go in such a list.

> I generally consider follow-up paragraphs after bulleted list to be
> enhancements on any of the points in the list, not necessarily
> applying to all of them.

I would argue the opposite; if it is about a specific point, then put it
with the point. Otherwise, you are asking the reader to remember back to
an earlier point (that they may not even have read; in reference
documentation, the point of a list is often to let readers skip from
bullet to bullet easily).

If it is a synthesis of multiple elements in the list, then that makes
more sense. And I think that is what you are implying here:

> The existing structure is:
> 
>     * point A (revisions and paths)
>     * point B (-- can be used to disambiguate)
>     * point C (ambiguation leads to an error)
> 
>     Note that point B and point C taken together imply corollary BC.

Which is fine by me. But inserting a point D that is not related to B,
C, or BC, only makes it harder to read.

> So perhaps something like this squashed in on top of the patch in
> question?
> 
>  Documentation/gitcli.txt | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git c/Documentation/gitcli.txt w/Documentation/gitcli.txt
> index c70cd81..4413489 100644
> --- c/Documentation/gitcli.txt
> +++ w/Documentation/gitcli.txt
> @@ -38,9 +38,9 @@ arguments.  Here are the rules:
>     you have to say either `git diff HEAD --` or `git diff -- HEAD` to
>     disambiguate.
>  
> - * Many commands allow wildcards in paths, but you need to protect
> -   them from getting globbed by the shell.  These two mean different
> -   things:
> +Many commands allow wildcards in paths (see pathspec in
> +linkgit:gitglossary[7]), but you need to protect them
> +from getting globbed by the shell.  These two mean different things:
>  +
>  --------------------------------
>  $ git checkout -- *.c

I don't think that makes it any better. You went from:

  * A
  * B
  * C
  * D

  By the way, B and C imply BC.

to:

  * A
  * B
  * C

  By the way, D.

  Also, B and C imply BC.

I think it would make more sense to do:

  * A
  * B
  * C

  By the way, B and C imply BC.

  Also, D.

(where obviously my "connecting" phrases do not need to be part of the
text, but are meant to illustrate how I am thinking about the
structure).

-Peff