view release on metacpan or  search on metacpan

lib/Pod/Weaver/Plugin/Ditaa.pm  view on Meta::CPAN

=head1 VERSION

version 0.001006

=head1 SYNOPSIS

In your F<weaver.ini>:

 [@Default]
 [-Ditaa]

In the pod of one of your modules:

 =head1 HOW IT WORKS

 =begin ditaa

 label: How it works

    +--------+   +-------+    +-------+
    |        | --+ ditaa +--> |       |
    |  Text  |   +-------+    |diagram|
    |Document|   |!magic!|    |       |
    |     {d}|   |       |    |       |
    +---+----+   +-------+    +-------+
        :                         ^
        |       Lots of work      |
        +-------------------------+

 =end ditaa

=head1 DESCRIPTION

It has often been said that a picture is worth a thousand words.  I find that
sometimes a diagram truly can illuminate your design.  This L<Pod::Weaver>
plugin allows you to put L<ditaa|http://ditaa.sourceforge.net/> diagrams in your
pod and render the image for an html view.  In text mode it merely uses the text
diagram directly.

Note that you may put a C<label: Foo> at the top of your diagram, but if you
do not you will get a numbered label in the format C<Figure $i>.

=head1 IN ACTION

=begin text

How it works

   +--------+   +-------+    +-------+
   |        | --+ ditaa +--> |       |
   |  Text  |   +-------+    |diagram|
   |Document|   |!magic!|    |       |
   |     {d}|   |       |    |       |
   +---+----+   +-------+    +-------+
       :                         ^
       |       Lots of work      |
       +-------------------------+

=end text

=for html <p><i>How it works</i><img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAaQAAAC2CAIAAAAZR25GAAAWmElEQVR42u2deUxUVxuHXdgRVBalFBdwjWmF1q0CdaXR2NiotW7VqHRRE1uTVpPa2qrVxLhUbdOmVVtRi1ZEFhWLoKLI0iqIsqkoIAyCQBUQRMDl8/t9nHi/KQOXEcZh5s7v+YPce+...

=head1 SYNTAX

The ditaa syntax L<is documented here|http://ditaa.sourceforge.net/#usage>.

=head1 PASSING FLAGS TO DITAA

 =begin ditaa -r -S

 label: Passing Flags

    +--------+
    |        |
    |  Test  |
    |        |
    +---+----+

 =end ditaa

=begin text

Passing Flags

    +--------+
    |        |
    |  Test  |
    |        |
    +---+----+

=end text

=for html <p><i>Passing Flags</i><img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAALQAAAB+CAIAAAAC3Ky3AAADsUlEQVR42u3dv0sycRzAcSOR6IcIGYYoJEQ0ODg01aVCDg4ODS5FETU1BK0Njg39CQ5BBkWCQy6Km5RBgYOQkENBFJX9gCIcrIae5wP3oE/PYy3PNTx37/d2d17g19fd974gafpB9...

To pass flags to C<ditaa> simply append the flags to the C<< =begin ditaa >>
directive.

=head1 DEBUGGING

Set the C<DITAA_TRACE> env var and you'll see all of the commands that this
plugin runs printed to C<STDERR>.  If you set the env var to C<keep> the
temporary files referenced in the command will not automatically be deleted, so
you can ensure that the text and image diagrams were created correctly.

=head1 PERL SUPPORT POLICY

Because this module is geared towards helping release code, as opposed to
helping run code, I only aim at supporting the last 3 releases of Perl.  So for
example, at the time of writing that would be 5.22, 5.20, and 5.18.  As an
author who is developing against Perl and using this to release modules, you can
use either L<perlbrew|http://perlbrew.pl/> or
L<plenv|https://github.com/tokuhirom/plenv> to get a more recent perl for
building releases.

Don't bother sending patches to support older versions; I could probably support
5.8 if I wanted, but this is more so that I can continue to use new perl
features.

=head1 AUTHOR

Arthur Axel "fREW" Schmidt <frioux+cpan@gmail.com>