[% setvar title Examples encoded with %]

This file is part of the Perl 6 Archive

Note: these documents may be out of date. Do not use as reference!

To see what is currently happening visit http://www.perl6.org/

TITLE

Examples encoded with =also for|begin|end POD commands

VERSION

  Maintainer: Barrie Slaymaker <barries@slaysys.com>
  Date: 2 Aug 2000
  Last Modified: 1 Oct 2000
  Mailing List: perl-qa@perl.org
  Number: 11
  Version: 2
  Status: Frozen

ABSTRACT

Note: written in the present tense, though =also, Pod::Tests, and pod2tests are not yet implemented.

The =also for|begin|end commands are shorthand having two copies of a section of POD (typically an example), one normal copy, and one delimited by =for or =begin ...=end. This supports semi-literate programming techniques, allowing examples in POD to be extracted and tested. It does not affect normal compilation of the source code, though older POD parsers may emit warnings.

DESCRIPTION

Many existing programs and modules include POD examples demostrating how too use the command or API provided. These examples are rarely tested or maintained, and can lead to lost time on the part of the module's or program's users.

Extracting these examples using Pod::Tests (usually by running pod2tests) on the source file and emitting them as test scripts provides a service both to the POD user and to the code maintainer.

The =also tag allows extractors like Pod::Tests to select exactly the same text that the POD user sees, so that the code maintainer can be sure that the documentation is at least partially correct.

Technically, a feature like this could be used to support literate programming of a modules' source code, but that is not the intent of the =also tag.

Example

The =also tag, in combination with special purpose parsers, allows a Pod::Parser based pod2text to process POD like:

  =item run

  =for test run.t
     #!perl -w
     use Test ;
     use IPC::Run qw( run ) ;
     $cmd = $^X ;
     @args = ( '-e', 'print "hello world\n"' ) ;
     ( $in, $out, $err ) = ('') x 3 ;
     plan tests => 2 ;

  =also for test run.t
     $r = run( [$cmd, @args], \$in, \$out, \$err ) ;

  =for test run.t
     ok( $out, "hello world\n" ) ;
     ok( $err, "" ) ;

  The run() method blah, blah, blah...

  =cut

  sub run {
     ...
  }

and provide output like:

    run
    
       $r = run( [$cmd, @args], \$in, \$out, \$err ) ;
    
    The run() method blah, blah, blah...

. It also allows pod2tests to process the same POD and produce a test script t/run.t containing code like

  #!perl -w
     use Test ;
     use IPC::Run qw( run ) ;
     $cmd = $^X ;
     @args = ( '-e', 'print "hello world\n"' ) ;
     ( $in, $out, $err ) = ('') x 3 ;
     plan tests => 2 ;
     $r = run( [$cmd, @args], \$in, \$out, \$err ) ;
     ok( $out, "hello world\n" ) ;
     ok( $err, "" ) ;

The '#line' directives are not shown in this example script for clarity.

IMPLEMENTATION

The =also command is implemented in Pod::Parser in a process called "=also mangling". This process passes the marked regions to the Pod::Parser handlers twice, once in "plain POD" mode, which looks to the handlers exactly as though the lines beginning with =also weren't present, and then a second time in "=for/=begin" mode, as though they were enclosed by =for, =begin, and =end commands.

This means that each paragraph marked as =also for foo results in two calls, the first to verbatim() or textblock(), and the second to command(), with a command value of '=for'.

Paragraph sequences bounded by =also begin foo and =also end foo are passed when parsed to verbatim() or textblock() as they are parsed.

They are also accumulated until the =also end foo tag is found. The command() handler is then called with a command value of "=begin", followed by a duplicate series of calls to verbatim() and textblock(), followed by a call to command() with a command value of "=end".

If needed at some future point, an option can be added to Pod::Parser to make it treat =also as a normal command, as can a "mangle_also" property to discover if =also mangling is supported (via can()) and to query or set the mangling option.

Pod::Parser based translators that generate documentation (all "normal" pod translators) ignore the second "=for/=begin" version of the =also paragraphs and only emit output for the "as plain POD" calls. See below for why using =also to direct paragraphs to such processors is a Bad Idea.

Pod::Parser based processors that extract only those POD segments =for them ignore anything not intended for them, so they ignore the first "plain POD" set of calls generated by =also sections and only see the second "=for/=begin" version.

This duplicitous subterfuge is a bit awkward, but it was designed to allow the "=also" command handling to be added only to Pod::Parser and to not affect existing parsers.

Compatibility with =for html, =for text, etc.

Using =also to flag sections for documentation translators is a mistake. For example, a command =also for html <P>blah will cause POD to HTML translators to output something like "&lt;P&gt;blah<P>blah", which makes for confusing reading.

Backwards Compatibility

Using the =also tag can cause older parser to emit "unrecognized directive" warnings and possibly may cause them to exit prematurely.

The solution is to upgrade to Pod::Parser based translators if possible, or to ignore the warnings if not. If the translator in question exits prematurely and an upgrade is not possible, it will need to be patched.

REFERENCES

  RFC ??: "=for test and pod2test"
  perlpod manpage
  Pod::Parser