Fossil SCM

Improved comments on the diff formatter and related logic.

drh 2021-09-02 22:28 diff-color-enhancements
Commit d29ddba32115d2131fa31a795ef99f3318e90be1f5c796280d20108252e6fa4b
Parent b0511022724d7bf…
2 files changed +61 -5 +8 -1
~ src/diff.c ~ src/diff.js
M src/diff.c
+61 -5
--- src/diff.c
+++ src/diff.c
@@ -1626,10 +1626,13 @@
16261626
16271627
 /*
16281628
 ** This is an abstract superclass for an object that accepts difference
16291629
 ** lines and formats them for display. Subclasses of this object format
16301630
 ** the diff output in different ways.
1631
+**
1632
+** To subclass, create an instance of the DiffBuilder object and fill
1633
+** in appropriate method implementations.
16311634
 */
16321635
 typedef struct DiffBuilder DiffBuilder;
16331636
 struct DiffBuilder {
16341637
 void (*xSkip)(DiffBuilder*, unsigned int, int);
16351638
 void (*xCommon)(DiffBuilder*,const DLine*);
@@ -1645,10 +1648,16 @@
16451648
 Blob *pOut; /* Output blob */
16461649
 Blob aCol[5]; /* Holding blobs */
16471650
 };
16481651
16491652
 /************************* DiffBuilderDebug ********************************/
1653
+/* This version of DiffBuilder is used for debugging the diff and diff
1654
+** diff formatter logic. It is accessed using the (undocumented) --debug
1655
+** option to the diff command. The output is human-readable text that
1656
+** describes the various method calls that are invoked agains the DiffBuilder
1657
+** object.
1658
+*/
16501659
 static void dfdebugSkip(DiffBuilder *p, unsigned int n, int isFinal){
16511660
 blob_appendf(p->pOut, "SKIP %d (%d..%d left and %d..%d right)%s\n",
16521661
 n, p->lnLeft+1, p->lnLeft+n, p->lnRight+1, p->lnRight+n,
16531662
 isFinal ? " FINAL" : "");
16541663
 p->lnLeft += n;
@@ -1739,12 +1748,33 @@
17391748
 return p;
17401749
 }
17411750
17421751
 /************************* DiffBuilderTcl ********************************/
17431752
 /*
1744
-** This variant outputs a description of the diff formatted as TCL, for
1745
-** use by the --tk option to "diff".
1753
+** This formatter outputs a description of the diff formatted as TCL, for
1754
+** use by the --tk option to "diff". See also the "diff.tcl" file. The
1755
+** output can be viewed directly using the --tcl option.
1756
+**
1757
+** There is one line per method call:
1758
+**
1759
+** SKIP n -- Skip "n" lines of input
1760
+** COM string -- "string" is an unchanged context line
1761
+** INS string -- "string" is in the right file only
1762
+** DEL string -- "string" is in the left file only
1763
+** EDIT string .... -- Complex edit between left and right
1764
+**
1765
+** The EDIT verb will be followed by 3*N or 3*N+1 strings. The triples
1766
+** each show:
1767
+**
1768
+** 1. Common text
1769
+** 2. Text from the left side
1770
+** 3. Text on the right that replaces (2) from the left
1771
+**
1772
+** For inserted text (2) will be an empty string. For deleted text, (3)
1773
+** will be an empty string. (1) might be empty for the first triple if
1774
+** the line begins with an edit. After all triples, there might be one
1775
+** additional string which is a common suffix.
17461776
 */
17471777
 static void dftclSkip(DiffBuilder *p, unsigned int n, int isFinal){
17481778
 blob_appendf(p->pOut, "SKIP %u\n", n);
17491779
 }
17501780
 static void dftclCommon(DiffBuilder *p, const DLine *pLine){
@@ -1807,11 +1837,11 @@
18071837
 return p;
18081838
 }
18091839
18101840
 /************************* DiffBuilderJson ********************************/
18111841
 /*
1812
-** This module generates a JSON array that describes the difference.
1842
+** This formatter generates a JSON array that describes the difference.
18131843
 **
18141844
 ** The Json array consists of integer opcodes with each opcode followed
18151845
 ** by zero or more arguments:
18161846
 **
18171847
 ** Syntax Mnemonic Description
@@ -1890,11 +1920,27 @@
18901920
 blob_append_char(pOut, '[');
18911921
 return p;
18921922
 }
18931923
18941924
 /************************* DiffBuilderUnified********************************/
