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.

• emacs

  For emacs, you can use this snippet from Sam Tregar (<http://use.perl.org/~samtregar/journal/30185>):

   (defun perltidy-region ()
      "Run perltidy on the current region."
      (interactive)
      (save-excursion
        (shell-command-on-region (point) (mark) "perltidy -q" nil t)
        (cperl-mode)))
   (defun perltidy-all ()
      "Run perltidy on the current region."
      (interactive)
      (let ((p (point)))
        (save-excursion
          (shell-command-on-region (point-min) (point-max) "perltidy -q" nil t)
          )
        (goto-char p)
        (cperl-mode)))
   (global-set-key "\M-t" `perltidy-region)
   (global-set-key "\M-T" `perltidy-all)
      

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

  =head2 this_method
  This method does some blah blah blah.
    my @answer = $thing->this_method(@arguments);
  =head2 that_thing
  Returns true if the thing is true.
    if($thing->that_thing) {
      ...
    }
    

"=item parameter"

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

VERSION

The version numbers are updated by Perl::Version.

DEVELOPER DOCS/NOTES

The following "formats" are used with "=begin"/"=end" and "=for" commands for pod which is not part of the public end-user/API documentation.

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

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
    

deprecated

  =for deprecated
    removed in 0.09, kill by ~0.25