kernel/git - git - PowerEL Git System

Commit Graph

Author	SHA1	Message	Date
Jeff King	6cf378f0cb	docs: stop using asciidoc no-inline-literal 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: <tt><sub></tt> foo <tt></sub>bar</tt> 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 <author@example.com>` 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.<url>.\*` properly escaped the asterisk in the first case, but literally passed through the backslash in the second case. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>	13 years ago
Jeff King	5d2fc9135a	docs: put listed example commands in backticks 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 <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>	13 years ago
Martin von Zweigbergk	7791a1d9b9	Documentation: use [verse] for SYNOPSIS sections 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 <martin.von.zweigbergk@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	14 years ago
Jeff King	48bb914ed6	doc: drop author/documentation sections from most pages 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.	14 years ago
Jonathan Nieder	60aa9cf8f3	Documentation: document show -s 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 <will@gnatter.net> Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	14 years ago
Jonathan Nieder	9d83e3827f	Documentation: gitrevisions is in section 7 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 <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	14 years ago
Michael J Gruber	f028cdae66	Documentation: link to gitrevisions rather than git-rev-parse 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 <git@drmicha.warpmail.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>	15 years ago
Thomas Rast	0b444cdb19	Documentation: spell 'git cmd' without dash throughout 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.	15 years ago
Junio C Hamano	1ceb95c804	Update my e-mail address The old cox.net address is still getting mails from gitters. Signed-off-by: Junio C Hamano <gitster@pobox.com>	16 years ago
Abhijit Menon-Sen	f448e24e2f	Make the DESCRIPTION match <x>... items in the SYNOPSIS When the SYNOPSIS says e.g. "<path>...", it is nice if the DESCRIPTION also mentions "<path>..." and says the specified "paths" (note plural) are used for $whatever. This fixes the obvious mismatches. Signed-off-by: Abhijit Menon-Sen <ams@toroid.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>	17 years ago
Junio C Hamano	59eb68aa2b	Update my e-mail address The old cox.net address is still getting mails from gitters. Signed-off-by: Junio C Hamano <gitster@pobox.com>	17 years ago
Jonathan Nieder	ba020ef5eb	manpages: italicize git command names (which were in teletype font) The names of git commands are not meant to be entered at the commandline; they are just names. So we render them in italics, as is usual for command names in manpages. Using doit () { perl -e 'for (<>) { s/\`(git-[^\`.])\`/'\''\1'\''/g; print }' } for i in git.txt config.txt diff.txt blame.txt fetch.txt i18n.txt \ merge.txt pretty.txt pull.txt rev.txt urls.txt do doit <"$i" >"$i+" && mv "$i+" "$i" done git diff . Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>	17 years ago
Jonathan Nieder	483bc4f045	Documentation formatting and cleanup Following what appears to be the predominant style, format names of commands and commandlines both as `teletype text`. While we're at it, add articles ("a" and "the") in some places, italicize the name of the command in the manual page synopsis line, and add a comma or two where it seems appropriate. Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>	17 years ago
Jonathan Nieder	b1889c36d8	Documentation: be consistent about "git-" versus "git " Since the git-* commands are not installed in $(bindir), using "git-command <parameters>" in examples in the documentation is not a good idea. On the other hand, it is nice to be able to refer to each command using one hyphenated word. (There is no escaping it, anyway: man page names cannot have spaces in them.) This patch retains the dash in naming an operation, command, program, process, or action. Complete command lines that can be entered at a shell (i.e., without options omitted) are made to use the dashless form. The changes consist only of replacing some spaces with hyphens and vice versa. After a "s/ /-/g", the unpatched and patched versions are identical. Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>	17 years ago
Christian Couder	9e1f0a85c6	documentation: move git(7) to git(1) As the "git" man page describes the "git" command at the end-user level, it seems better to move it to man section 1. Signed-off-by: Christian Couder <chriscool@tuxfamily.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>	17 years ago
Jon Loeliger	3a3e097b86	git-show.txt: Not very stubby these days. Signed-off-by: Jon Loeliger <jdl@freescale.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	17 years ago
Dan McGee	5162e69732	Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w\|-)?):(?P<target>\S?)(\[(?P<attrlist>.?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http\|https\|ftp\|file\|mailto\|callto\|image\|link)):(?P<target>\S?)(\[(?P<attrlist>.?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	17 years ago
Junio C Hamano	a6080a0a44	War on whitespace This uses "git-apply --whitespace=strip" to fix whitespace errors that have crept in to our source files over time. There are a few files that need to have trailing whitespaces (most notably, test vectors). The results still passes the test, and build result in Documentation/ area is unchanged. Signed-off-by: Junio C Hamano <gitster@pobox.com>	18 years ago
Jakub Narebski	331b51d240	Documentation: Split description of pretty formats of commit log Split description of pretty formats into list of pretty options (--pretty and --encoding) in new file Documentation/pretty-options.txt and description of formats itself as a separate "PRETTY FORMATS" section in pretty-formats.txt While at it correct formatting a bit, to be better laid out in the resulting manpages: git-rev-list(1), git-show(1), git-log(1) and git-diff-tree(1). Those manpages now include pretty options in the same place as it was before, and description of formats just after all options. Inspired by the split into two filesdocumentation for merge strategies: Documentation/merge-options.txt and Documentation/merge-strategies.txt Signed-off-by: Jakub Narebski <jnareb@gmail.com> Signed-off-by: Junio C Hamano <junkio@cox.net>	18 years ago
Theodore Tso	7ee70a7119	Fix git-show man page formatting in the EXAMPLES section Fix asciidoc markup so that the man page is properly formatted in the EXAMPLES section. Signed-off-by: "Theodore Ts'o" <tytso@mit.edu> Signed-off-by: Junio C Hamano <junkio@cox.net>	18 years ago
Michael S. Tsirkin	66e788bc7f	Update git-log and git-show documentation Point at where the options not so frequently used are found. Signed-off-by: Junio C Hamano <junkio@cox.net>	18 years ago
Shawn O. Pearce	41a5564e05	Refer users to git-rev-parse for revision specification syntax. The revision specification syntax (sometimes referred to as SHA1-expressions) is accepted almost everywhere in Git by almost every tool. Unfortunately it is only documented in git-rev-parse.txt, and most users don't know to look there. Signed-off-by: Shawn O. Pearce <spearce@spearce.org> Signed-off-by: Junio C Hamano <junkio@cox.net>	18 years ago
Junio C Hamano	99e09cce8d	Documentation: minor rewording for git-log and git-show pages. Signed-off-by: Junio C Hamano <junkio@cox.net>	18 years ago
Junio C Hamano	5dc7bcc245	Documentation: i18n commit log message notes. Signed-off-by: Junio C Hamano <junkio@cox.net>	18 years ago
Johannes Schindelin	5d7eeee2ac	git-show: grok blobs, trees and tags, too Since git-show is pure Porcelain, it is the ideal candidate to pretty print other things than commits, too. Signed-off-by: Johannes Schindelin <Johannes.Schindelin@gmx.de> Signed-off-by: Junio C Hamano <junkio@cox.net>	18 years ago
Chris Riddoch	5d1faf8791	Move --pretty options into Documentation/pretty-formats.txt Asciidoc-include it into the manuals for programs that use the --pretty command-line option, for consistency among the docs. This describes all the pretty-formats currently listed in the cmit_fmt enum in commit.h, and also briefly describes the presence and format of the 'Merge: ' line in some pretty formats. There's a hedge that limiting your view of history can affect what goes in the Merge: line, and that --abbrev/--no-abbrev do nothing to the 'raw' format. Signed-off-by: Chris Riddoch <chris@syntacticsugar.org> Signed-off-by: Junio C Hamano <junkio@cox.net>	18 years ago
Fredrik Kuivinen	7bd7f2804d	Remove trailing dot after short description Signed-off-by: Fredrik Kuivinen <freku045@student.liu.se> Signed-off-by: Junio C Hamano <junkio@cox.net>	19 years ago
Petr Baudis	4e783b41e0	Basic documentation for git-show Signed-off-by: Petr Baudis <pasky@suse.cz> Signed-off-by: Junio C Hamano <junkio@cox.net>	19 years ago

27 Commits (675a0fe297e88e0fab2ee9b311d4ebb3c3bfef28)