search

markpitchless / moosex-getopt-usage

Perl Moose Role to use with MooseX::Getopt to generate a coloured usage message from your classes meta
2 stars 2 forks source link

Integrate Pod::Usage #2

Open markpitchless opened 12 years ago

markpitchless commented 12 years ago

This will add a --man option that generates the man page from the POD using getopt usage. Include generated pod from the meta info ie inject a USAGE section.

Read the USAGE section from the POD for use in the message generated via --help. Allow pod to be used as the format setting in effect.

Must be done with minimal dependancies on the install side. No pulling a load of POD weaving mods just for this. However we really want the generated pod to go into the man page generated at install time, which could be achieved with more author side deps.

On 17 March 2012 16:09, Tomas Doran bobtfish@bobtfish.net wrote:

You provide some way for FooBarModule.pm to provide metadata about which pod sections are prepends/appends to the script manual + what section to rewrite in this doc (probably by adding a =for block of some sort), you then write a DZ pluginbundle which strips the custom markup from FooBarModule.pm and uses it to weave Pod generated for the attributes with parts of the docs.

You can have multiple strategies here - e.g. you update an attributes section in the original doc, or only in the target module, and/or you could weave a completely independent FooBarModule/ScriptHelp.pod - which could later be pod2text'd by --help if present, so that you don't need any of the additional pod tools at the user end but can still have a subset of the full module docs as the --help..

markpitchless commented 12 years ago

Started work on this in the pod-usage branch.

markpitchless commented 11 years ago

First bit is done, --man works and POD sections get read to generate the the full message. Man is generated at run time from the meta data.

So now just need a way to build the POD at build time as well.