Getting Started

See the resources section in META.yml or Build.PL 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.

Formatting

perltidy

The project comes with a .perltidyrc, 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:

vim

In .vimrc, you can add the following lines:

nnoremap <Leader>pt :%!perltidy -q<cr> " only work in 'normal' mode
vnoremap <Leader>pt :!perltidy -q<cr> " only work in 'visual' mode

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

Documentation

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

Pod Commands

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

=head1 SECTION

Sections begin with an =head1 command and are all-caps.

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

=head2 method

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

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).

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

Pod Formatting Codes

L<Some::Module>

Be careful of the wording of L<Some::Module>. Older pod formatters would render this as "the Some::Module manpage", so it is best to either word your links as "(see <Some::Module> for details.)" or use the "explicit rendering" form of "<Some::Module|Some::Module>".