On Fri, Apr 29, 2005 at 12:16:40AM +0100, Robert Rothenberg wrote:
>
> =begin readme include in README as POD
> =begin readme pod same as above
> =begin readme plain include in README as plaintext
>
> =for readme commands commands for the README parser,
> some examples:
>
> =for readme stop stop including POD in readme
> =for readme continue continue including readme
>
> =for readme include plain file
> =for readme include pod file
> include a plaintext or pod file
>
> =for readme include plain file mark
> =for readme include pod file mark
> include a text file until "mark" occurs?
>
> =for readme requirements insert a =head1 REQUIREMENTS section
> which parses the META.yml for non-core
> requirements
>
> =for readme install inserts a =head1 INSTALLATION section
> which can tell if there's Makefile.PL,
> Build.PL or both; also parses the
> build_requires section of META.yml and
> notes these
I really don't want to do any extra work to generate the README file.
Currently I'm happy with what Module::Build provides:
create_readme
This parameter tells Module::Build to automatically create a
README file at the top level of your distribution. Currently
it will simply use "Pod::Text" on the file indicated by
"dist_version_from" and put the result in the README file.
This is by no means the only recommended style for writing a
README, but it seems to be one common one used on the CPAN.
Beyond that, I wouldn't mind a little more boiler or auto-generated
information, but I really want it to be That Easy.
I would also just assume stick with what Module::Build provides unless
the alternative was significantly better and just as easy.
If your concern is about making a module that is widely used, I think
it's important to find out: How much effort to do people usually want to
put into a README file? Do they want the generation to be dead-simple /
automatic, or are they willing to configure it more to have a more
customized or powerful solution? I definitely fall into the first camp.
Mark
