threads / discuss / 2759

A list of things missing or wrong in the documentation

Subject: A list of things missing or wrong in the documentation

## tl;dr

One message between Dec 6, 2005 and Dec 6, 2005.

replies: 0people: 1as markdown or json

Nikolai Weibull· Dec 6, 2005, 22:12 UTC · lore

Here's a list of things that are missing, wrong, or badly formatted in the documentation (all checked against the man pages):

git-checkout-index:
        SYNOPSIS:
                --index
                --quiet
                --force
                --all
                --no-create
                (How do we put these in the SYNOPSIS?)
                (My bad, forgot to mention this in an earlier patch.)
git-read-tree:
        --trivial
        SYNOPSIS:
                --reset
git-update-index:
        -h
        --help
        (perhaps redundant)
git-rev-list:
        --dense
        --no-merges
git-merge-base:
        -a, --all
git-verify-pack:
        --
git-http-fetch:
        commit-id and url are missing descriptions
git-update-server-info:
        -f
git-am:
        --utf8 is converted to -u
        --keep is converted to -k
git-bisect:
        Documentation is messed up.  Lines are being joined when they
        shouldn't be (put "+ " at end of line).
git-cherry-pick:
        --no-commit
        --replay
git-clone:
        SYNOPSIS:
                --local
                --shared
                --quiet
                --upload-pack
git-commit:
        --all
        --signoff
        --verify
        --no-verify
        --edit
        -n
git-diff:
        --diff-options should be <common diff options>
        The table isn't rendered properly in the man-page.  I'm guessing
        that this is a problem with my DocBook templates, but I wanted
        to check if anyone else has this issue.
git-format-patch:
        SYNOPSIS:
                provide spacing around options, like other man-pages
        --keep-subject
        --numbered
        --output-directory
        -h --help
        -m
        -d
git-ls-remote:
        -h
        -t
        
git-pull:
        --strategy
git-repack:
        -n
        -l
git-revert:
        --no-commit
        -r --replay
git-show-branch:
        --topo-order
git-cvsimport:
        error in spacing (-P)
git-prune:
        --
git-tag:
        doesn't follow the format of the other manual pages
        missing explicit documentation for many options
General:
        The term "commit-id" isn't listed in the glossary.  Should this
        be changed to "commit" instead?
        Style guides generally suggest putting a comma after "e.g." and
        "i.e.", i.e., "e.g.," and "i.e.,".  It's perhaps a bit anal, but
        what do you think?
        rev is used as a term in some places.  Should perhaps expand it
        to revision?

I should of course provide patches for this, but I'm quite a bit under the weather at the moment, and as a 1.0.0 release draws near I figured that it'd be best that people at least know what I know so that they may do something about it. (Also, someone with better knowledge of asciidoc and git itself would probably do a better job than I could.)

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

← back to recent threads