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
_______________________________________________
List: Catalyst@lists.scsys.co.uk
Listinfo: http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst
Searchable archive: http://www.mail-archive.com/catalyst@lists.scsys.co.uk/
Dev site: http://dev.catalyst.perl.org/
