DOCUMENTING PBSFILES AND PBS MODULES

Pbsfiles are documented using POD. See man perlpod for a complete reference.

PBS has commands to help you extract POD documentation from your Pbsfiles. Comments, starting with '#', are not POD and thus not extracted.

Two types of POD can be embedded in Pbsfiles pr PBS modules.

POD documenting how to use the Pbsfile

Documenting how to use a Pbsfile is most often used to help the user find out which targets are defined and how to invokethe PBS command line utility (pbs). The output is filtered through pod2text for your convenience.

Extracting the POD:

  pbs --pbsfile_pod 
  pbs --pp

Pbsfile pod start withB=for PBS followed by a =head tag. It ends when PBS either finds:

• a =head tag of a higher level

• =for PBS STOP is found.

You can interleave Pbsfile documentation and structural documentation if you so wish.

POD documenting the structure of the Pbsfile

The structural documentation is the development documentation. It is used to explain the Pbsfile structure to the build system maintainers.

This is normal POD. pbs will extract this type of document when the --pbs2pod switch is given to pbs. The output is also filtered through pod2text.

Extracting the POD:

  pbs --pbs2pod

Generating HTML and other formats

When given the --raw_pod switch, pbs will not filter the POD with pod2text. This allows you to use any of the POD filters available on CPAN.

  pbs --pbs2pod --raw_pod | pod2html > structure_documentation.html

Example

  =for PBS =head1 PBSFILE HELP
  
  =head2 Simple Java build one class example
  
  =head2 Targets
  
  =over 2 
  
  =item * all
  
  =back
  
  =for PBS STOP
  
  This section was not necessary as the next =head tag has higher level. This 
  sections content will not be extracted.
  
  =cut
  
  #-------------------------------------------------------------
  
  =head1 Structural documentation
  
  We let PBS know that B<.java> files are considered source code.
  
  =cut
  
  ExcludeFromDigestGeneration('java-files' => qr/\.java$/);
  
  #-------------------------------------------------------------
  
  my @classes = qw(HelloWorld.class) ;
  
  =head1 Rules
  
  =head2 all
  
  We declare a rule to match the I<all> target. This is a convenience rule
  as we could build I<HelloWorld.class> directly from the command line.
  
  =cut
  
  ...