Don't show declarator blocks with p6doc

Question

I've written a small example file to learn more about Perl 6 POD, and I'm using p6doc to render a small manual page from the POD document. However, p6doc also tries to parse the declarator blocks outside the POD document. This doesn't look particularly great in the output. Is there a way to ignore the declarator blocks when using p6doc?

The code sample I'm using is:

#! /usr/bin/env perl6

use v6.c;

#| Greet people on the command line.
sub MAIN (
    #| A name to greet.
    $names,

    #| Optional. Additional names to greet.
    *@names,
) {
    *
}

=begin pod

=NAME    greeter
=AUTHOR  Patrick Spek
=VERSION 0.0.1

The greeter application greets someone via a terminal. At least 1 name is
required, but multiple names can be given to greet many people in one go.
=end pod

And the output given by p6doc is:

sub MAIN(
    $names, # A name to greet.
    *@names, # Optional. Additional names to greet.
)
Greet people on the command line.

class $names
A name to greet.

class *@names
Optional. Additional names to greet.

NAME
greeter

AUTHOR
Patrick Spek

VERSION
0.0.1

The greeter application greets someone via a terminal. At least 1 name is
required, but multiple names can be given to greet many people in one go.

Everything before the NAME part is what I want to remove from the p6doc output.

Wavawave

Answer 1

declarator blocks outside the POD document.

A couple minor things that still seem worth a quick mention first:

• It's considered best practice to call it pod (or Pod or Pod6 or POD6) rather than POD to distinguish it from P5's POD because it's not backwards compatible, in the same way P6 isn't backwards compatible with P5;

• The syntax =begin pod ... =end pod doesn't declare "the pod document". It declares a pod block that's one of many that comprise the overall pod document. You can have several of them. And the reason for mentioning this is because declarator blocks are also pod blocks. This is why they get included.

Is there a way to ignore the declarator blocks when using p6doc?

You could run the output through a filter at the shell command level.

But see my next comment for what's likely a better way.

I'm using p6doc

p6doc is a wrapper around perl6 --doc.

perl6 --doc provides exactly the same result as you've shown in your question, but has an output post-processing option (and isn't limited to installed modules only).

Assuming you can switch to using perl6 --doc instead:

perl6 -doc, without an argument to the --doc option, uses the default pod output filter.

Using perl6 --doc=MyFilter.pm6 you can run the pod through an installed custom filter module Pod::To::MyFilter.pm6.

See a search of modules.perl6.org for pod::to for a full list of filters that you can use as examples.

Diaghilev

Are yo usure p6doc does the same as perl6 --doc? If I run both, the output on a pod document differs. The only difference I've spotted this far happens in a C<> construct, in perl6 --doc it appears as regular text, but with p6doc it's bold. – Wavawave

This appears to be the pertinent code. It conditionally uses either perl6 --doc ... or perl6 --doc=SectionFilter ... which latter uses this filter. So my current guess is that the difference you're seeing is related to these two ways of invoking perl6 --doc. – Diaghilev

Your pointers have been a great help, and I've work started on my own pod output filter. Right now it does a little more than just the filtering I originally wanted. – Wavawave