delta/git.git/Documentation/git-show.txt, branch pb/commit-editmsg-path

doc: convert \--option to --option

2015-05-13T05:14:46+00:00

Older versions of AsciiDoc would convert the "--" in
"--option" into an emdash. According to 565e135
(Documentation: quote double-dash for AsciiDoc, 2011-06-29),
this is fixed in AsciiDoc 8.3.0. According to bf17126, we
don't support anything older than 8.4.1 anyway, so we no
longer need to worry about quoting.

Even though this does not change the output at all, there
are a few good reasons to drop the quoting:

  1. It makes the source prettier to read.

  2. We don't quote consistently, which may be confusing when
     reading the source.

  3. Asciidoctor does not like the quoting, and renders a
     literal backslash.

Signed-off-by: Jeff King 
Signed-off-by: Junio C Hamano

Documentation/git-show.txt: include common diff options, like git-log.txt

2013-07-18T00:50:56+00:00

Signed-off-by: Matthieu Moy 
Reviewed-by: Jonathan Nieder 
Signed-off-by: Junio C Hamano

docs: stop using asciidoc no-inline-literal

2012-04-26T20:19:06+00:00

In asciidoc 7, backticks like `foo` produced a typographic
effect, but did not otherwise affect the syntax. In asciidoc
8, backticks introduce an "inline literal" inside which markup
is not interpreted. To keep compatibility with existing
documents, asciidoc 8 has a "no-inline-literal" attribute to
keep the old behavior. We enabled this so that the
documentation could be built on either version.

It has been several years now, and asciidoc 7 is no longer
in wide use. We can now decide whether or not we want
inline literals on their own merits, which are:

  1. The source is much easier to read when the literal
     contains punctuation. You can use `master~1` instead
     of `master{tilde}1`.

  2. They are less error-prone. Because of point (1), we
     tend to make mistakes and forget the extra layer of
     quoting.

This patch removes the no-inline-literal attribute from the
Makefile and converts every use of backticks in the
documentation to an inline literal (they must be cleaned up,
or the example above would literally show "{tilde}" in the
output).

Problematic sites were found by grepping for '`.*[{\\]' and
examined and fixed manually. The results were then verified
by comparing the output of "html2text" on the set of
generated html pages. Doing so revealed that in addition to
making the source more readable, this patch fixes several
formatting bugs:

  - HTML rendering used the ellipsis character instead of
    literal "..." in code examples (like "git log A...B")

  - some code examples used the right-arrow character
    instead of '->' because they failed to quote

  - api-config.txt did not quote tilde, and the resulting
    HTML contained a bogus snippet like:

       foo bar

    which caused some parsers to choke and omit whole
    sections of the page.

  - git-commit.txt confused ``foo`` (backticks inside a
    literal) with ``foo'' (matched double-quotes)

  - mentions of `A U Thor ` used to
    erroneously auto-generate a mailto footnote for
    author@example.com

  - the description of --word-diff=plain incorrectly showed
    the output as "[-removed-] and {added}", not "{+added+}".

  - using "prime" notation like:

      commit `C` and its replacement `C'`

    confused asciidoc into thinking that everything between
    the first backtick and the final apostrophe were meant
    to be inside matched quotes

  - asciidoc got confused by the escaping of some of our
    asterisks. In particular,

      `credential.\*` and `credential..\*`

    properly escaped the asterisk in the first case, but
    literally passed through the backslash in the second
    case.

Signed-off-by: Jeff King 
Signed-off-by: Junio C Hamano

docs: put listed example commands in backticks

2011-08-04T22:49:13+00:00

Many examples of git command invocation are given in asciidoc listing
blocks, which makes them monospaced and avoids further interpretation of
special characters.  Some manpages make a list of examples, like:

  git foo::
    Run git foo.

  git foo -q::
    Use the "-q" option.

to quickly show many variants. However, they can sometimes be hard to
read, because they are shown in a proportional-width font (so, for
example, seeing the difference between "-- foo" and "--foo" can be
difficult).

This patch puts all such examples into backticks, which gives the
equivalent formatting to a listing block (i.e., monospaced and without
character interpretation).