1895
-/* This module generates a unified diff for HTML
1925
+/* This formatter generates a unified diff for HTML.
1926
+**
1927
+** The result is a <table> with four columns. The four columns hold:
1928
+**
1929
+** 1. The line numbers for the first file.
1930
+** 2. The line numbers for the second file.
1931
+** 3. The "diff mark": "+" or "-" or just a space
1932
+** 4. Text of the line
1933
+**
1934
+** Inserted lines are marked with <ins> and deleted lines are marked
1935
+** with <del>. The whole line is marked this way, not just the part that
1936
+** changed. The part that change has an additional nested <ins> or <del>.
1937
+** The CSS needs to be set up such that a single <ins> or <del> gives a
1938
+** light background and a nested <ins> or <del> gives a darker background.
1939
+** Additional attributes (like bold font) might also be added to nested
1940
+** <ins> and <del> since those are the characters that have actually
1941
+** changed.
18961942
 **
18971943
 ** Accumulator strategy:
18981944
 **
18991945
 ** * Delete line numbers are output directly to p->pOut
19001946
 ** * Insert line numbers accumulate in p->aCol[0].
@@ -2098,11 +2144,21 @@
20982144
 blob_init(&p->aCol[4], 0, 0);
20992145
 return p;
21002146
 }
21012147
21022148
 /************************* DiffBuilderSplit ******************************/
