Short introduction to Pod introspection.

See issue #1907

Author: fluca1978

doc/Language/pod.pod6

@@ -574,6 +574,51 @@ multi MAIN(Bool :$man)
 
 Now C<myprogram --man> will output your Pod rendered as a man page.
 
+
+=head1 Accessing Pod
+
+In order to access Pod documentation from within a program
+it is required to use the special C<=> twigil, as documented
+in the L<variables section|/language/variables#The_=_Twigil>.
+
+The C<=> twigil provides the introspection over the Pod structure,
+providing a L<Pod::Block> tree root from which it is possible
+to access the whole structure of the Pod document.
+
+As an example, the following piece of code instrospects
+its own Pod documentaion:
+
+=begin code
+=begin pod
+
+=head1 This is an head1 title
+
+This is a paragraph.
+
+=begin code
+'Hello World'.say;
+=end code
+
+=end pod
+
+for $=pod -> $pod-item {
+    for $pod-item.contents -> $pod-block {
+      $pod-block.perl.say;
+    }
+}
+=end code
+
+producing the following output:
+
+=for code
+Pod::Heading.new(level => 1, config => {},
+                 contents => [Pod::Block::Para.new(config => {},
+                             contents => ["This is an head1 title"])])
+Pod::Block::Para.new(config => {}, contents => ["This is a paragraph."])
+Pod::Block::Code.new(allowed => [], config => {},
+                     contents => ["'Hello World'.say;", "\n"])
+
+
 =end pod
 
 # vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6