[PATCH v2 0/4] Documentation style fixes

[Thomas Rast <trast@student.ethz.ch>]

I'm violating the midnight rule, so there's probably something wrong
with this series.

Junio C Hamano wrote:
> I am tempted to suggest describing the command in terms of more common use
> pattern, describing the flexible and more general form as "an aside" for
> more advanced users, perhaps like this.
> 
>         <branch>...:
>                 Other branch to merge into the current branch...trying an
>                 Octopus merge.
>         +
>         Strictly speaking, these can name arbitrary commits, not necessarily
>         at the tip of branches.  e.g. "git merge topic{tilde}4" lets you merge
>         the topic except for the last 4 commits.
> 
> I don't know if such an arrangement really makes the document more
> approachable to new people, or it is making the description longer and
> more complicated without helping new people, though (that is why this is
> just "I am tempted to").

Not sure.  I have a bit of an aversion against "lying" in the
synopsis, even though the common use-case really is a branch.

> Thomas Rast <trast@student.ethz.ch> writes:
> > * More importantly, while `code` style seems to be an improvement in
> >   HTML output (because it gives typewriter font), my local 'man'
> >   renders 'emphasis' as underlines -- which actually makes the code
> >   snippets much more visible than `literal` quotes which are not
> >   rendered specially at all.
> >
> > So which way should it be changed?
> 
> I'd prefer to see us mark code as `code`.

I tried to make it so, including a few other places that grep found.

Regarding 'git-cmd' vs. 'git cmd', I found that we're in the somewhat
unsatisfactory situation where the git-svn manpage uses dashless since
647ac70 (git-svn.txt: stop using dash-form of commands., 2009-07-07).
Most of the rest uses dashed, but there sometimes even were
inconsistent uses very close to each other.  Dashless seems to be a
bit more common in newer patches, and does have the advantage that it
does not need an exception for 'git submodule update' and friends.

So I tried to sed it towards the dashless form, with a few exceptions.
The churn, of course, is rather daunting.  The other alternative,
returning to dashed forms, would mean reverting 647ac70 and then more
applications of sed to fix the stray dashless uses, being careful to
preserve the SYNOPSIS sections.


