Fossil SCM
First attempt at documenting the new diff web layout.
Commit
07d28ec886cdee51d47f43f663d15eb02735cca8446907392220eb016500014d
Parent
00b5e02ab2fdc4c…
2 files changed
+112
+12
+112
| --- a/www/css/diff.md | ||
| +++ b/www/css/diff.md | ||
| @@ -0,0 +1,112 @@ | ||
| 1 | +Notes On Diff Formatting | |
| 2 | +======================== | |
| 3 | + | |
| 4 | +There are two main kinds of diff display for the web interface: | |
| 5 | +unified and side-by-side. Both displays are implemented using | |
| 6 | +a <table>. The unified diff is a 4-column table, and the | |
| 7 | +side-by-side diff is a 5-column table. In a page like /info that | |
| 8 | +might show multiple file diffs, each file diff is in a separate | |
| 9 | +<table>. For side-by-side diffs, a small amount of Javascript | |
| 10 | +code is used to resize the text columns so that they fill the screen | |
| 11 | +width and to keep horizontal scrollbars in sync. | |
| 12 | + | |
| 13 | +For the unified diff, the basic structure | |
| 14 | +is like this: | |
| 15 | + | |
| 16 | +> ~~~~ | |
| 17 | +<table class='diff udiff'> | |
| 18 | +<tr> | |
| 19 | + <td class='diffln difflnl'><pre> | |
| 20 | + Line numbers for the left-hand file | |
| 21 | + </pre></td> | |
| 22 | + <td class='diffln difflnr'><pre> | |
| 23 | + Line numbers for the right-hand file | |
| 24 | + </pre></td> | |
| 25 | + <td class='diffsep'><pre> | |
| 26 | + Change marks. "+" or "=" or nothing | |
| 27 | + </pre></td> | |
| 28 | + <td class='difftxt difftxtu'><pre> | |
| 29 | + The text | |
| 30 | + </pre></td> | |
| 31 | +</tr> | |
| 32 | +</table> | |
| 33 | +~~~~ | |
| 34 | + | |
| 35 | +The structure for a side-by-side diff follows the | |
| 36 | +same basic pattern, though with 5 columns instead of | |
| 37 | +4, and slightly different class names: | |
| 38 | + | |
| 39 | +> ~~~~ | |
| 40 | +<table class='diff splitdiff'> | |
| 41 | +<tr> | |
| 42 | + <td class='diffln difflnl'><pre> | |
| 43 | + Line numbers for the left-hand file | |
| 44 | + </pre></td> | |
| 45 | + <td class='difftxt difftxtl'><pre> | |
| 46 | + The text for the left side | |
| 47 | + </pre></td> | |
| 48 | + <td class='diffsep'><pre> | |
| 49 | + Change marks. "+" or "=" or nothing | |
| 50 | + </pre></td> | |
| 51 | + <td class='diffln difflnr'><pre> | |
| 52 | + Line numbers for the right-hand file | |
| 53 | + </pre></td> | |
| 54 | + <td class='difftxt difftxtr'><pre> | |
| 55 | + The text on the right-hand side | |
| 56 | + </pre></td> | |
| 57 | +</tr> | |
| 58 | +</table> | |
| 59 | +~~~~ | |
| 60 | + | |
| 61 | +The outer <table> always has class "diff". The "diffu" class | |
| 62 | +is added for unified diffs and the "splitdiff" class is added for | |
| 63 | +side-by-side diffs. | |
| 64 | + | |
| 65 | +All line-number columns have the "diffln" class. They also always | |
| 66 | +have one of "difflnl" or "difflnr" depending on whether they hold | |
| 67 | +line numbers for the left or right files, respectively. | |
| 68 | + | |
| 69 | +Text is always kept in a separate column so that it can be scraped | |
| 70 | +and copied by the user. All text columns have the "difftxt" class. | |
| 71 | +One additional class "difftxtu", "difftxtl", or "difftxtr" is added | |
| 72 | +depending on if the text is for a unified diff, the left column of | |
| 73 | +a side-by-side diff, or the right column of a side-by-side diff. | |
| 74 | + | |
| 75 | +The content of all columns is a single <pre> that contains the | |
| 76 | +appropriate diff-text for that column. Scrolling is done on the | |
| 77 | +<pre> element. | |
| 78 | + | |
| 79 | +Within text columns, highlighting is done with <del> and | |
| 80 | +<ins> markup. All text on a line that contains an isert or | |
| 81 | +delete is surrounded by <ins>...</ins> or | |
| 82 | +<del>..</del>. Within that line, specific characters | |
| 83 | +of text that specifically inserted deleted have an additional | |
| 84 | +layer of <ins> or <del> markup. Thus CSS like the | |
| 85 | +following is appropriate: | |
| 86 | + | |
| 87 | +> ~~~~ | |
| 88 | +td.difftxt ins { | |
| 89 | + background-color: #dafbe1; /* Light green for the whole line */ | |
| 90 | + text-decoration: none; | |
| 91 | +} | |
| 92 | +td.difftxt ins > ins { | |
| 93 | + background-color: #a0e4b2; /* Dark green for specific characters that change */ | |
| 94 | + text-decoration: none; | |
| 95 | +} | |
| 96 | +~~~~ | |
| 97 | + | |
| 98 | +In a side-by-side diff, if an interior <ins> or <del> that mark | |
| 99 | +specific characters that change correspond to a delete/insert on the other | |
| 100 | +side, they they have the "edit" class tag. (ex: <ins class='edit'> | |
| 101 | +or <del class='edit'>). Some skins choose to paint these "modified" | |
| 102 | +regions blue: | |
| 103 | + | |
| 104 | +> ~~~~ | |
| 105 | +td.difftxt ins > ins.edit { | |
| 106 | + background-color: #c0c0ff; /* Blue for "modified" text region */ | |
| 107 | + text-decoration: none; | |
| 108 | +} | |
| 109 | +~~~~ | |
| 110 | + | |
| 111 | +Line number text also has <ins> and <del> tags for lines which | |
| 112 | +are pure insert or pure delete. But the tags do not nest for line numbers. |
| --- a/www/css/diff.md | |
| +++ b/www/css/diff.md | |
| @@ -0,0 +1,112 @@ | |
| --- a/www/css/diff.md | |
| +++ b/www/css/diff.md | |
| @@ -0,0 +1,112 @@ | |
| 1 | Notes On Diff Formatting |
| 2 | ======================== |
| 3 | |
| 4 | There are two main kinds of diff display for the web interface: |
| 5 | unified and side-by-side. Both displays are implemented using |
| 6 | a <table>. The unified diff is a 4-column table, and the |
| 7 | side-by-side diff is a 5-column table. In a page like /info that |
| 8 | might show multiple file diffs, each file diff is in a separate |
| 9 | <table>. For side-by-side diffs, a small amount of Javascript |
| 10 | code is used to resize the text columns so that they fill the screen |
| 11 | width and to keep horizontal scrollbars in sync. |
| 12 | |
| 13 | For the unified diff, the basic structure |
| 14 | is like this: |
| 15 | |
| 16 | > ~~~~ |
| 17 | <table class='diff udiff'> |
| 18 | <tr> |
| 19 | <td class='diffln difflnl'><pre> |
| 20 | Line numbers for the left-hand file |
| 21 | </pre></td> |
| 22 | <td class='diffln difflnr'><pre> |
| 23 | Line numbers for the right-hand file |
| 24 | </pre></td> |
| 25 | <td class='diffsep'><pre> |
| 26 | Change marks. "+" or "=" or nothing |
| 27 | </pre></td> |
| 28 | <td class='difftxt difftxtu'><pre> |
| 29 | The text |
| 30 | </pre></td> |
| 31 | </tr> |
| 32 | </table> |
| 33 | ~~~~ |
| 34 | |
| 35 | The structure for a side-by-side diff follows the |
| 36 | same basic pattern, though with 5 columns instead of |
| 37 | 4, and slightly different class names: |
| 38 | |
| 39 | > ~~~~ |
| 40 | <table class='diff splitdiff'> |
| 41 | <tr> |
| 42 | <td class='diffln difflnl'><pre> |
| 43 | Line numbers for the left-hand file |
| 44 | </pre></td> |
| 45 | <td class='difftxt difftxtl'><pre> |
| 46 | The text for the left side |
| 47 | </pre></td> |
| 48 | <td class='diffsep'><pre> |
| 49 | Change marks. "+" or "=" or nothing |
| 50 | </pre></td> |
| 51 | <td class='diffln difflnr'><pre> |
| 52 | Line numbers for the right-hand file |
| 53 | </pre></td> |
| 54 | <td class='difftxt difftxtr'><pre> |
| 55 | The text on the right-hand side |
| 56 | </pre></td> |
| 57 | </tr> |
| 58 | </table> |
| 59 | ~~~~ |
| 60 | |
| 61 | The outer <table> always has class "diff". The "diffu" class |
| 62 | is added for unified diffs and the "splitdiff" class is added for |
| 63 | side-by-side diffs. |
| 64 | |
| 65 | All line-number columns have the "diffln" class. They also always |
| 66 | have one of "difflnl" or "difflnr" depending on whether they hold |
| 67 | line numbers for the left or right files, respectively. |
| 68 | |
| 69 | Text is always kept in a separate column so that it can be scraped |
| 70 | and copied by the user. All text columns have the "difftxt" class. |
| 71 | One additional class "difftxtu", "difftxtl", or "difftxtr" is added |
| 72 | depending on if the text is for a unified diff, the left column of |
| 73 | a side-by-side diff, or the right column of a side-by-side diff. |
| 74 | |
| 75 | The content of all columns is a single <pre> that contains the |
| 76 | appropriate diff-text for that column. Scrolling is done on the |
| 77 | <pre> element. |
| 78 | |
| 79 | Within text columns, highlighting is done with <del> and |
| 80 | <ins> markup. All text on a line that contains an isert or |
| 81 | delete is surrounded by <ins>...</ins> or |
| 82 | <del>..</del>. Within that line, specific characters |
| 83 | of text that specifically inserted deleted have an additional |
| 84 | layer of <ins> or <del> markup. Thus CSS like the |
| 85 | following is appropriate: |
| 86 | |
| 87 | > ~~~~ |
| 88 | td.difftxt ins { |
| 89 | background-color: #dafbe1; /* Light green for the whole line */ |
| 90 | text-decoration: none; |
| 91 | } |
| 92 | td.difftxt ins > ins { |
| 93 | background-color: #a0e4b2; /* Dark green for specific characters that change */ |
| 94 | text-decoration: none; |
| 95 | } |
| 96 | ~~~~ |
| 97 | |
| 98 | In a side-by-side diff, if an interior <ins> or <del> that mark |
| 99 | specific characters that change correspond to a delete/insert on the other |
| 100 | side, they they have the "edit" class tag. (ex: <ins class='edit'> |
| 101 | or <del class='edit'>). Some skins choose to paint these "modified" |
| 102 | regions blue: |
| 103 | |
| 104 | > ~~~~ |
| 105 | td.difftxt ins > ins.edit { |
| 106 | background-color: #c0c0ff; /* Blue for "modified" text region */ |
| 107 | text-decoration: none; |
| 108 | } |
| 109 | ~~~~ |
| 110 | |
| 111 | Line number text also has <ins> and <del> tags for lines which |
| 112 | are pure insert or pure delete. But the tags do not nest for line numbers. |
+12
| --- a/www/css/index.md | ||
| +++ b/www/css/index.md | ||
| @@ -0,0 +1,12 @@ | ||
| 1 | +Cascading Style Sheet Notes | |
| 2 | +=========================== | |
| 3 | + | |
| 4 | +This is a collection of technical notes that document the design of | |
| 5 | +the Document Object Model (DOM) and corresponding Cascading Style Sheet (CSS) | |
| 6 | +attributes used for customing the look-and-feel of Fossil. These notes | |
| 7 | +are of interest to people who want to customize the Fossil skin or | |
| 8 | +enhance the internal display logic. | |
| 9 | + | |
| 10 | +This is a collection of documents that we hope will grow over time. | |
| 11 | + | |
| 12 | + * [Diff styling](./diff.md) |
| --- a/www/css/index.md | |
| +++ b/www/css/index.md | |
| @@ -0,0 +1,12 @@ | |
| --- a/www/css/index.md | |
| +++ b/www/css/index.md | |
| @@ -0,0 +1,12 @@ | |
| 1 | Cascading Style Sheet Notes |
| 2 | =========================== |
| 3 | |
| 4 | This is a collection of technical notes that document the design of |
| 5 | the Document Object Model (DOM) and corresponding Cascading Style Sheet (CSS) |
| 6 | attributes used for customing the look-and-feel of Fossil. These notes |
| 7 | are of interest to people who want to customize the Fossil skin or |
| 8 | enhance the internal display logic. |
| 9 | |
| 10 | This is a collection of documents that we hope will grow over time. |
| 11 | |
| 12 | * [Diff styling](./diff.md) |