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

Ashley 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  


More information about the Catalyst mailing list