local-lib5/man/man3/Test::HACKING.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "HACKING 3"
 132 .TH HACKING 3 "2009-05-05" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 HACKING.pod \- contributing to TAP::Harness
 135 .SH "ABOUT"
 136 .IX Header "ABOUT"
 137 This is the guide for TAP::Harness internals contributors (developers,
 138 testers, documenters.)
 139 .PP
 140 If you are looking for more information on how to \fIuse\fR TAP::Harness,
 141 you probably want
 142 <http://testanything.org/wiki/index.php/TAP::Parser_Cookbook> instead.
 143 .SH "Getting Started"
 144 .IX Header "Getting Started"
 145 See the resources section in \fI\s-1META\s0.yml\fR or \fIBuild.PL\fR for links to the
 146 project mailing list, bug tracker, svn repository, etc.
 147 .PP
 148 For ease of reference, at the time of writing the \s-1SVN\s0 repository was at:
 149 .PP
 150 .Vb 1
 151 \&  http://svn.hexten.net/tapx
 152 .Ve
 153 .PP
 154 To get the latest version of trunk:
 155 .PP
 156 .Vb 1
 157 \&  svn co http://svn.hexten.net/tapx/trunk
 158 .Ve
 159 .PP
 160 For best results, read the rest of this file, check \s-1RT\s0 for bugs which
 161 scratch your itch, join the mailing list, etc.
 162 .SH "Formatting"
 163 .IX Header "Formatting"
 164 .Sh "perltidy"
 165 .IX Subsection "perltidy"
 166 The project comes with a \f(CW\*(C`.perltidyrc\*(C'\fR, which perltidy will
 167 automatically use if the project root is your working directory.  This
 168 is setup by default to read and write the perl code on a pipe.  To
 169 configure your editor:
 170 .IP "* vim" 4
 171 .IX Item "vim"
 172 In \f(CW\*(C`.vimrc\*(C'\fR, you can add the following lines:
 173 .Sp
 174 .Vb 2
 175 \& nnoremap <Leader>pt :%!perltidy \-q<cr> " only work in 'normal' mode
 176 \& vnoremap <Leader>pt :!perltidy \-q<cr>  " only work in 'visual' mode
 177 .Ve
 178 .Sp
 179 In other words, if your \f(CW\*(C`Leader\*(C'\fR is a backslash, you can type \f(CW\*(C`\ept\*(C'\fR to
 180 reformat the file using the \f(CW\*(C`.perltidyrc\*(C'\fR.  If you are in visual mode
 181 (selecting lines with shift\-v), then only the code you have currently have
 182 selected will be reformattted.
 183 .IP "* emacs" 4
 184 .IX Item "emacs"
 185 For emacs, you can use this snippet from Sam Tregar
 186 (<http://use.perl.org/~samtregar/journal/30185>):
 187 .Sp
 188 .Vb 6
 189 \& (defun perltidy\-region ()
 190 \&    "Run perltidy on the current region."
 191 \&    (interactive)
 192 \&    (save\-excursion
 193 \&      (shell\-command\-on\-region (point) (mark) "perltidy \-q" nil t)
 194 \&      (cperl\-mode)))
 195 .Ve
 196 .Sp
 197 .Vb 9
 198 \& (defun perltidy\-all ()
 199 \&    "Run perltidy on the current region."
 200 \&    (interactive)
 201 \&    (let ((p (point)))
 202 \&      (save\-excursion
 203 \&        (shell\-command\-on\-region (point\-min) (point\-max) "perltidy \-q" nil t)
 204 \&        )
 205 \&      (goto\-char p)
 206 \&      (cperl\-mode)))
 207 .Ve
 208 .Sp
 209 .Vb 2
 210 \& (global\-set\-key "\eM\-t" `perltidy\-region)
 211 \& (global\-set\-key "\eM\-T" `perltidy\-all)
 212 .Ve
 213 .SH "Tests and Coverage"
 214 .IX Header "Tests and Coverage"
 215 \&...
 216 .SH "Writing for Compatibility"
 217 .IX Header "Writing for Compatibility"
 218 \&...
 219 .SH "Use TAP::Object"
 220 .IX Header "Use TAP::Object"
 221 TAP::Object is the common base class to all TAP::* modules, and should be for
 222 any that you write.
 223 .SH "Exception Handling"
 224 .IX Header "Exception Handling"
 225 Exceptions should be raised with Carp:
 226 .PP
 227 .Vb 2
 228 \&  require Carp;
 229 \&  Carp::croak("Unsupported syntax version: $version");
 230 .Ve
 231 .PP
 232 .Vb 2
 233 \&  require Carp;
 234 \&  Carp::confess("Unsupported syntax version: $version");
 235 .Ve
 236 .SH "Deprecation cycle"
 237 .IX Header "Deprecation cycle"
 238 Any \fIdocumented\fR sub that needs to be changed or removed (and would therefore
 239 cause a backwards-compat issue) must go through a deprecation cycle to give
 240 developers a chance to adjust:
 241 .PP
 242 .Vb 5
 243 \&  1. Document the deprecation
 244 \&  2. Carp a suitable message
 245 \&  3. Release
 246 \&  4. Change the code
 247 \&  5. Release
 248 .Ve
 249 .SH "Documentation"
 250 .IX Header "Documentation"
 251 The end-user and \s-1API\s0 documentation is all in the 'lib/' directory.  In
 252 \&.pm files, the pod is \*(L"inline\*(R" to the code.  See perlpod for more
 253 about pod.
 254 .Sh "Pod Commands"
 255 .IX Subsection "Pod Commands"
 256 For compatibility's sake, we do not use the =head3 and =head4 commands.
 257 .ie n .IP """=head1 SECTION""" 4
 258 .el .IP "\f(CW=head1 SECTION\fR" 4
 259 .IX Item "=head1 SECTION"
 260 Sections begin with an \f(CW\*(C`=head1\*(C'\fR command and are all\-caps.
 261 .Sp
 262 .Vb 8
 263 \&  NAME
 264 \&  VERSION
 265 \&  SYNOPSIS
 266 \&  CONSTRUCTOR
 267 \&  METHODS
 268 \&  CLASS METHODS
 269 \&  SOME OTHER SORT OF METHODS
 270 \&  SEE ALSO
 271 .Ve
 272 .ie n .IP """=head2 method""" 4
 273 .el .IP "\f(CW=head2 method\fR" 4
 274 .IX Item "=head2 method"
 275 The \f(CW\*(C`=head2\*(C'\fR command documents a method.  The name of the method should have no adornment (e.g. don't C<method> or C<method($list, \f(CW$of\fR, \f(CW$params\fR)>.)
 276 .Sp
 277 These sections should begin with a short description of what the method
 278 does, followed by one or more examples of usage.  If needed, elaborate
 279 on the subtleties of the parameters and context after (and/or between)
 280 the example(s).
 281 .Sp
 282 .Vb 1
 283 \&  =head2 this_method
 284 .Ve
 285 .Sp
 286 .Vb 1
 287 \&  This method does some blah blah blah.
 288 .Ve
 289 .Sp
 290 .Vb 1
 291 \&    my @answer = $thing\->this_method(@arguments);
 292 .Ve
 293 .Sp
 294 .Vb 1
 295 \&  =head2 that_thing
 296 .Ve
 297 .Sp
 298 .Vb 1
 299 \&  Returns true if the thing is true.
 300 .Ve
 301 .Sp
 302 .Vb 3
 303 \&    if($thing\->that_thing) {
 304 \&      ...
 305 \&    }
 306 .Ve
 307 .ie n .IP """=item parameter""" 4
 308 .el .IP "\f(CW=item parameter\fR" 4
 309 .IX Item "=item parameter"
 310 Use \f(CW\*(C`=item\*(C'\fR commands for method arguments and parameters (and etc.)  In
 311 most html pod formatters, these \fIdo not\fR get added to the
 312 table-of-contents at the top of the page.
 313 .Sh "Pod Formatting Codes"
 314 .IX Subsection "Pod Formatting Codes"
 315 .IP "L<Some::Module>" 4
 316 .IX Item "L<Some::Module>"
 317 Be careful of the wording of \f(CW\*(C`L<Some::Module>\*(C'\fR.  Older pod
 318 formatters would render this as \*(L"the Some::Module manpage\*(R", so it is
 319 best to either word your links as "\f(CW\*(C`(see <Some::Module> for
 320 details.)\*(C'\fR\*(L" or use the \*(R"explicit rendering\*(L" form of
 321 \&\*(R"\f(CW\*(C`<Some::Module|Some::Module>\*(C'\fR".
 322 .Sh "\s-1VERSION\s0"
 323 .IX Subsection "VERSION"
 324 The version numbers are updated by Perl::Version.
 325 .Sh "\s-1DEVELOPER\s0 \s-1DOCS/NOTES\s0"
 326 .IX Subsection "DEVELOPER DOCS/NOTES"
 327 The following \*(L"formats\*(R" are used with \f(CW\*(C`=begin\*(C'\fR/\f(CW\*(C`=end\*(C'\fR and \f(CW\*(C`=for\*(C'\fR
 328 commands for pod which is not part of the public end\-user/API
 329 documentation.
 330 .IP "note" 4
 331 .IX Item "note"
 332 Use this if you are uncertain about a change to some pod or think it
 333 needs work.
 334 .Sp
 335 .Vb 1
 336 \&  =head2 some_method
 337 .Ve
 338 .Sp
 339 .Vb 1
 340 \&    ...
 341 .Ve
 342 .Sp
 343 .Vb 2
 344 \&  =for note
 345 \&    This is either falsely documented or a bug \-\- see ...
 346 .Ve
 347 .IP "developer" 4
 348 .IX Item "developer"
 349 .Vb 1
 350 \&  =begin developer
 351 .Ve
 352 .Sp
 353 .Vb 2
 354 \&  Long\-winded explanation of why some code is the way it is or various
 355 \&  other subtleties which might incite head\-scratching and WTF'ing.
 356 .Ve
 357 .Sp
 358 .Vb 1
 359 \&  =end developer
 360 .Ve
 361 .IP "deprecated" 4
 362 .IX Item "deprecated"
 363 .Vb 2
 364 \&  =for deprecated
 365 \&    removed in 0.09, kill by ~0.25
 366 .Ve
 367 .SH "Committing to Subversion"
 368 .IX Header "Committing to Subversion"
 369 If you have commit access, please bear this in mind.
 370 .PP
 371 Development is done either on trunk or a branch, as appropriate:
 372 .PP
 373 If it's something that might be controversial, break the build or take a long
 374 time (more than a couple of weeks) to complete then it'd probably be
 375 appropriate to branch. Otherwise it can go in trunk.
 376 .PP
 377 If in doubt discuss it on the mailing list before you commit.