As a bonus, this also fixes an example in the git-push manpage, in which
"git push origin :::" was accidentally considered a newly-indented list,
and not a list item with "git push origin :" in it.

Signed-off-by: Jeff King 
Signed-off-by: Junio C Hamano

Documentation: use [verse] for SYNOPSIS sections

2011-07-06T21:26:26+00:00

The SYNOPSIS sections of most commands that span several lines already
use [verse] to retain line breaks. Most commands that don't span
several lines seem not to use [verse]. In the HTML output, [verse]
does not only preserve line breaks, but also makes the section
indented, which causes a slight inconsistency between commands that
use [verse] and those that don't. Use [verse] in all SYNOPSIS sections
for consistency.

Also remove the blank lines from git-fetch.txt and git-rebase.txt to
align with the other man pages. In the case of git-rebase.txt, which
already uses [verse], the blank line makes the [verse] not apply to
the last line, so removing the blank line also makes the formatting
within the document more consistent.

While at it, add single quotes to 'git cvsimport' for consistency with
other commands.

Signed-off-by: Martin von Zweigbergk 
Signed-off-by: Junio C Hamano

doc: drop author/documentation sections from most pages

2011-03-11T15:59:16+00:00

The point of these sections is generally to:

  1. Give credit where it is due.

  2. Give the reader an idea of where to ask questions or
     file bug reports.

But they don't do a good job of either case. For (1), they
are out of date and incomplete. A much more accurate answer
can be gotten through shortlog or blame.  For (2), the
correct contact point is generally git@vger, and even if you
wanted to cc the contact point, the out-of-date and
incomplete fields mean you're likely sending to somebody
useless.

So let's drop the fields entirely from all manpages except
git(1) itself. We already point people to the mailing list
for bug reports there, and we can update the Authors section
to give credit to the major contributors and point to
shortlog and blame for more information.

Each page has a "This is part of git" footer, so people can
follow that to the main git manpage.

Documentation: document show -s

2010-11-09T17:42:57+00:00

Git's diff machinery has supported a -s (silence diff output) option
as far back as v0.99~900 (Silent flag for show-diff, 2005-04-13), but
the option is only advertised in an odd corner of the git diff-tree
manual.

The main use is to retrieve basic metadata about a commit:

	git show -s rev

Explain this in the 'git log' manual and provide an example in the
'git show' examples section.  This is kind of a cop-out, since it
would be more useful to explain it in the 'git show' manual proper,
which says:

	The command takes options applicable to the git
	diff-tree command to control how the changes the
	commit introduces are shown.

	This manual page describes only the most frequently
	used options.

Fixing that is a larger task for another day.

Reported-by: Will Hall 
Signed-off-by: Jonathan Nieder 
Signed-off-by: Junio C Hamano

Documentation: gitrevisions is in section 7

2010-10-14T02:10:55+00:00

Fix references to gitrevisions(1) in the manual pages and HTML
documentation.

In practice, this will not matter much unless someone tries to use a
hard copy of the git reference manual.

Signed-off-by: Jonathan Nieder 
Signed-off-by: Junio C Hamano

Documentation: link to gitrevisions rather than git-rev-parse

2010-07-05T20:39:13+00:00

Currently, whenever we need documentation for revisions and ranges, we
link to the git-rev-parse man page, i.e. a plumbing man page, which has
this along with the documentation of all rev-parse modes.

Link to the new gitrevisions man page instead in all cases except
- when the actual git-rev-parse command is referred to or
- in very technical context (git-send-pack).

Signed-off-by: Michael J Gruber 
Signed-off-by: Junio C Hamano

Documentation: spell 'git cmd' without dash throughout

2010-01-10T12:01:28+00:00

The documentation was quite inconsistent when spelling 'git cmd' if it
only refers to the program, not to some specific invocation syntax:
both 'git-cmd' and 'git cmd' spellings exist.

The current trend goes towards dashless forms, and there is precedent
in 647ac70 (git-svn.txt: stop using dash-form of commands.,
2009-07-07) to actively eliminate the dashed variants.

Replace 'git-cmd' with 'git cmd' throughout, except where git-shell,
git-cvsserver, git-upload-pack, git-receive-pack, and
git-upload-archive are concerned, because those really live in the
$PATH.