[Templates-cvs] cvs commit: TT3/docs modules.pod podspec.pod

[cvs@template-toolkit.org]

cvs         04/12/13 13:09:35

  Added:       docs     modules.pod podspec.pod
  Log:
  * added new documents describing modules and POD specification
  
  Revision  Changes    Path
  1.1                  TT3/docs/modules.pod
  
  Index: modules.pod
  ===================================================================
  =head1 Template Modules
  
  This document gives a brief overview of the many different 
  modules that comprise the Template Toolkit.
  
  Modules are added as and when they are fully completed, including
  code, tests and documentation.
  
  The fact that a module doesn't appear in this list is not necessarily
  an indication that it isn't yet complete, but more likely that it just
  hasn't been through a final inspection and added to this
  documentation.
  
  However, you can be reasonably well assured that the modules that do
  appear below are now fit for public consumption.
  
  =head2 Template::Base
  
  This module implements a base class from which most (if not all) other
  Template Template modules are derived.  It implements a C<new()>
  method for constructing objects and a default C<init()> method for
  initialisation (this is the method that most subclasses redefine to
  handle object creation).  It provides a number of other general
  purpose methods for error reporting, (C<error()>, C<error_msg()>,
  C<decline()>, C<throw()>), debugging C<debug(), C<dump()>,
  C<dump_xxxx()>), and various miscellaneous tasks (C<version()>,
  C<pkgvar()>, C<pkgvars()>, etc.)
  
  =head2 Template::Utils
  
  This module implement a number of useful utility methods, relating
  to the loading of Perl modules, reading and writing external files,
  and similar activities.
  
  
  
  
  1.1                  TT3/docs/podspec.pod
  
  Index: podspec.pod
  ===================================================================
  =head1 Template Toolkit POD Specification
  
  This document describes how the documentation for the Template Toolkit
  should be marked up using the POD format.
  
  =head2 Inline Code
  
  All inline code fragments should be quoted using C<...>.  Module names
  should not be quoted as such.
  
      blah blah blah the C<$foo> variable is passed to the
      Template::Module C<fetch()> method and so on
  
  =head2 Indenting Code Blocks
  
  All code blocks should be indented with four space characters, as
  shown in this example.
  
      my $foo = 10;
      print $foo;
  
  Any blanks lines in code blocks should be padded with one or more
  spaces, as shown notionally in the example below.
  
      sub foo {
          my $self = shift;
      [space]
          $self->do_something();
      [space]
          # more code...
      }
  
  POD processors split blocks on blank lines so without the spaces we end
  up with three separate code blocks.  A single space is enough to stop the
  processor from doing this and treat it as a single code block.  If you really
  do want two separate code blocks then do use a blank line.
  
      sub foo {
          my $self = shift;
      [space]                         # don't split here
          # more code...
      }
                                      # do split here
      sub foo {
          my $self = shift;
      [space]                         # don't split here
          $self->do_something();
      }