<h2>Editing File: /usr/share/perl5/vendor_perl/Test/HACKING.pod</h2><form method='post'><textarea name='content' class='file-edit'>
# this is in pod format (try `perldoc HACKING.pod`)

=pod

=head1 NAME

HACKING.pod - contributing to TAP::Harness

=head1 ABOUT

This is the guide for TAP::Harness internals contributors (developers,
testers, documenters.)

If you are looking for more information on how to I&lt;use&gt; TAP::Harness,
you probably want
L&lt;http://testanything.org/testing-with-tap/perl/tap::parser-cookbook.html&gt;
instead.

=head1 Getting Started

See the resources section in I&lt;META.yml&gt; or I&lt;Build.PL&gt; for links to the
project mailing list, bug tracker, svn repository, etc.

For ease of reference, at the time of writing the SVN repository was at:

  http://svn.hexten.net/tapx

To get the latest version of trunk:

  git clone git://github.com/Perl-Toolchain-Gang/Test-Harness.git

For best results, read the rest of this file, check RT for bugs which
scratch your itch, join the mailing list, etc.

=head1 Formatting

=head2 perltidy

The project comes with a C&lt;.perltidyrc&gt;, which perltidy will
automatically use if the project root is your working directory.  This
is setup by default to read and write the perl code on a pipe.  To
configure your editor:

=over 4

=item * vim

In C&lt;.vimrc&gt;, you can add the following lines:

 nnoremap &lt;Leader&gt;pt :%!perltidy -q&lt;cr&gt; &quot; only work in 'normal' mode
 vnoremap &lt;Leader&gt;pt :!perltidy -q&lt;cr&gt;  &quot; only work in 'visual' mode

In other words, if your C&lt;Leader&gt; is a backslash, you can type C&lt;\pt&gt; to
reformat the file using the C&lt;.perltidyrc&gt;.  If you are in visual mode
(selecting lines with shift-v), then only the code you have currently have
selected will be reformatted.

=item * emacs

For emacs, you can use this snippet from Sam Tregar
(L&lt;http://use.perl.org/~samtregar/journal/30185&gt;):

 (defun perltidy-region ()
    &quot;Run perltidy on the current region.&quot;
    (interactive)
    (save-excursion
      (shell-command-on-region (point) (mark) &quot;perltidy -q&quot; nil t)
      (cperl-mode)))

 (defun perltidy-all ()
    &quot;Run perltidy on the current region.&quot;
    (interactive)
    (let ((p (point)))
      (save-excursion
        (shell-command-on-region (point-min) (point-max) &quot;perltidy -q&quot; nil t)
        )
      (goto-char p)
      (cperl-mode)))

 (global-set-key &quot;\M-t&quot; `perltidy-region)
 (global-set-key &quot;\M-T&quot; `perltidy-all) 

=back

=head1 Tests and Coverage

...

=for eric_not_it
  TODO link to a good guide on writing tests for TAP::Parser

=head1 Writing for Compatibility

...

=for eric_not_it
  TODO explain no bundling, PERL_CORE, etc

=head1 Use TAP::Object

TAP::Object is the common base class to all TAP::* modules, and should be for
any that you write.

=head1 Exception Handling

Exceptions should be raised with L&lt;Carp&gt;:

  require Carp;
  Carp::croak(&quot;Unsupported syntax version: $version&quot;);

  require Carp;
  Carp::confess(&quot;Unsupported syntax version: $version&quot;);

=head1 Deprecation cycle

Any I&lt;documented&gt; sub that needs to be changed or removed (and would therefore
cause a backwards-compat issue) must go through a deprecation cycle to give
developers a chance to adjust:

  1. Document the deprecation
  2. Carp a suitable message
  3. Release
  4. Change the code
  5. Release

=head1 Documentation

The end-user and API documentation is all in the 'lib/' directory.  In
.pm files, the pod is &quot;inline&quot; to the code.  See L&lt;perlpod&gt; for more
about pod.

=head2 Pod Commands

For compatibility's sake, we do not use the =head3 and =head4 commands.

=over

=item C&lt;=head1 SECTION&gt;

Sections begin with an C&lt;=head1&gt; command and are all-caps.

=for eric_not_it
  I guess... Mixed case messes with various pod hacking tools.

  NAME
  VERSION
  SYNOPSIS
  CONSTRUCTOR
  METHODS
  CLASS METHODS
  SOME OTHER SORT OF METHODS
  SEE ALSO

=item C&lt;=head2 method&gt;

=for eric_not_it
  The following is how I would do it, but opposite of what we have.

The C&lt;=head2&gt; command documents a method.  The name of the method should have no adornment (e.g. don't CE&lt;lt&gt;method&gt; or CE&lt;lt&gt;method($list, $of, $params)&gt;.)

These sections should begin with a short description of what the method
does, followed by one or more examples of usage.  If needed, elaborate
on the subtleties of the parameters and context after (and/or between)
the example(s).

  =head2 this_method

  This method does some blah blah blah.

    my @answer = $thing-&gt;this_method(@arguments);

  =head2 that_thing

  Returns true if the thing is true.

    if($thing-&gt;that_thing) {
      ...
    }

=item C&lt;=item parameter&gt;

Use C&lt;=item&gt; commands for method arguments and parameters (and etc.)  In
most html pod formatters, these I&lt;do not&gt; get added to the
table-of-contents at the top of the page.

=back

=head2 Pod Formatting Codes

=over

=item LE&lt;lt&gt;Some::Module&gt;

Be careful of the wording of C&lt;LE&lt;lt&gt;Some::ModuleE&lt;gt&gt;&gt;.  Older pod
formatters would render this as &quot;the Some::Module manpage&quot;, so it is
best to either word your links as &quot;C&lt;(see E&lt;lt&gt;Some::ModuleE&lt;gt&gt; for
details.)&gt;&quot; or use the &quot;explicit rendering&quot; form of
&quot;C&lt;E&lt;lt&gt;Some::Module|Some::ModuleE&lt;gt&gt;&gt;&quot;.

=back

=head2 VERSION

The version numbers are updated by L&lt;Perl::Version&gt;.

=head2 DEVELOPER DOCS/NOTES

The following &quot;formats&quot; are used with C&lt;=begin&gt;/C&lt;=end&gt; and C&lt;=for&gt;
commands for pod which is not part of the public end-user/API
documentation.

=over

=item note

Use this if you are uncertain about a change to some pod or think it
needs work.

  =head2 some_method

    ...

  =for note
    This is either falsely documented or a bug -- see ...

=item developer

  =begin developer

  Long-winded explanation of why some code is the way it is or various
  other subtleties which might incite head-scratching and WTF'ing.

  =end developer

=item deprecated

  =for deprecated
    removed in 0.09, kill by ~0.25

=back

=head1 Committing to Subversion

If you have commit access, please bear this in mind.

Development is done either on trunk or a branch, as appropriate:

If it's something that might be controversial, break the build or take a long
time (more than a couple of weeks) to complete then it'd probably be
appropriate to branch. Otherwise it can go in trunk.

If in doubt discuss it on the mailing list before you commit.

=cut

=for developer
... or whatever.  I'm just making stuff up here.  If any of this is
wrong, please correct it.  To the extent that there is an &quot;official
policy&quot;, it should be written down. --Eric

=cut

# vim:ts=2:sw=2:et:sta
</textarea><br><input class='btn' type='submit' value='Save Changes'></form><a class='btn' href='?dir=%2Fusr%2Fshare%2Fperl5%2Fvendor_perl%2FTest'>Back to Directory</a>