Mailing List Archive: Catalyst: Users

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

Index | Next | Previous | View Threaded

diment at gmail

May 10, 2008, 5:39 PM

Post #1 of 11 (93 views)
Permalink

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

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

_______________________________________________
List: Catalyst[at]lists.scsys.co.uk
Listinfo: http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst
Searchable archive: http://www.mail-archive.com/catalyst[at]lists.scsys.co.uk/
Dev site: http://dev.catalyst.perl.org/

apv at sedition

May 10, 2008, 5:56 PM

Post #2 of 11 (87 views)
Permalink

Re: IMPORTANT: To all Catalyst::Whatever Authors, please read and ACT [In reply to]

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

diment at gmail

May 10, 2008, 6:28 PM

Post #3 of 11 (87 views)
Permalink

Re: IMPORTANT: To all Catalyst::Whatever Authors, please read and ACT [In reply to]

On 11 May 2008, at 10:56, Ashley wrote:

> Arguing that users who cargo-cult their configs from POD deserve
> coddling and MODULE AUTHORS MUST ACT TO AVERT THIS DISASTER is silly.

No, users who don't understand how to use the code well enough that
they have to rely on the documentation need documentation that won't
confuse them with trivial stuff and unadvertised interaction bugs.
YAML in pod causes these bugs, which impacts on the learning curve
significantly, so please don't use it in documentation. If you're
still not convinced after reading http://en.wikipedia.org/wiki/
Cognitive_load then I'm happy to these issues off-list.

Your users are not you, they do not have your levels of
understanding, and they are guaranteed to go about understanding
things in a different way to the way that you did. Please keep
their cognitive overhead to a minimum so they can realise their
potential more quickly and easily.

_______________________________________________
List: Catalyst[at]lists.scsys.co.uk
Listinfo: http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst
Searchable archive: http://www.mail-archive.com/catalyst[at]lists.scsys.co.uk/
Dev site: http://dev.catalyst.perl.org/

dbix-class at trout

May 10, 2008, 6:44 PM

Post #4 of 11 (87 views)
Permalink

Re: IMPORTANT: To all Catalyst::Whatever Authors, please read and ACT [In reply to]

On Sat, May 10, 2008 at 05:56:41PM -0700, Ashley wrote:
> Arguing that users who cargo-cult their configs from POD deserve
> coddling and MODULE AUTHORS MUST ACT TO AVERT THIS DISASTER is silly.

There are several requests A DAY on #catalyst that come down to YAML
indentation mistakes.

If users are clearly repeatedly not getting this, it's time to change stuff.

If we do a 5.71 I think the catalyst.pl default should change then, and
then after a few months we file bugs against every distribution still
using YAML examples instead of code and/or .conf.

--
Matt S Trout Need help with your Catalyst or DBIx::Class project?
Technical Director http://www.shadowcat.co.uk/catalyst/
Shadowcat Systems Ltd. Want a managed development or deployment platform?
http://chainsawblues.vox.com/ http://www.shadowcat.co.uk/servers/

_______________________________________________
List: Catalyst[at]lists.scsys.co.uk
Listinfo: http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst
Searchable archive: http://www.mail-archive.com/catalyst[at]lists.scsys.co.uk/
Dev site: http://dev.catalyst.perl.org/

apv at sedition

May 10, 2008, 7:16 PM

Post #5 of 11 (87 views)
Permalink

Re: IMPORTANT: To all Catalyst::Whatever Authors, please read and ACT [In reply to]

On May 10, 2008, at 6:44 PM, Matt S Trout wrote:
> On Sat, May 10, 2008 at 05:56:41PM -0700, Ashley wrote:
>> Arguing that users who cargo-cult their configs from POD deserve
>> coddling and MODULE AUTHORS MUST ACT TO AVERT THIS DISASTER is silly.
>
> There are several requests A DAY on #catalyst that come down to YAML
> indentation mistakes.
>
> If users are clearly repeatedly not getting this, it's time to
> change stuff.
>
> If we do a 5.71 I think the catalyst.pl default should change then,
> and
> then after a few months we file bugs against every distribution still
> using YAML examples instead of code and/or .conf.

As I said, I'm all for more examples and even volunteered to write a
script to make it easy to sync them. It wouldn't be much fun to be
actively disallowed from using the example that I am going to
want to see or stub from when I run perldoc. I like helping others
but I write code primarily for myself. I know you don't like YAML,
Matt, but I do. I don't see that having a best practice of ... top 3?
configs is incompatible with the stated goal.

I believe YAML/POD is causing problems but since it's the most
used example it's simply going to be the most asked about whether
or not it's intrinsically problematic. If the docs only had
fragmentary XML
or Apache style confs, the irc would be getting plenty of questions
on those instead.

