From: Nikolai Weibull <mailing-lists.git@rawuncut.elitemail.org>
Date: Tue, 06 Dec 2005 22:12:52 GMT
Subject: A list of things missing or wrong in the documentation
Message-ID: <20051206221252.GA8839@puritan.petwork>

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