NAME

Pod::Knit::Manual - manual for the Pod::Knit system

VERSION

version 0.0.1

DESCRIPTION

I love Dist::Zilla and I adore the doc-munging that Pod::Weaver does. I'm, however, scared of its Pod::Elemental guts. Hence Pod::Knit, which is also a system to transform POD, but does it using an XML representation of the document.

Using Pod::Knit

To use Pod::Knit, you need a knit.yml configuration file. That file has two main sections: the plugins section listing all the plugins that you want to use, and the optional stash section holding any variable you may want to pass to the knitter.

E.g.,

---
stash:
    author: Yanick Champoux <yanick@cpan.org>
plugins:
    - Abstract
    - Attributes
    - Methods
    - NamedSections:
        sections:
            - synopsis
            - description
    - Version
    - Authors
    - Legal
    - Sort:
        order:
        - NAME
        - VERSION
        - SYNOPSIS
        - DESCRIPTION
        - ATTRIBUTES
        - METHODS
        - '*'
        - AUTHORS
        - AUTHOR
        - COPYRIGHT AND LICENSE

Note that the plugins will be applied to the POD in the order in which they appear in the configuration file.

Then in that directory, use the script podknit to munge a POD or Perl file.

$ podknit lib/My/Module.pm 

Magic!

Using Pod::Knit with Dist::Zilla

See Dist::Zilla::Plugin::PodKnit.

Writing a Pod::Knit plugin

The documentation of Pod::Knit::Plugin should give you a good idea how to do that. Looking at already-existing plugins for inspiration is also recommended.

AUTHOR

Yanick Champoux <yanick@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2018 by Yanick Champoux.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

Full text of the license can be found in the LICENSE file included in this distribution.