Thomas Rast (4):
  Documentation/git-merge: reword references to "remote" and "pull"
  Documentation: warn prominently against merging with dirty trees
  Documentation: format full commands in typewriter font
  Documentation: spell 'git cmd' without dash throughout

 Documentation/config.txt                |   70 +++++++-------
 Documentation/fetch-options.txt         |   10 +-
 Documentation/git-add.txt               |    2 +-
 Documentation/git-am.txt                |   10 +-
 Documentation/git-apply.txt             |   10 +-
 Documentation/git-archimport.txt        |   12 ++--
 Documentation/git-archive.txt           |    2 +-
 Documentation/git-bisect.txt            |    2 +-
 Documentation/git-blame.txt             |    8 +-
 Documentation/git-branch.txt            |    6 +-
 Documentation/git-bundle.txt            |   26 +++---
 Documentation/git-check-ref-format.txt  |    2 +-
 Documentation/git-checkout-index.txt    |    8 +-
 Documentation/git-cherry-pick.txt       |    2 +-
 Documentation/git-cherry.txt            |    6 +-
 Documentation/git-citool.txt            |    4 +-
 Documentation/git-clean.txt             |    4 +-
 Documentation/git-commit-tree.txt       |    2 +-
 Documentation/git-commit.txt            |   18 ++--
 Documentation/git-config.txt            |   14 ++--
 Documentation/git-cvsexportcommit.txt   |    2 +-
 Documentation/git-cvsimport.txt         |   18 ++--
 Documentation/git-cvsserver.txt         |    6 +-
 Documentation/git-daemon.txt            |   40 ++++----
 Documentation/git-describe.txt          |    6 +-
 Documentation/git-diff-files.txt        |    2 +-
 Documentation/git-diff-index.txt        |   16 ++--
 Documentation/git-diff-tree.txt         |    4 +-
 Documentation/git-difftool.txt          |   16 ++--
 Documentation/git-fast-export.txt       |   12 ++--
 Documentation/git-fast-import.txt       |   20 ++--
 Documentation/git-fetch-pack.txt        |    6 +-
 Documentation/git-fetch.txt             |    2 +-
 Documentation/git-filter-branch.txt     |   24 +++---
 Documentation/git-fmt-merge-msg.txt     |    2 +-
 Documentation/git-format-patch.txt      |    4 +-
 Documentation/git-fsck.txt              |    4 +-
 Documentation/git-gc.txt                |   18 ++--
 Documentation/git-get-tar-commit-id.txt |    4 +-
 Documentation/git-grep.txt              |    2 +-
 Documentation/git-gui.txt               |   20 ++--
 Documentation/git-hash-object.txt       |    2 +-
 Documentation/git-help.txt              |    6 +-
 Documentation/git-http-backend.txt      |   22 +++---
 Documentation/git-http-fetch.txt        |    2 +-
 Documentation/git-imap-send.txt         |    2 +-
 Documentation/git-index-pack.txt        |    8 +-
 Documentation/git-init.txt              |    6 +-
 Documentation/git-log.txt               |    2 +-
 Documentation/git-ls-files.txt          |    4 +-
 Documentation/git-ls-tree.txt           |    4 +-
 Documentation/git-mailinfo.txt          |    2 +-
 Documentation/git-merge-file.txt        |   10 +-
 Documentation/git-merge-index.txt       |    6 +-
 Documentation/git-merge-one-file.txt    |    2 +-
 Documentation/git-merge.txt             |   54 ++++++-----
 Documentation/git-mergetool.txt         |   16 ++--
 Documentation/git-name-rev.txt          |    4 +-
 Documentation/git-notes.txt             |    2 +-
 Documentation/git-pack-objects.txt      |    6 +-
 Documentation/git-pack-redundant.txt    |    2 +-
 Documentation/git-patch-id.txt          |    2 +-
 Documentation/git-peek-remote.txt       |    2 +-
 Documentation/git-prune.txt             |   14 ++--
 Documentation/git-pull.txt              |   14 ++-
 Documentation/git-push.txt              |    6 +-
 Documentation/git-read-tree.txt         |   40 ++++----
 Documentation/git-rebase.txt            |   38 ++++----
 Documentation/git-receive-pack.txt      |    6 +-
 Documentation/git-reflog.txt            |    2 +-
 Documentation/git-remote.txt            |    2 +-
 Documentation/git-repack.txt            |   10 +-
 Documentation/git-replace.txt           |    2 +-
 Documentation/git-rerere.txt            |   26 +++---
 Documentation/git-reset.txt             |    2 +-
 Documentation/git-rev-list.txt          |    6 +-
 Documentation/git-rev-parse.txt         |   30 +++---
 Documentation/git-revert.txt            |    8 +-
 Documentation/git-send-pack.txt         |    4 +-
 Documentation/git-sh-setup.txt          |    2 +-
 Documentation/git-shortlog.txt          |    4 +-
 Documentation/git-show-index.txt        |    2 +-
 Documentation/git-show-ref.txt          |    4 +-
 Documentation/git-show.txt              |    4 +-
 Documentation/git-stash.txt             |    8 +-
 Documentation/git-status.txt            |    2 +-
 Documentation/git-submodule.txt         |    8 +-
 Documentation/git-symbolic-ref.txt      |    2 +-
 Documentation/git-tag.txt               |    6 +-
 Documentation/git-tar-tree.txt          |    4 +-
 Documentation/git-update-index.txt      |   14 ++--
 Documentation/git-upload-archive.txt    |    2 +-
 Documentation/git-upload-pack.txt       |    8 +-
 Documentation/git-var.txt               |    2 +-
 Documentation/git-verify-pack.txt       |    2 +-
 Documentation/git-verify-tag.txt        |    2 +-
 Documentation/git-web--browse.txt       |    2 +-
 Documentation/git-whatchanged.txt       |    4 +-
 Documentation/git-write-tree.txt        |    8 +-
 Documentation/git.txt                   |    8 +-
 Documentation/gitattributes.txt         |   12 ++--
 Documentation/gitcore-tutorial.txt      |  148 +++++++++++++++---------------
 Documentation/gitcvs-migration.txt      |   10 +-
 Documentation/gitdiffcore.txt           |    8 +-
 Documentation/githooks.txt              |   56 ++++++------
 Documentation/gitignore.txt             |    4 +-
 Documentation/gitk.txt                  |    2 +-
 Documentation/gitrepository-layout.txt  |   16 ++--
 Documentation/gittutorial-2.txt         |   16 ++--
 Documentation/gittutorial.txt           |   42 +++++-----
 Documentation/gitworkflows.txt          |    6 +-
 Documentation/i18n.txt                  |    4 +-
 Documentation/merge-options.txt         |    4 +-
 Documentation/pull-fetch-param.txt      |    8 +-
 Documentation/urls-remotes.txt          |    4 +-
 115 files changed, 634 insertions(+), 626 deletions(-)