[Catalyst] IMPORTANT: To all Catalyst::Whatever Authors,
please read and ACT
apv at sedition.com
Sun May 11 01:56:41 BST 2008
On May 10, 2008, at 5:39 PM, Kieren Diment wrote:
> If you maintain a Catalyst::Plugin, View, Controller or anything
> else, please pay attention and address the following issue:
> YAML is not an appropriate configuration format for use in perldoc
> because both yaml and perldoc are sensitive to white space.
> Therefore they interact. Even worse they interact in different
> ways depending on the formatter being used.
> You may say that this is not important because people can just
> remove the indentation from the perldoc at the beginning of each
> line of the config, but this makes your module less usable for
> people, and *requires thought*.
> If using the trivial parts of your module requires thought, this is
> overhead for someone learning how to use your software which can be
> avoided (see http://en.wikipedia.org/wiki/Cognitive_load for details).
> So in your modules, Ideally you will provide provide both a
> __PACKAGE__->config(....) example, and an example using a
> serialisation format like Config::General (which is much harder to
> stuff up than yaml). If you're only going to provide one example
> though please don't make it YAML. If you don't want to have to
> maintain two config examples, then provide the __PACKAGE__
> declaration, which means at least us poor users can then do:
> perl -Ilib -e 'use MyApp; use Config::General; Config::General->new-
> >save_file("myapp.conf", MyApp->config);'
Two or more config examples is nice and kind to users and I think
it's a great best practice to include it (maybe someone would attach
a simple script to dump several formats? If I have time this weekend,
I'll try if no one beats me to it).
Arguing that users who cargo-cult their configs from POD deserve
coddling and MODULE AUTHORS MUST ACT TO AVERT THIS DISASTER is silly.
More information about the Catalyst