[Catalyst] IMPORTANT: To all Catalyst::Whatever Authors, please read and ACT

[Ashley]

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.

-Ashley