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

[Kieren Diment]

Hi,

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);'

Thanks.

Kieren