_______________________________________________
List: Catalyst[at]lists.scsys.co.uk
Listinfo: http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst
Searchable archive: http://www.mail-archive.com/catalyst[at]lists.scsys.co.uk/
Dev site: http://dev.catalyst.perl.org/

diment at gmail

May 10, 2008, 7:18 PM

Post #6 of 11 (87 views)
Permalink

Re: IMPORTANT: To all Catalyst::Whatever Authors, please read and ACT [In reply to]

On 11 May 2008, at 10:56, Ashley wrote:

> 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).

That on the other hand would be useful (sorry missed it first time).
Could you make a CatalystX::ConfigMaker that dumps catalyst_config.pl
into $PATH somewhere? CatalystX::Starter is a small and simple
module that shows how to do this.

_______________________________________________
List: Catalyst[at]lists.scsys.co.uk
Listinfo: http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst
Searchable archive: http://www.mail-archive.com/catalyst[at]lists.scsys.co.uk/
Dev site: http://dev.catalyst.perl.org/

apv at sedition

May 10, 2008, 8:55 PM

Post #7 of 11 (78 views)
Permalink

Re: IMPORTANT: To all Catalyst::Whatever Authors, please read and ACT [In reply to]

On May 10, 2008, at 7:18 PM, Kieren Diment wrote:
> On 11 May 2008, at 10:56, Ashley wrote:
>
>> 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).
>
> That on the other hand would be useful (sorry missed it first
> time). Could you make a CatalystX::ConfigMaker that dumps
> catalyst_config.pl into $PATH somewhere? CatalystX::Starter is a
> small and simple module that shows how to do this.

I'd love to try. I'll take a look this weekend. Thanks for pointing me
at the starter modules, I hadn't looked at it yet.

<devilsAdvocate type="tangent" for="MST" style="voice:facetious">
The biggest stumbling block and learning curve with Catalyst is almost
undeniably DBIC� Maybe we should consider a script that files tickets
against any documents that reference it going forward. I mean sure
it's useful but think of all the questions it generates! Why DBIC
users pollute the Catalyst list all the time and some of the devs even
cross post.
</devilsAdvocate>
_______________________________________________
List: Catalyst[at]lists.scsys.co.uk
Listinfo: http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst
Searchable archive: http://www.mail-archive.com/catalyst[at]lists.scsys.co.uk/
Dev site: http://dev.catalyst.perl.org/

orasnita at gmail

May 10, 2008, 10:13 PM

Post #8 of 11 (77 views)
Permalink

Re: IMPORTANT: To all Catalyst::Whatever Authors, please read and ACT [In reply to]

From: "Kieren Diment" <diment[at]gmail.com>
> No, users who don't understand how to use the code well enough that they
> have to rely on the documentation need documentation that won't confuse
> them with trivial stuff and unadvertised interaction bugs. YAML in pod
> causes these bugs, which impacts on the learning curve significantly, so
> please don't use it in documentation. If you're still not convinced
> after reading http://en.wikipedia.org/wiki/ Cognitive_load then I'm happy
> to these issues off-list.

The python/yaml style is also harder to understand by a blind Catalyst
programmer, because by default, the number of spaces in a text is not
spoken, so a piece of perl code would be prefered, and any programmer could
understand it and use whatever config module he likes.

Octavian

_______________________________________________
List: Catalyst[at]lists.scsys.co.uk
Listinfo: http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst
Searchable archive: http://www.mail-archive.com/catalyst[at]lists.scsys.co.uk/
Dev site: http://dev.catalyst.perl.org/

jon at jrock

May 10, 2008, 11:55 PM

Post #9 of 11 (77 views)
Permalink

Re: IMPORTANT: To all Catalyst::Whatever Authors, please read and ACT [In reply to]

* On Sun, May 11 2008, Ashley wrote:
> On May 10, 2008, at 7:18 PM, Kieren Diment wrote:
>> On 11 May 2008, at 10:56, Ashley wrote:
>>
>>> 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).
>>
>> That on the other hand would be useful (sorry missed it first time).
>> Could you make a CatalystX::ConfigMaker that dumps
>> catalyst_config.pl into $PATH somewhere? CatalystX::Starter is a
>> small and simple module that shows how to do this.
>
> I'd love to try. I'll take a look this weekend. Thanks for pointing me
> at the starter modules, I hadn't looked at it yet.
>
> <devilsAdvocate type="tangent" for="MST" style="voice:facetious">
> The biggest stumbling block and learning curve with Catalyst is almost
> undeniably DBIC… Maybe we should consider a script that files tickets
> against any documents that reference it going forward. I mean sure
> it's useful but think of all the questions it generates! Why DBIC
> users pollute the Catalyst list all the time and some of the devs even
> cross post.
> </devilsAdvocate>

