Documentation Directions

Documentation Directions

[Jon Loeliger]

Couple of questions regarding documentation direction:

- Is the plan to update all docs to use $GIT_DIR instead of .git?

- Do we intend on adding explicit support for '--help' on most,
  if not all, of the git commands?  In some cases (git-branch)
  a -*) case tacitly catches --help and usage()'s it.  In other
  cases (git-pull) this can't be done as -*) passes options
  on to git-fetch.  I think that we should catch --help directly
  so that it doesn't emit git-fetch's *) catch-all usage:

    % git pull --help
    usage: git-fetch-pack [-q] [-v] [--exec=upload-pack] [host:]directory <refs>...
    Fetch failure: --help

- Do you want to head in the per-man-page-"Now What?" direction
  as suggested by Junio?

Thanks,
jdl

Re: Documentation Directions

[Jon Loeliger]

Also:

    - Do you want to standardize on using a '$' prompt
      for all the example command executions samples?
      Like so:

          Do do the thing, run the command:

                $ git-frobnicate --weirdly

Do you/we care?  Consistency uber alles?

Thanks,
jdl

Re: Documentation Directions

[Junio C Hamano]

Jon Loeliger <jdl@freescale.com> writes:

> Couple of questions regarding documentation direction:
>
> - Is the plan to update all docs to use $GIT_DIR instead of .git?

I personally feel we should use less (not more) $GIT_DIR in the
documentation and casual mention of things under .git/ directory
should say .git/ instead, with the understanding that the reader
have already learned that there is a way to override it if the
user chooses to do so.

> - Do we intend on adding explicit support for '--help' on most,
>   if not all, of the git commands?

I think that would be very helpful.

>     - Do you want to standardize on using a '$' prompt
>       for all the example command executions samples?

Ah, I see you recently added a couple of Csh style '%' prompt.
Also I suspect that some examples in earlier tutorial do not
even have any prompt.

You are right -- being consistent would be nice.

Re: Documentation Directions

[Nikolai Weibull]

Jon Loeliger wrote:

> - Is the plan to update all docs to use $GIT_DIR instead of .git?

Well, shouldn't we go all the way and use ${GIT_DIR:-.git} then?  :-)

        nikolai

-- 
Nikolai Weibull: now available free of charge at http://bitwi.se/!
Born in Chicago, IL USA; currently residing in Gothenburg, Sweden.
main(){printf(&linux["\021%six\012\0"],(linux)["have"]+"fun"-97);}