svn commit: r279519 - in head/contrib: diff/doc gperf/doc
Baptiste Daroussin
bapt at FreeBSD.org
Mon Mar 2 11:48:01 UTC 2015
Author: bapt
Date: Mon Mar 2 11:48:00 2015
New Revision: 279519
URL: https://svnweb.freebsd.org/changeset/base/279519
Log:
Convert texinfo to mdoc(7) using texi2mdoc
Added:
head/contrib/diff/doc/diff.7 (contents, props changed)
head/contrib/gperf/doc/gperf.7 (contents, props changed)
Added: head/contrib/diff/doc/diff.7
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ head/contrib/diff/doc/diff.7 Mon Mar 2 11:48:00 2015 (r279519)
@@ -0,0 +1,6287 @@
+.Dd 2015-03-02
+.Dt DIFF 7
+.Os
+.Sh NAME
+.Nm diff
+.Nd Comparing and Merging Files
+.Sh Comparing and Merging Files
+.Sh Overview
+Computer users often find occasion to ask how two files differ. Perhaps one
+file is a newer version of the other file. Or maybe the two files started
+out as identical copies but were changed by different people.
+.Pp
+You can use the
+.Xr diff
+command to show differences between two files, or each corresponding file
+in two directories.
+.Xr diff
+outputs differences between files line by line in any of several formats,
+selectable by command line options. This set of differences is often called
+a
+.Em diff
+or
+.Em patch .
+For files that are identical,
+.Xr diff
+normally produces no output; for binary (non-text) files,
+.Xr diff
+normally reports only that they are different.
+.Pp
+You can use the
+.Xr cmp
+command to show the byte and line numbers where two files differ.
+.Xr cmp
+can also show all the bytes that differ between the two files, side by side.
+A way to compare two files character by character is the Emacs command
+.Li M-x compare-windows .
+See Section.Dq Other Window ,
+for more information on that command.
+.Pp
+You can use the
+.Xr diff3
+command to show differences among three files. When two people have made independent
+changes to a common original,
+.Xr diff3
+can report the differences between the original and the two changed versions,
+and can produce a merged file that contains both persons' changes together
+with warnings about conflicts.
+.Pp
+You can use the
+.Xr sdiff
+command to merge two files interactively.
+.Pp
+You can use the set of differences produced by
+.Xr diff
+to distribute updates to text files (such as program source code) to other
+people. This method is especially useful when the differences are small compared
+to the complete files. Given
+.Xr diff
+output, you can use the
+.Xr patch
+program to update, or
+.Em patch ,
+a copy of the file. If you think of
+.Xr diff
+as subtracting one file from another to produce their difference, you can
+think of
+.Xr patch
+as adding the difference to one file to reproduce the other.
+.Pp
+This manual first concentrates on making diffs, and later shows how to use
+diffs to update files.
+.Pp
+GNU
+.Xr diff
+was written by Paul Eggert, Mike Haertel, David Hayes, Richard Stallman, and
+Len Tower. Wayne Davison designed and implemented the unified output format.
+The basic algorithm is described by Eugene W. Myers in \(lqAn O(ND) Difference
+Algorithm and its Variations\(rq,
+.Em Algorithmica
+Vol. 1 No. 2, 1986, pp. 251--266; and in \(lqA File Comparison Program\(rq, Webb Miller
+and Eugene W. Myers,
+.Em Software---Practice and Experience
+Vol. 15 No. 11, 1985, pp. 1025--1040. The algorithm was independently discovered
+as described by E. Ukkonen in \(lqAlgorithms for Approximate String Matching\(rq,
+.Em Information and Control
+Vol. 64, 1985, pp. 100--118. Unless the
+.Op --minimal
+option is used,
+.Xr diff
+uses a heuristic by Paul Eggert that limits the cost to O(N^1.5 log N) at
+the price of producing suboptimal output for large inputs with many differences.
+Related algorithms are surveyed by Alfred V. Aho in section 6.3 of \(lqAlgorithms
+for Finding Patterns in Strings\(rq,
+.Em Handbook of Theoretical Computer Science
+(Jan Van Leeuwen, ed.), Vol. A,
+.Em Algorithms and Complexity ,
+Elsevier/MIT Press, 1990, pp. 255--300.
+.Pp
+GNU
+.Xr diff3
+was written by Randy Smith. GNU
+.Xr sdiff
+was written by Thomas Lord. GNU
+.Xr cmp
+was written by Torbj\(:orn Granlund and David MacKenzie.
+.Pp
+GNU
+.Xr patch
+was written mainly by Larry Wall and Paul Eggert; several GNU enhancements
+were contributed by Wayne Davison and David MacKenzie. Parts of this manual
+are adapted from a manual page written by Larry Wall, with his permission.
+.Pp
+.Sh What Comparison Means
+There are several ways to think about the differences between two files. One
+way to think of the differences is as a series of lines that were deleted
+from, inserted in, or changed in one file to produce the other file.
+.Xr diff
+compares two files line by line, finds groups of lines that differ, and reports
+each group of differing lines. It can report the differing lines in several
+formats, which have different purposes.
+.Pp
+GNU
+.Xr diff
+can show whether files are different without detailing the differences. It
+also provides ways to suppress certain kinds of differences that are not important
+to you. Most commonly, such differences are changes in the amount of white
+space between words or lines.
+.Xr diff
+also provides ways to suppress differences in alphabetic case or in lines
+that match a regular expression that you provide. These options can accumulate;
+for example, you can ignore changes in both white space and alphabetic case.
+.Pp
+Another way to think of the differences between two files is as a sequence
+of pairs of bytes that can be either identical or different.
+.Xr cmp
+reports the differences between two files byte by byte, instead of line by
+line. As a result, it is often more useful than
+.Xr diff
+for comparing binary files. For text files,
+.Xr cmp
+is useful mainly when you want to know only whether two files are identical,
+or whether one file is a prefix of the other.
+.Pp
+To illustrate the effect that considering changes byte by byte can have compared
+with considering them line by line, think of what happens if a single newline
+character is added to the beginning of a file. If that file is then compared
+with an otherwise identical file that lacks the newline at the beginning,
+.Xr diff
+will report that a blank line has been added to the file, while
+.Xr cmp
+will report that almost every byte of the two files differs.
+.Pp
+.Xr diff3
+normally compares three input files line by line, finds groups of lines that
+differ, and reports each group of differing lines. Its output is designed
+to make it easy to inspect two different sets of changes to the same file.
+.Pp
+.Ss Hunks
+When comparing two files,
+.Xr diff
+finds sequences of lines common to both files, interspersed with groups of
+differing lines called
+.Em hunks .
+Comparing two identical files yields one sequence of common lines and no hunks,
+because no lines differ. Comparing two entirely different files yields no
+common lines and one large hunk that contains all lines of both files. In
+general, there are many ways to match up lines between two given files.
+.Xr diff
+tries to minimize the total hunk size by finding large sequences of common
+lines interspersed with small hunks of differing lines.
+.Pp
+For example, suppose the file
+.Pa F
+contains the three lines
+.Li a ,
+.Li b ,
+.Li c ,
+and the file
+.Pa G
+contains the same three lines in reverse order
+.Li c ,
+.Li b ,
+.Li a .
+If
+.Xr diff
+finds the line
+.Li c
+as common, then the command
+.Li diff F G
+produces this output:
+.Pp
+.Bd -literal -offset indent
+1,2d0
+< a
+< b
+3a2,3
+> b
+> a
+.Ed
+.Pp
+But if
+.Xr diff
+notices the common line
+.Li b
+instead, it produces this output:
+.Pp
+.Bd -literal -offset indent
+1c1
+< a
+---
+> c
+3c3
+< c
+---
+> a
+.Ed
+.Pp
+It is also possible to find
+.Li a
+as the common line.
+.Xr diff
+does not always find an optimal matching between the files; it takes shortcuts
+to run faster. But its output is usually close to the shortest possible. You
+can adjust this tradeoff with the
+.Op -d
+or
+.Op --minimal
+option (see Section
+.Dq diff Performance ) .
+.Pp
+.Ss Suppressing Differences in Blank and Tab Spacing
+The
+.Op -E
+or
+.Op --ignore-tab-expansion
+option ignores the distinction between tabs and spaces on input. A tab is
+considered to be equivalent to the number of spaces to the next tab stop (see Section
+.Dq Tabs ) .
+.Pp
+The
+.Op -b
+or
+.Op --ignore-space-change
+option is stronger. It ignores white space at line end, and considers all
+other sequences of one or more white space characters within a line to be
+equivalent. With this option,
+.Xr diff
+considers the following two lines to be equivalent, where
+.Li $
+denotes the line end:
+.Pp
+.Bd -literal -offset indent
+Here lyeth muche rychnesse in lytell space. -- John Heywood$
+Here lyeth muche rychnesse in lytell space. -- John Heywood $
+.Ed
+.Pp
+The
+.Op -w
+or
+.Op --ignore-all-space
+option is stronger still. It ignores differences even if one line has white
+space where the other line has none.
+.Em White space
+characters include tab, newline, vertical tab, form feed, carriage return,
+and space; some locales may define additional characters to be white space.
+With this option,
+.Xr diff
+considers the following two lines to be equivalent, where
+.Li $
+denotes the line end and
+.Li ^M
+denotes a carriage return:
+.Pp
+.Bd -literal -offset indent
+Here lyeth muche rychnesse in lytell space.-- John Heywood$
+ He relyeth much erychnes seinly tells pace. --John Heywood ^M$
+.Ed
+.Pp
+.Ss Suppressing Differences Whose Lines Are All Blank
+The
+.Op -B
+or
+.Op --ignore-blank-lines
+option ignores changes that consist entirely of blank lines. With this option,
+for example, a file containing
+.Bd -literal -offset indent
+1. A point is that which has no part.
+
+2. A line is breadthless length.
+-- Euclid, The Elements, I
+.Ed
+is considered identical to a file containing
+.Bd -literal -offset indent
+1. A point is that which has no part.
+2. A line is breadthless length.
+
+
+-- Euclid, The Elements, I
+.Ed
+.Pp
+Normally this option affects only lines that are completely empty, but if
+you also specify the
+.Op -b
+or
+.Op --ignore-space-change
+option, or the
+.Op -w
+or
+.Op --ignore-all-space
+option, lines are also affected if they look empty but contain white space.
+In other words,
+.Op -B
+is equivalent to
+.Li -I '^$'
+by default, but it is equivalent to
+.Op -I '^[[:space:]]*$'
+if
+.Op -b
+or
+.Op -w
+is also specified.
+.Pp
+.Ss Suppressing Differences Whose Lines All Match a Regular Expression
+To ignore insertions and deletions of lines that match a
+.Xr grep
+-style regular expression, use the
+.Op -I Va regexp
+or
+.Op --ignore-matching-lines= Va regexp
+option. You should escape regular expressions that contain shell metacharacters
+to prevent the shell from expanding them. For example,
+.Li diff -I '^[[:digit:]]'
+ignores all changes to lines beginning with a digit.
+.Pp
+However,
+.Op -I
+only ignores the insertion or deletion of lines that contain the regular expression
+if every changed line in the hunk---every insertion and every deletion---matches
+the regular expression. In other words, for each nonignorable change,
+.Xr diff
+prints the complete set of changes in its vicinity, including the ignorable
+ones.
+.Pp
+You can specify more than one regular expression for lines to ignore by using
+more than one
+.Op -I
+option.
+.Xr diff
+tries to match each line against each regular expression.
+.Pp
+.Ss Suppressing Case Differences
+GNU
+.Xr diff
+can treat lower case letters as equivalent to their upper case counterparts,
+so that, for example, it considers
+.Li Funky Stuff ,
+.Li funky STUFF ,
+and
+.Li fUNKy stuFf
+to all be the same. To request this, use the
+.Op -i
+or
+.Op --ignore-case
+option.
+.Pp
+.Ss Summarizing Which Files Differ
+When you only want to find out whether files are different, and you don't
+care what the differences are, you can use the summary output format. In this
+format, instead of showing the differences between the files,
+.Xr diff
+simply reports whether files differ. The
+.Op -q
+or
+.Op --brief
+option selects this output format.
+.Pp
+This format is especially useful when comparing the contents of two directories.
+It is also much faster than doing the normal line by line comparisons, because
+.Xr diff
+can stop analyzing the files as soon as it knows that there are any differences.
+.Pp
+You can also get a brief indication of whether two files differ by using
+.Xr cmp .
+For files that are identical,
+.Xr cmp
+produces no output. When the files differ, by default,
+.Xr cmp
+outputs the byte and line number where the first difference occurs, or reports
+that one file is a prefix of the other. You can use the
+.Op -s ,
+.Op --quiet ,
+or
+.Op --silent
+option to suppress that information, so that
+.Xr cmp
+produces no output and reports whether the files differ using only its exit
+status (see Section
+.Dq Invoking cmp ) .
+.Pp
+Unlike
+.Xr diff ,
+.Xr cmp
+cannot compare directories; it can only compare two files.
+.Pp
+.Ss Binary Files and Forcing Text Comparisons
+If
+.Xr diff
+thinks that either of the two files it is comparing is binary (a non-text
+file), it normally treats that pair of files much as if the summary output
+format had been selected (see Section
+.Dq Brief ) ,
+and reports only that the binary files are different. This is because line
+by line comparisons are usually not meaningful for binary files.
+.Pp
+.Xr diff
+determines whether a file is text or binary by checking the first few bytes
+in the file; the exact number of bytes is system dependent, but it is typically
+several thousand. If every byte in that part of the file is non-null,
+.Xr diff
+considers the file to be text; otherwise it considers the file to be binary.
+.Pp
+Sometimes you might want to force
+.Xr diff
+to consider files to be text. For example, you might be comparing text files
+that contain null characters;
+.Xr diff
+would erroneously decide that those are non-text files. Or you might be comparing
+documents that are in a format used by a word processing system that uses
+null characters to indicate special formatting. You can force
+.Xr diff
+to consider all files to be text files, and compare them line by line, by
+using the
+.Op -a
+or
+.Op --text
+option. If the files you compare using this option do not in fact contain
+text, they will probably contain few newline characters, and the
+.Xr diff
+output will consist of hunks showing differences between long lines of whatever
+characters the files contain.
+.Pp
+You can also force
+.Xr diff
+to report only whether files differ (but not how). Use the
+.Op -q
+or
+.Op --brief
+option for this.
+.Pp
+Normally, differing binary files count as trouble because the resulting
+.Xr diff
+output does not capture all the differences. This trouble causes
+.Xr diff
+to exit with status 2. However, this trouble cannot occur with the
+.Op -a
+or
+.Op --text
+option, or with the
+.Op -q
+or
+.Op --brief
+option, as these options both cause
+.Xr diff
+to generate a form of output that represents differences as requested.
+.Pp
+In operating systems that distinguish between text and binary files,
+.Xr diff
+normally reads and writes all data as text. Use the
+.Op --binary
+option to force
+.Xr diff
+to read and write binary data instead. This option has no effect on a POSIX-compliant
+system like GNU or traditional Unix. However, many personal computer operating
+systems represent the end of a line with a carriage return followed by a newline.
+On such systems,
+.Xr diff
+normally ignores these carriage returns on input and generates them at the
+end of each output line, but with the
+.Op --binary
+option
+.Xr diff
+treats each carriage return as just another input character, and does not
+generate a carriage return at the end of each output line. This can be useful
+when dealing with non-text files that are meant to be interchanged with POSIX-compliant
+systems.
+.Pp
+The
+.Op --strip-trailing-cr
+causes
+.Xr diff
+to treat input lines that end in carriage return followed by newline as if
+they end in plain newline. This can be useful when comparing text that is
+imperfectly imported from many personal computer operating systems. This option
+affects how lines are read, which in turn affects how they are compared and
+output.
+.Pp
+If you want to compare two files byte by byte, you can use the
+.Xr cmp
+program with the
+.Op -l
+or
+.Op --verbose
+option to show the values of each differing byte in the two files. With GNU
+.Xr cmp ,
+you can also use the
+.Op -b
+or
+.Op --print-bytes
+option to show the ASCII representation of those bytes.See Section
+.Dq Invoking cmp ,
+for more information.
+.Pp
+If
+.Xr diff3
+thinks that any of the files it is comparing is binary (a non-text file),
+it normally reports an error, because such comparisons are usually not useful.
+.Xr diff3
+uses the same test as
+.Xr diff
+to decide whether a file is binary. As with
+.Xr diff ,
+if the input files contain a few non-text bytes but otherwise are like text
+files, you can force
+.Xr diff3
+to consider all files to be text files and compare them line by line by using
+the
+.Op -a
+or
+.Op --text
+option.
+.Pp
+.Sh Xr diff Output Formats
+.Xr diff
+has several mutually exclusive options for output format. The following sections
+describe each format, illustrating how
+.Xr diff
+reports the differences between two sample input files.
+.Pp
+.Ss Two Sample Input Files
+Here are two sample files that we will use in numerous examples to illustrate
+the output of
+.Xr diff
+and how various options can change it.
+.Pp
+This is the file
+.Pa lao :
+.Pp
+.Bd -literal -offset indent
+The Way that can be told of is not the eternal Way;
+The name that can be named is not the eternal name.
+The Nameless is the origin of Heaven and Earth;
+The Named is the mother of all things.
+Therefore let there always be non-being,
+ so we may see their subtlety,
+And let there always be being,
+ so we may see their outcome.
+The two are the same,
+But after they are produced,
+ they have different names.
+.Ed
+.Pp
+This is the file
+.Pa tzu :
+.Pp
+.Bd -literal -offset indent
+The Nameless is the origin of Heaven and Earth;
+The named is the mother of all things.
+
+Therefore let there always be non-being,
+ so we may see their subtlety,
+And let there always be being,
+ so we may see their outcome.
+The two are the same,
+But after they are produced,
+ they have different names.
+They both may be called deep and profound.
+Deeper and more profound,
+The door of all subtleties!
+.Ed
+.Pp
+In this example, the first hunk contains just the first two lines of
+.Pa lao ,
+the second hunk contains the fourth line of
+.Pa lao
+opposing the second and third lines of
+.Pa tzu ,
+and the last hunk contains just the last three lines of
+.Pa tzu .
+.Pp
+.Ss Showing Differences in Their Context
+Usually, when you are looking at the differences between files, you will also
+want to see the parts of the files near the lines that differ, to help you
+understand exactly what has changed. These nearby parts of the files are called
+the
+.Em context .
+.Pp
+GNU
+.Xr diff
+provides two output formats that show context around the differing lines:
+.Em context format
+and
+.Em unified format .
+It can optionally show in which function or section of the file the differing
+lines are found.
+.Pp
+If you are distributing new versions of files to other people in the form
+of
+.Xr diff
+output, you should use one of the output formats that show context so that
+they can apply the diffs even if they have made small changes of their own
+to the files.
+.Xr patch
+can apply the diffs in this case by searching in the files for the lines of
+context around the differing lines; if those lines are actually a few lines
+away from where the diff says they are,
+.Xr patch
+can adjust the line numbers accordingly and still apply the diff correctly.See Section
+.Dq Imperfect ,
+for more information on using
+.Xr patch
+to apply imperfect diffs.
+.Pp
+.Em Context Format
+.Pp
+The context output format shows several lines of context around the lines
+that differ. It is the standard format for distributing updates to source
+code.
+.Pp
+To select this output format, use the
+.Op -C Va lines ,
+.Op --context[= Va lines] ,
+or
+.Op -c
+option. The argument
+.Va lines
+that some of these options take is the number of lines of context to show.
+If you do not specify
+.Va lines ,
+it defaults to three. For proper operation,
+.Xr patch
+typically needs at least two lines of context.
+.Pp
+.No An Example of Context Format
+.Pp
+Here is the output of
+.Li diff -c lao tzu
+(see Section
+.Dq Sample diff Input ,
+for the complete contents of the two files). Notice that up to three lines
+that are not different are shown around each line that is different; they
+are the context lines. Also notice that the first two hunks have run together,
+because their contents overlap.
+.Pp
+.Bd -literal -offset indent
+*** lao 2002-02-21 23:30:39.942229878 -0800
+--- tzu 2002-02-21 23:30:50.442260588 -0800
+***************
+*** 1,7 ****
+- The Way that can be told of is not the eternal Way;
+- The name that can be named is not the eternal name.
+ The Nameless is the origin of Heaven and Earth;
+! The Named is the mother of all things.
+ Therefore let there always be non-being,
+ so we may see their subtlety,
+ And let there always be being,
+--- 1,6 ----
+ The Nameless is the origin of Heaven and Earth;
+! The named is the mother of all things.
+!
+ Therefore let there always be non-being,
+ so we may see their subtlety,
+ And let there always be being,
+***************
+*** 9,11 ****
+--- 8,13 ----
+ The two are the same,
+ But after they are produced,
+ they have different names.
++ They both may be called deep and profound.
++ Deeper and more profound,
++ The door of all subtleties!
+.Ed
+.Pp
+.No An Example of Context Format with Less Context
+.Pp
+Here is the output of
+.Li diff -C 1 lao tzu
+(see Section
+.Dq Sample diff Input ,
+for the complete contents of the two files). Notice that at most one context
+line is reported here.
+.Pp
+.Bd -literal -offset indent
+*** lao 2002-02-21 23:30:39.942229878 -0800
+--- tzu 2002-02-21 23:30:50.442260588 -0800
+***************
+*** 1,5 ****
+- The Way that can be told of is not the eternal Way;
+- The name that can be named is not the eternal name.
+ The Nameless is the origin of Heaven and Earth;
+! The Named is the mother of all things.
+ Therefore let there always be non-being,
+--- 1,4 ----
+ The Nameless is the origin of Heaven and Earth;
+! The named is the mother of all things.
+!
+ Therefore let there always be non-being,
+***************
+*** 11 ****
+--- 10,13 ----
+ they have different names.
++ They both may be called deep and profound.
++ Deeper and more profound,
++ The door of all subtleties!
+.Ed
+.Pp
+.No Detailed Description of Context Format
+.Pp
+The context output format starts with a two-line header, which looks like
+this:
+.Pp
+.Bd -literal -offset indent
+*** from-file from-file-modification-time
+--- to-file to-file-modification time
+.Ed
+.Pp
+The time stamp normally looks like
+.Li 2002-02-21 23:30:39.942229878 -0800
+to indicate the date, time with fractional seconds, and time zone in
+.Lk ftp://ftp.isi.edu/in-notes/rfc2822.txt .
+(The fractional seconds are omitted on hosts that do not support fractional
+time stamps.) However, a traditional time stamp like
+.Li Thu Feb 21 23:30:39 2002
+is used if the
+.Ev LC_TIME
+locale category is either
+.Li C
+or
+.Li POSIX .
+.Pp
+You can change the header's content with the
+.Op --label= Va label
+option; see Alternate Names.
+.Pp
+Next come one or more hunks of differences; each hunk shows one area where
+the files differ. Context format hunks look like this:
+.Pp
+.Bd -literal -offset indent
+***************
+*** from-file-line-numbers ****
+ from-file-line
+ from-file-line...
+--- to-file-line-numbers ----
+ to-file-line
+ to-file-line...
+.Ed
+.Pp
+If a hunk contains two or more lines, its line numbers look like
+.Li Va start, Va end .
+Otherwise only its end line number appears. An empty hunk is considered to
+end at the line that precedes the hunk.
+.Pp
+The lines of context around the lines that differ start with two space characters.
+The lines that differ between the two files start with one of the following
+indicator characters, followed by a space character:
+.Pp
+.Bl -tag -width Ds
+.It !
+A line that is part of a group of one or more lines that changed between the
+two files. There is a corresponding group of lines marked with
+.Li !
+in the part of this hunk for the other file.
+.Pp
+.It +
+An \(lqinserted\(rq line in the second file that corresponds to nothing in the first
+file.
+.Pp
+.It -
+A \(lqdeleted\(rq line in the first file that corresponds to nothing in the second
+file.
+.El
+.Pp
+If all of the changes in a hunk are insertions, the lines of
+.Va from-file
+are omitted. If all of the changes are deletions, the lines of
+.Va to-file
+are omitted.
+.Pp
+.Em Unified Format
+.Pp
+The unified output format is a variation on the context format that is more
+compact because it omits redundant context lines. To select this output format,
+use the
+.Op -U Va lines ,
+.Op --unified[= Va lines] ,
+or
+.Op -u
+option. The argument
+.Va lines
+is the number of lines of context to show. When it is not given, it defaults
+to three.
+.Pp
+At present, only GNU
+.Xr diff
+can produce this format and only GNU
+.Xr patch
+can automatically apply diffs in this format. For proper operation,
+.Xr patch
+typically needs at least three lines of context.
+.Pp
+.No An Example of Unified Format
+.Pp
+Here is the output of the command
+.Li diff -u lao tzu
+(see Section
+.Dq Sample diff Input ,
+for the complete contents of the two files):
+.Pp
+.Bd -literal -offset indent
+--- lao 2002-02-21 23:30:39.942229878 -0800
++++ tzu 2002-02-21 23:30:50.442260588 -0800
+@@ -1,7 +1,6 @@
+-The Way that can be told of is not the eternal Way;
+-The name that can be named is not the eternal name.
+ The Nameless is the origin of Heaven and Earth;
+-The Named is the mother of all things.
++The named is the mother of all things.
++
+ Therefore let there always be non-being,
+ so we may see their subtlety,
+ And let there always be being,
+@@ -9,3 +8,6 @@
+ The two are the same,
+ But after they are produced,
+ they have different names.
++They both may be called deep and profound.
++Deeper and more profound,
++The door of all subtleties!
+.Ed
+.Pp
+.No Detailed Description of Unified Format
+.Pp
+The unified output format starts with a two-line header, which looks like
+this:
+.Pp
+.Bd -literal -offset indent
+--- from-file from-file-modification-time
++++ to-file to-file-modification-time
+.Ed
+.Pp
+The time stamp looks like
+.Li 2002-02-21 23:30:39.942229878 -0800
+to indicate the date, time with fractional seconds, and time zone. The fractional
+seconds are omitted on hosts that do not support fractional time stamps.
+.Pp
+You can change the header's content with the
+.Op --label= Va label
+option; seeSee Section
+.Dq Alternate Names .
+.Pp
+Next come one or more hunks of differences; each hunk shows one area where
+the files differ. Unified format hunks look like this:
+.Pp
+.Bd -literal -offset indent
+@@ from-file-line-numbers to-file-line-numbers @@
+ line-from-either-file
+ line-from-either-file...
+.Ed
+.Pp
+If a hunk contains just one line, only its start line number appears. Otherwise
+its line numbers look like
+.Li Va start, Va count .
+An empty hunk is considered to start at the line that follows the hunk.
+.Pp
+If a hunk and its context contain two or more lines, its line numbers look
+like
+.Li Va start, Va count .
+Otherwise only its end line number appears. An empty hunk is considered to
+end at the line that precedes the hunk.
+.Pp
+The lines common to both files begin with a space character. The lines that
+actually differ between the two files have one of the following indicator
+characters in the left print column:
+.Pp
+.Bl -tag -width Ds
+.It +
+A line was added here to the first file.
+.Pp
+.It -
+A line was removed here from the first file.
+.El
+.Pp
+.Em Showing Which Sections Differences Are in
+.Pp
+Sometimes you might want to know which part of the files each change falls
+in. If the files are source code, this could mean which function was changed.
+If the files are documents, it could mean which chapter or appendix was changed.
+GNU
+.Xr diff
+can show this by displaying the nearest section heading line that precedes
+the differing lines. Which lines are \(lqsection headings\(rq is determined by a regular
+expression.
+.Pp
+.No Showing Lines That Match Regular Expressions
+.Pp
+To show in which sections differences occur for files that are not source
+code for C or similar languages, use the
+.Op -F Va regexp
+or
+.Op --show-function-line= Va regexp
+option.
+.Xr diff
+considers lines that match the
+.Xr grep
+-style regular expression
+.Va regexp
+to be the beginning of a section of the file. Here are suggested regular expressions
+for some common languages:
+.Pp
+.Bl -tag -width Ds
+.It ^[[:alpha:]$_]
+C, C++, Prolog
+.It ^(
+Lisp
+.It ^@node
+Texinfo
+.El
+.Pp
+This option does not automatically select an output format; in order to use
+it, you must select the context format (see Section
+.Dq Context Format )
+or unified format (see Section
+.Dq Unified Format ) .
+In other output formats it has no effect.
+.Pp
+The
+.Op -F
+or
+.Op --show-function-line
+option finds the nearest unchanged line that precedes each hunk of differences
+and matches the given regular expression. Then it adds that line to the end
+of the line of asterisks in the context format, or to the
+.Li @@
+line in unified format. If no matching line exists, this option leaves the
+output for that hunk unchanged. If that line is more than 40 characters long,
+it outputs only the first 40 characters. You can specify more than one regular
+expression for such lines;
+.Xr diff
+tries to match each line against each regular expression, starting with the
+last one given. This means that you can use
+.Op -p
+and
+.Op -F
+together, if you wish.
+.Pp
+.No Showing C Function Headings
+.Pp
+To show in which functions differences occur for C and similar languages,
+you can use the
+.Op -p
+or
+.Op --show-c-function
+option. This option automatically defaults to the context output format (see Section
+.Dq Context Format ) ,
+with the default number of lines of context. You can override that number
+with
+.Op -C Va lines
+elsewhere in the command line. You can override both the format and the number
+with
+.Op -U Va lines
+elsewhere in the command line.
+.Pp
+The
+.Op -p
+or
+.Op --show-c-function
+option is equivalent to
+.Op -F '^[[:alpha:]$_]'
+if the unified format is specified, otherwise
+.Op -c -F '^[[:alpha:]$_]'
+(see Section
+.Dq Specified Headings ) .
+GNU
+.Xr diff
+provides this option for the sake of convenience.
+.Pp
+.Em Showing Alternate File Names
+.Pp
+If you are comparing two files that have meaningless or uninformative names,
+you might want
+.Xr diff
+to show alternate names in the header of the context and unified output formats.
+To do this, use the
+.Op --label= Va label
+option. The first time you give this option, its argument replaces the name
+and date of the first file in the header; the second time, its argument replaces
+the name and date of the second file. If you give this option more than twice,
*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
More information about the svn-src-head
mailing list