2103
-/* This module generates a side-by-side diff for HTML.
2149
+/* This formatter creates a side-by-side diff in HTML. The output is a
2150
+** <table> with 5 columns:
2151
+**
2152
+** 1. Line numbers for the first file.
2153
+** 2. Text for the first file.
2154
+** 3. The difference mark. "<", ">", "|" or blank
2155
+** 4. Line numbers for the second file.
2156
+** 5. Text for the second file.
2157
+**
2158
+** The <ins> and <del> strategy is the same as for unified diff above.
2159
+** In fact, the same CSS can be used for both.
21042160
 **
21052161
 ** Accumulator strategy:
21062162
 **
21072163
 ** * Left line numbers are output directly to p->pOut
21082164
 ** * Left text accumulates in p->aCol[0].
21092165
--- src/diff.c
+++ src/diff.c
@@ -1626,10 +1626,13 @@
1626
1627 /*
1628 ** This is an abstract superclass for an object that accepts difference
1629 ** lines and formats them for display. Subclasses of this object format
1630 ** the diff output in different ways.
 
 
 
1631 */
1632 typedef struct DiffBuilder DiffBuilder;
1633 struct DiffBuilder {
1634 void (*xSkip)(DiffBuilder*, unsigned int, int);
1635 void (*xCommon)(DiffBuilder*,const DLine*);
@@ -1645,10 +1648,16 @@
1645 Blob *pOut; /* Output blob */
1646 Blob aCol[5]; /* Holding blobs */
1647 };
1648
1649 /************************* DiffBuilderDebug ********************************/
 
 
 
 
 
 
1650 static void dfdebugSkip(DiffBuilder *p, unsigned int n, int isFinal){
1651 blob_appendf(p->pOut, "SKIP %d (%d..%d left and %d..%d right)%s\n",
1652 n, p->lnLeft+1, p->lnLeft+n, p->lnRight+1, p->lnRight+n,
1653 isFinal ? " FINAL" : "");
1654 p->lnLeft += n;
@@ -1739,12 +1748,33 @@
1739 return p;
1740 }
1741
1742 /************************* DiffBuilderTcl ********************************/
1743 /*
1744 ** This variant outputs a description of the diff formatted as TCL, for
1745 ** use by the --tk option to "diff".
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1746 */
1747 static void dftclSkip(DiffBuilder *p, unsigned int n, int isFinal){
1748 blob_appendf(p->pOut, "SKIP %u\n", n);
1749 }
1750 static void dftclCommon(DiffBuilder *p, const DLine *pLine){
@@ -1807,11 +1837,11 @@
1807 return p;
1808 }
1809
1810 /************************* DiffBuilderJson ********************************/
1811 /*
1812 ** This module generates a JSON array that describes the difference.
1813 **
1814 ** The Json array consists of integer opcodes with each opcode followed
1815 ** by zero or more arguments:
1816 **
1817 ** Syntax Mnemonic Description
@@ -1890,11 +1920,27 @@
1890 blob_append_char(pOut, '[');
1891 return p;
1892 }
1893
1894 /************************* DiffBuilderUnified********************************/
1895 /* This module generates a unified diff for HTML
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1896 **
1897 ** Accumulator strategy:
1898 **
1899 ** * Delete line numbers are output directly to p->pOut
1900 ** * Insert line numbers accumulate in p->aCol[0].
@@ -2098,11 +2144,21 @@
2098 blob_init(&p->aCol[4], 0, 0);
2099 return p;
2100 }
2101
2102 /************************* DiffBuilderSplit ******************************/
2103 /* This module generates a side-by-side diff for HTML.
 
 
 
 
 
 
 
 
 
 
2104 **
2105 ** Accumulator strategy:
2106 **
2107 ** * Left line numbers are output directly to p->pOut
2108 ** * Left text accumulates in p->aCol[0].
2109
--- src/diff.c
+++ src/diff.c
@@ -1626,10 +1626,13 @@
1626
1627 /*
1628 ** This is an abstract superclass for an object that accepts difference
1629 ** lines and formats them for display. Subclasses of this object format
1630 ** the diff output in different ways.
1631 **
1632 ** To subclass, create an instance of the DiffBuilder object and fill
1633 ** in appropriate method implementations.
1634 */
1635 typedef struct DiffBuilder DiffBuilder;
1636 struct DiffBuilder {
1637 void (*xSkip)(DiffBuilder*, unsigned int, int);
1638 void (*xCommon)(DiffBuilder*,const DLine*);
@@ -1645,10 +1648,16 @@
1648 Blob *pOut; /* Output blob */
1649 Blob aCol[5]; /* Holding blobs */
1650 };
1651
1652 /************************* DiffBuilderDebug ********************************/
1653 /* This version of DiffBuilder is used for debugging the diff and diff
1654 ** diff formatter logic. It is accessed using the (undocumented) --debug
1655 ** option to the diff command. The output is human-readable text that
1656 ** describes the various method calls that are invoked agains the DiffBuilder
1657 ** object.
1658 */
1659 static void dfdebugSkip(DiffBuilder *p, unsigned int n, int isFinal){
1660 blob_appendf(p->pOut, "SKIP %d (%d..%d left and %d..%d right)%s\n",
1661 n, p->lnLeft+1, p->lnLeft+n, p->lnRight+1, p->lnRight+n,
1662 isFinal ? " FINAL" : "");
1663 p->lnLeft += n;
@@ -1739,12 +1748,33 @@
1748 return p;
1749 }
1750
1751 /************************* DiffBuilderTcl ********************************/
1752 /*
1753 ** This formatter outputs a description of the diff formatted as TCL, for
1754 ** use by the --tk option to "diff". See also the "diff.tcl" file. The
1755 ** output can be viewed directly using the --tcl option.
1756 **
1757 ** There is one line per method call:
1758 **
1759 ** SKIP n -- Skip "n" lines of input
1760 ** COM string -- "string" is an unchanged context line
1761 ** INS string -- "string" is in the right file only
1762 ** DEL string -- "string" is in the left file only
1763 ** EDIT string .... -- Complex edit between left and right
1764 **
1765 ** The EDIT verb will be followed by 3*N or 3*N+1 strings. The triples
1766 ** each show:
1767 **
1768 ** 1. Common text
1769 ** 2. Text from the left side
1770 ** 3. Text on the right that replaces (2) from the left
1771 **
1772 ** For inserted text (2) will be an empty string. For deleted text, (3)
1773 ** will be an empty string. (1) might be empty for the first triple if
1774 ** the line begins with an edit. After all triples, there might be one
1775 ** additional string which is a common suffix.
1776 */
1777 static void dftclSkip(DiffBuilder *p, unsigned int n, int isFinal){
1778 blob_appendf(p->pOut, "SKIP %u\n", n);
1779 }
1780 static void dftclCommon(DiffBuilder *p, const DLine *pLine){
@@ -1807,11 +1837,11 @@
1837 return p;
1838 }
1839
1840 /************************* DiffBuilderJson ********************************/
1841 /*
1842 ** This formatter generates a JSON array that describes the difference.
1843 **
1844 ** The Json array consists of integer opcodes with each opcode followed
1845 ** by zero or more arguments:
1846 **
1847 ** Syntax Mnemonic Description
@@ -1890,11 +1920,27 @@
1920 blob_append_char(pOut, '[');
1921 return p;
1922 }
1923
1924 /************************* DiffBuilderUnified********************************/
1925 /* This formatter generates a unified diff for HTML.
1926 **
1927 ** The result is a <table> with four columns. The four columns hold:
1928 **
1929 ** 1. The line numbers for the first file.
1930 ** 2. The line numbers for the second file.
1931 ** 3. The "diff mark": "+" or "-" or just a space
1932 ** 4. Text of the line
1933 **
1934 ** Inserted lines are marked with <ins> and deleted lines are marked
1935 ** with <del>. The whole line is marked this way, not just the part that
1936 ** changed. The part that change has an additional nested <ins> or <del>.
1937 ** The CSS needs to be set up such that a single <ins> or <del> gives a
1938 ** light background and a nested <ins> or <del> gives a darker background.
1939 ** Additional attributes (like bold font) might also be added to nested
1940 ** <ins> and <del> since those are the characters that have actually
1941 ** changed.
1942 **
1943 ** Accumulator strategy:
1944 **
1945 ** * Delete line numbers are output directly to p->pOut
1946 ** * Insert line numbers accumulate in p->aCol[0].
@@ -2098,11 +2144,21 @@
2144 blob_init(&p->aCol[4], 0, 0);
2145 return p;
2146 }
2147
2148 /************************* DiffBuilderSplit ******************************/
2149 /* This formatter creates a side-by-side diff in HTML. The output is a
2150 ** <table> with 5 columns:
2151 **
2152 ** 1. Line numbers for the first file.
2153 ** 2. Text for the first file.
2154 ** 3. The difference mark. "<", ">", "|" or blank
2155 ** 4. Line numbers for the second file.
2156 ** 5. Text for the second file.
2157 **
2158 ** The <ins> and <del> strategy is the same as for unified diff above.
2159 ** In fact, the same CSS can be used for both.
2160 **
2161 ** Accumulator strategy:
2162 **
2163 ** * Left line numbers are output directly to p->pOut
2164 ** * Left text accumulates in p->aCol[0].
2165
M src/diff.js
+8 -1
--- src/diff.js
+++ src/diff.js
@@ -1,6 +1,13 @@
1
-/* Keeps the horizontal scrollbars* in sync on side-by-side diffs.
1
+/* Refinements to the display of unified and side-by-side diffs.
2
+**
3
+** In all cases, the table columns tagged with "difftxt" are expanded,
4
+** where possible, to fill the width of the screen.
5
+**
6
+** For a side-by-side diff, if either column is two wide to fit on the
7
+** display, scrollbars are added. The scrollbars are linked, so that
8
+** both sides scroll together. Left and right arrows also scroll.
29
 */
310
 (function(){
411
 var SCROLL_LEN = 25;
512
 function initDiff(diff){
613
 var txtCols = diff.querySelectorAll('td.difftxt');
714
--- src/diff.js
+++ src/diff.js
@@ -1,6 +1,13 @@
1 /* Keeps the horizontal scrollbars* in sync on side-by-side diffs.
 
 
 
 
 
 
 
2 */
3 (function(){
4 var SCROLL_LEN = 25;
5 function initDiff(diff){
6 var txtCols = diff.querySelectorAll('td.difftxt');
7
--- src/diff.js
+++ src/diff.js
@@ -1,6 +1,13 @@
1 /* Refinements to the display of unified and side-by-side diffs.
2 **
3 ** In all cases, the table columns tagged with "difftxt" are expanded,
4 ** where possible, to fill the width of the screen.
5 **
6 ** For a side-by-side diff, if either column is two wide to fit on the
7 ** display, scrollbars are added. The scrollbars are linked, so that
8 ** both sides scroll together. Left and right arrows also scroll.
9 */
10 (function(){
11 var SCROLL_LEN = 25;
12 function initDiff(diff){
13 var txtCols = diff.querySelectorAll('td.difftxt');
14

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button