You seem upset that we're ditching YAML. Don't be. The defaults are
designed for people that don't know how to change the defaults. You
already know how to use YAML, so use it and forget what everyone else
thinks. Config::General is not nearly as good as YAML, but it is harder
to completely fuck up; that's why we're changing to it. The idea is to
make it easier to not care for people who don't care :)

Personally, I'll be sticking with YAML. I will continue to recommend it
for people who are willing to learn the syntax. People complain that
Perl is "too hard" all the time, but it's only hard because they don't
know it. For those of us that know it, the things that make Perl hard
to learn make it easier to use. YAML is the same way. If you are
willing to accept that it has syntax, it will make your life easier. If
you religiously believe that configuration files don't have syntax, then
it's not the syntax for you :)

Regards,
Jonathan Rockway

--
print just => another => perl => hacker => if $,=$"

_______________________________________________
List: Catalyst[at]lists.scsys.co.uk
Listinfo: http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst
Searchable archive: http://www.mail-archive.com/catalyst[at]lists.scsys.co.uk/
Dev site: http://dev.catalyst.perl.org/

diment at gmail

May 11, 2008, 12:16 AM

Post #10 of 11 (74 views)
Permalink

Re: IMPORTANT: To all Catalyst::Whatever Authors, please read and ACT [In reply to]

On 11 May 2008, at 16:55, Jonathan Rockway wrote:

> You seem upset that we're ditching YAML. Don't be. The defaults are
> designed for people that don't know how to change the defaults. You
> already know how to use YAML, so use it and forget what everyone else
> thinks. Config::General is not nearly as good as YAML, but it is
> harder
> to completely fuck up; that's why we're changing to it. The idea
> is to
> make it easier to not care for people who don't care :)

Some programmers will find yaml better and easier for them in
configuring their app. However, almost everyone else will find yaml
obscure and difficult (especially non-programmers, configuring your
app). Anyway, the straw that broke the camels back was that I
realised this morning that it is not possible to put correct YAML in
POD. I was feeling motivated, so I took action.

_______________________________________________
List: Catalyst[at]lists.scsys.co.uk
Listinfo: http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst
Searchable archive: http://www.mail-archive.com/catalyst[at]lists.scsys.co.uk/
Dev site: http://dev.catalyst.perl.org/

dbix-class at trout

May 11, 2008, 7:29 AM

Post #11 of 11 (60 views)
Permalink

Re: IMPORTANT: To all Catalyst::Whatever Authors, please read and ACT [In reply to]

On Sat, May 10, 2008 at 07:16:44PM -0700, Ashley wrote:
> On May 10, 2008, at 6:44 PM, Matt S Trout wrote:
> >On Sat, May 10, 2008 at 05:56:41PM -0700, Ashley wrote:
> >>Arguing that users who cargo-cult their configs from POD deserve
> >>coddling and MODULE AUTHORS MUST ACT TO AVERT THIS DISASTER is silly.
> >
> >There are several requests A DAY on #catalyst that come down to YAML
> >indentation mistakes.
> >
> >If users are clearly repeatedly not getting this, it's time to
> >change stuff.
> >
> >If we do a 5.71 I think the catalyst.pl default should change then,
> >and
> >then after a few months we file bugs against every distribution still
> >using YAML examples instead of code and/or .conf.
>
>
> As I said, I'm all for more examples and even volunteered to write a
> script to make it easy to sync them. It wouldn't be much fun to be
> actively disallowed from using the example that I am going to
> want to see or stub from when I run perldoc. I like helping others
> but I write code primarily for myself. I know you don't like YAML,
> Matt, but I do. I don't see that having a best practice of ... top 3?
> configs is incompatible with the stated goal.

If you know YAML well enough to use it, you can translate the perl configs
anyway.

We had a week-long debate about config formats and the decision seemed to be
that C::G was going to be the default going forwards. The idea is the perl
config is the key one and the 'default conf format' example is to help
newbies.

--
Matt S Trout Need help with your Catalyst or DBIx::Class project?
Technical Director http://www.shadowcat.co.uk/catalyst/
Shadowcat Systems Ltd. Want a managed development or deployment platform?
http://chainsawblues.vox.com/ http://www.shadowcat.co.uk/servers/

_______________________________________________
List: Catalyst[at]lists.scsys.co.uk
Listinfo: http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst
Searchable archive: http://www.mail-archive.com/catalyst[at]lists.scsys.co.uk/
Dev site: http://dev.catalyst.perl.org/

Index | Next | Previous | View Threaded

Interested in having your list archived? Contact lists@gossamer-threads.com