[PATCH v2 0/4] Documentation style fixes
From: Thomas Rast <hidden>
Date: 2016-06-15 22:47:59
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 [off-list ref] writes:quoted
* 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(-)