threads / discuss / 2366

Documentation Directions

Subject: Documentation Directions

## tl;dr

3 messages between Nov 6, 2005 and Nov 6, 2005.

replies: 2people: 3as markdown or json

Jon Loeliger· Nov 6, 2005, 17:35 UTC · lore

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

Junio C Hamano· Nov 6, 2005, 20:11 UTC · re: Jon Loeliger · lore

Re: Documentation Directions

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.

Nikolai Weibull· Nov 6, 2005, 22:03 UTC · re: Jon Loeliger · lore

Re: Documentation Directions

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);}