local-lib5/man/man3/Text::Diff::Table.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "Text::Diff::Table 3"
 127 .TH Text::Diff::Table 3 "2009-07-16" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 .Vb 1
 134 \&  Text::Diff::Table \- Text::Diff plugin to generate "table" format output
 135 .Ve
 136 .SH "SYNOPSIS"
 137 .IX Header "SYNOPSIS"
 138 .Vb 1
 139 \&  use Text::Diff;
 140 \&
 141 \&  diff \e@a, $b { STYLE => "Table" };
 142 .Ve
 143 .SH "DESCRIPTION"
 144 .IX Header "DESCRIPTION"
 145 This is a plugin output formatter for Text::Diff that generates \*(L"table\*(R" style
 146 diffs:
 147 .PP
 148 .Vb 10
 149 \&  +\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
 150 \&  |  |../Test\-Differences\-0.2/MANIFEST  |  |../Test\-Differences/MANIFEST  |
 151 \&  |  |Thu Dec 13 15:38:49 2001          |  |Sat Dec 15 02:09:44 2001      |
 152 \&  +\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
 153 \&  |  |                                  * 1|Changes                       *
 154 \&  | 1|Differences.pm                    | 2|Differences.pm                |
 155 \&  | 2|MANIFEST                          | 3|MANIFEST                      |
 156 \&  |  |                                  * 4|MANIFEST.SKIP                 *
 157 \&  | 3|Makefile.PL                       | 5|Makefile.PL                   |
 158 \&  |  |                                  * 6|t/00escape.t                  *
 159 \&  | 4|t/00flatten.t                     | 7|t/00flatten.t                 |
 160 \&  | 5|t/01text_vs_data.t                | 8|t/01text_vs_data.t            |
 161 \&  | 6|t/10test.t                        | 9|t/10test.t                    |
 162 \&  +\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
 163 .Ve
 164 .PP
 165 This format also goes to some pains to highlight \*(L"invisible\*(R" characters on
 166 differing elements by selectively escaping whitespace.  Each element is split
 167 in to three segments (leading whitespace, body, trailing whitespace).  If
 168 whitespace differs in a segement, that segment is whitespace escaped.
 169 .PP
 170 Here is an example of the selective whitespace.
 171 .PP
 172 .Vb 10
 173 \&  +\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
 174 \&  |  |demo_ws_A.txt             |demo_ws_B.txt             |
 175 \&  |  |Fri Dec 21 08:36:32 2001  |Fri Dec 21 08:36:50 2001  |
 176 \&  +\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
 177 \&  | 1|identical                 |identical                 |
 178 \&  * 2|        spaced in         |        also spaced in    *
 179 \&  * 3|embedded space            |embedded        tab       *
 180 \&  | 4|identical                 |identical                 |
 181 \&  * 5|        spaced in         |\ettabbed in               *
 182 \&  * 6|trailing spaces\es\es\en     |trailing tabs\et\et\en       *
 183 \&  | 7|identical                 |identical                 |
 184 \&  * 8|lf line\en                 |crlf line\er\en             *
 185 \&  * 9|embedded ws               |embedded\etws              *
 186 \&  +\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
 187 .Ve
 188 .PP
 189 Here's why the lines do or do not have whitespace escaped:
 190 .IP "lines 1, 4, 7 don't differ, no need." 4
 191 .IX Item "lines 1, 4, 7 don't differ, no need."
 192 .PD 0
 193 .IP "lines 2, 3 differ in non-whitespace, no need." 4
 194 .IX Item "lines 2, 3 differ in non-whitespace, no need."
 195 .IP "lines 5, 6, 8, 9 all have subtle ws changes." 4
 196 .IX Item "lines 5, 6, 8, 9 all have subtle ws changes."
 197 .PD
 198 .PP
 199 Whether or not line 3 should have that tab character escaped is a judgement
 200 call; so far I'm choosing not to.
 201 .SH "LIMITATIONS"
 202 .IX Header "LIMITATIONS"
 203 Table formatting requires buffering the entire diff in memory in order to
 204 calculate column widths.  This format should only be used for smaller
 205 diffs.
 206 .PP
 207 Assumes tab stops every 8 characters, as \f(CW$DIETY\fR intended.
 208 .PP
 209 Assumes all character codes >= 127 need to be escaped as hex codes, ie that the
 210 user's terminal is \s-1ASCII\s0, and not even \*(L"high bit \s-1ASCII\s0\*(R", capable.  This can be
 211 made an option when the need arises.
 212 .PP
 213 Assumes that control codes (character codes 0..31) that don't have slash-letter
 214 escapes (\*(L"\en\*(R", \*(L"\er\*(R", etc) in Perl are best presented as hex escapes (\*(L"\ex01\*(R")
 215 instead of octal (\*(L"\e001\*(R") or control-code (\*(L"\ecA\*(R") escapes.
 216 .SH "AUTHOR"
 217 .IX Header "AUTHOR"
 218 Barrie Slaymaker <barries@slaysys.com>
 219 .SH "LICENSE"
 220 .IX Header "LICENSE"
 221 Copyright 2001 Barrie Slaymaker, All Rights Reserved.
 222 .PP
 223 You may use this software under the terms of the \s-1GNU\s0 public license, any
 224 version, or the Artistic license.