Re: [Catalyst] Catalyst-Devel Patch
I like the new section. Perfect! Thanks, Todd On Mon, Jul 21, 2008 at 9:10 AM, Ash Berlin <[EMAIL PROTECTED]> wrote: > > On 21 Jul 2008, at 14:37, Todd Rinaldo wrote: > >> J, Thanks for the detailed reply. I hadn't thought about the base >> class nature of this class. Catalyst and DBIC are both MAJOR >> development projects. This means their documentation on CPAN gets >> spread broadly over many pages. I admit this is not a problem for most >> modules on CPAN. I suppose my patch was specifically aimed at dealing >> with some of this. I have countless times asked questions on a >> list/IRC which was clearly documented on a page I'd reviewed multiple >> times. Once I knew where to look, the answer was easy. >> >> I am a major fan of wiki, as it's low entry barrier can make it easy >> for the people who most need the information (newbies) to append to >> the docs or clarify the docs once they get their answer. I'll take a >> look at the available wikis. When I'm done, I suspect my comment will >> be, well if this is the best place to put the docs on useability, >> shouldn't we point to it from the POD? This would effectivley allow us >> to separate the design specs related stuff (POD) from the practical >> use (WIKI). What are your thoughts on this approach? >> >> Todd > > Generally, the problem with the docs for Catalyst::Helper is that they are > only relevant if you are writing a new helper, not if you are trying to use > it. > > I've just re-ordered the POD in Catalyst::Helper a bit, and added a section > linking to common helpers: > > http://dev.catalystframework.org/svnweb/Catalyst/revision?rev=8144 > > Something similar to what you suggested in your original message might have > a place in Catalyst::Helper::Model::DBIC::Schema (or a link to the relevant > docs there) > > -ash > > ___ > 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/ > > -- Todd Rinaldo [EMAIL PROTECTED] ___ 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/
Re: [Catalyst] Catalyst-Devel Patch
On Sun, Jul 20, 2008 at 08:42:26AM -0500, Todd Rinaldo wrote: > Hi, yesterday, I asked a question in DBIC channel about how > Catalyst::Helper auto-produces schema. It was answered with purl: > make_schema_at. I suggest this be put in Catalyst::Helper so people > can more easily find the answer I suggested you patched Catalyst::Helper::Model::DBIC::Schema ... maybe we should have a myapp_create.pl --help Model DBIC::Schema option that invokes perldoc for the appropriate helper? -- Matt S Trout Need help with your Catalyst or DBIx::Class project? Technical Directorhttp://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@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/
Re: [Catalyst] Catalyst-Devel Patch
On 21 Jul 2008, at 14:37, Todd Rinaldo wrote: J, Thanks for the detailed reply. I hadn't thought about the base class nature of this class. Catalyst and DBIC are both MAJOR development projects. This means their documentation on CPAN gets spread broadly over many pages. I admit this is not a problem for most modules on CPAN. I suppose my patch was specifically aimed at dealing with some of this. I have countless times asked questions on a list/IRC which was clearly documented on a page I'd reviewed multiple times. Once I knew where to look, the answer was easy. I am a major fan of wiki, as it's low entry barrier can make it easy for the people who most need the information (newbies) to append to the docs or clarify the docs once they get their answer. I'll take a look at the available wikis. When I'm done, I suspect my comment will be, well if this is the best place to put the docs on useability, shouldn't we point to it from the POD? This would effectivley allow us to separate the design specs related stuff (POD) from the practical use (WIKI). What are your thoughts on this approach? Todd Generally, the problem with the docs for Catalyst::Helper is that they are only relevant if you are writing a new helper, not if you are trying to use it. I've just re-ordered the POD in Catalyst::Helper a bit, and added a section linking to common helpers: http://dev.catalystframework.org/svnweb/Catalyst/revision?rev=8144 Something similar to what you suggested in your original message might have a place in Catalyst::Helper::Model::DBIC::Schema (or a link to the relevant docs there) -ash ___ 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/
Re: [Catalyst] Catalyst-Devel Patch
J, Thanks for the detailed reply. I hadn't thought about the base class nature of this class. Catalyst and DBIC are both MAJOR development projects. This means their documentation on CPAN gets spread broadly over many pages. I admit this is not a problem for most modules on CPAN. I suppose my patch was specifically aimed at dealing with some of this. I have countless times asked questions on a list/IRC which was clearly documented on a page I'd reviewed multiple times. Once I knew where to look, the answer was easy. I am a major fan of wiki, as it's low entry barrier can make it easy for the people who most need the information (newbies) to append to the docs or clarify the docs once they get their answer. I'll take a look at the available wikis. When I'm done, I suspect my comment will be, well if this is the best place to put the docs on useability, shouldn't we point to it from the POD? This would effectivley allow us to separate the design specs related stuff (POD) from the practical use (WIKI). What are your thoughts on this approach? Todd On Sun, Jul 20, 2008 at 10:38 PM, J. Shirley <[EMAIL PROTECTED]> wrote: > On Sun, Jul 20, 2008 at 7:49 PM, Todd Rinaldo <[EMAIL PROTECTED]> wrote: >> Hi, >> >> I still think something should go in the manual explaining how this >> works. I spent quite a bit of time trying to figure out how >> Catalyst::Helper did it's magic. If a code reference shouldn't go in, >> then could I recommend a link to the FAQ. I think allot of people get >> their start with DBIC using Catalyst::Helper and so it's the natural >> place they would look first. >> >> [snip] > > The main point is that Catalyst::Helper is specific to Catalyst, and > has absolutely zero relevance to DBIx::Class. > > If you want something in the Catalyst::Helper space, something > specific to DBIC would be the right place. > > As an example, Catalyst::Model::DBIC::Schema: > http://search.cpan.org/~blblack/Catalyst-Model-DBIC-Schema-0.20/lib/Catalyst/Model/DBIC/Schema.pm > > But, again, the question you are asking is already answered in the > Catalyst::Helper::Model::DBIC::Schema documents: > http://search.cpan.org/~blblack/Catalyst-Model-DBIC-Schema-0.20/lib/Catalyst/Helper/Model/DBIC/Schema.pm > > The relevant excerpt: > create=static instructs this Helper to generate the named Schema class > for you, using DBIx::Class::Schema::Loader in "one shot" mode to > create a standard, manually-defined DBIx::Class::Schema setup, based > on what the Loader sees in your database at this moment. A > Schema/Model pair generated this way will not require > DBIx::Class::Schema::Loader at runtime, and will not automatically > adapt itself to changes in your database structure. You can edit the > generated classes by hand to refine them. > > So, what we have is documentation to use > Catalyst::Helper::Model::DBIC::Schema or to use DBIx::Class directly > and the make_schema_at method. > > If you'll note, Catalyst::Helper's pod, almost in entirety, is focused > on people writing generic model, view and controller classes - and not > for end users. In fact, even in Catalyst::Manual::Cookbook the only > reference to DBIC is a link to Catalyst::Model::DBIC::Schema. Further > reading of that page, in the description section, it hints at your > question: > "This is a Catalyst Model for DBIx::Class::Schema-based Models. See > the documentation for Catalyst::Helper::Model::DBIC::Schema for > information on generating these Models via Helper scripts." > > The link there finally answers the specifics of the question on how to > generate DBIC classes from an existing database, and in very specific > detail. > > It's unreasonable to expect Catalyst core documentation to reference > any specific model that may or may not be used. Simply because > Catalyst and DBIC are most commonly used together does not mean that > the Catalyst community endorses DBIC as the only ORM. If you ask our > advice, we will recommend it (more in the way of, if you don't know > why you should use it over others, you should use it). > > Now, please note I'm not saying that search.cpan.org or Pod in its > current form is the best solution for documentation. I think it could > use work, and that would help increase findability. As always, > patches welcome and all that. I just think that your patch is a > misguided attempt to help because you failed to read other relevant > documentation. I don't want to discourage you from helping just > because I'm saying no, because there are other ways to address your > very valid issue of not finding the right information. > > If you agree with me in my feelings that finding this information is > the issue, and not the location (and increasing where the information > is found is not a solution), perhaps the right solution is to submit > this on the wiki, or start a blog, or if you have one use a catalyst, > perl or dbic tag, write an article and then submit your blog to be > included on planet.catalystframework.org. Th
Re: [Catalyst] Catalyst-Devel Patch
On Sun, Jul 20, 2008 at 7:49 PM, Todd Rinaldo <[EMAIL PROTECTED]> wrote: > Hi, > > I still think something should go in the manual explaining how this > works. I spent quite a bit of time trying to figure out how > Catalyst::Helper did it's magic. If a code reference shouldn't go in, > then could I recommend a link to the FAQ. I think allot of people get > their start with DBIC using Catalyst::Helper and so it's the natural > place they would look first. > > [snip] The main point is that Catalyst::Helper is specific to Catalyst, and has absolutely zero relevance to DBIx::Class. If you want something in the Catalyst::Helper space, something specific to DBIC would be the right place. As an example, Catalyst::Model::DBIC::Schema: http://search.cpan.org/~blblack/Catalyst-Model-DBIC-Schema-0.20/lib/Catalyst/Model/DBIC/Schema.pm But, again, the question you are asking is already answered in the Catalyst::Helper::Model::DBIC::Schema documents: http://search.cpan.org/~blblack/Catalyst-Model-DBIC-Schema-0.20/lib/Catalyst/Helper/Model/DBIC/Schema.pm The relevant excerpt: create=static instructs this Helper to generate the named Schema class for you, using DBIx::Class::Schema::Loader in "one shot" mode to create a standard, manually-defined DBIx::Class::Schema setup, based on what the Loader sees in your database at this moment. A Schema/Model pair generated this way will not require DBIx::Class::Schema::Loader at runtime, and will not automatically adapt itself to changes in your database structure. You can edit the generated classes by hand to refine them. So, what we have is documentation to use Catalyst::Helper::Model::DBIC::Schema or to use DBIx::Class directly and the make_schema_at method. If you'll note, Catalyst::Helper's pod, almost in entirety, is focused on people writing generic model, view and controller classes - and not for end users. In fact, even in Catalyst::Manual::Cookbook the only reference to DBIC is a link to Catalyst::Model::DBIC::Schema. Further reading of that page, in the description section, it hints at your question: "This is a Catalyst Model for DBIx::Class::Schema-based Models. See the documentation for Catalyst::Helper::Model::DBIC::Schema for information on generating these Models via Helper scripts." The link there finally answers the specifics of the question on how to generate DBIC classes from an existing database, and in very specific detail. It's unreasonable to expect Catalyst core documentation to reference any specific model that may or may not be used. Simply because Catalyst and DBIC are most commonly used together does not mean that the Catalyst community endorses DBIC as the only ORM. If you ask our advice, we will recommend it (more in the way of, if you don't know why you should use it over others, you should use it). Now, please note I'm not saying that search.cpan.org or Pod in its current form is the best solution for documentation. I think it could use work, and that would help increase findability. As always, patches welcome and all that. I just think that your patch is a misguided attempt to help because you failed to read other relevant documentation. I don't want to discourage you from helping just because I'm saying no, because there are other ways to address your very valid issue of not finding the right information. If you agree with me in my feelings that finding this information is the issue, and not the location (and increasing where the information is found is not a solution), perhaps the right solution is to submit this on the wiki, or start a blog, or if you have one use a catalyst, perl or dbic tag, write an article and then submit your blog to be included on planet.catalystframework.org. This is always preferable than adding in more, and potentially irrelevant, documentation in an area where it doesn't belong. On the wiki, there is already a DBIC FAQ that would be the perfect location: http://dev.catalystframework.org/dbicfaq Thanks and I hope to see your contributions on the wiki, -J ___ 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/
Re: [Catalyst] Catalyst-Devel Patch
Hi,
I still think something should go in the manual explaining how this
works. I spent quite a bit of time trying to figure out how
Catalyst::Helper did it's magic. If a code reference shouldn't go in,
then could I recommend a link to the FAQ. I think allot of people get
their start with DBIC using Catalyst::Helper and so it's the natural
place they would look first.
On Sun, Jul 20, 2008 at 9:06 AM, J. Shirley <[EMAIL PROTECTED]> wrote:
> On Sun, Jul 20, 2008 at 6:42 AM, Todd Rinaldo <[EMAIL PROTECTED]> wrote:
>> Hi, yesterday, I asked a question in DBIC channel about how
>> Catalyst::Helper auto-produces schema. It was answered with purl:
>> make_schema_at. I suggest this be put in Catalyst::Helper so people
>> can more easily find the answer
>>
>> I'm sorry if this is not in the right format, but diff -u -b does not
>> work on OSX
>>
>>
>> $>svn diff lib/Catalyst/Helper.pm
>> Index: lib/Catalyst/Helper.pm
>> ===
>> --- lib/Catalyst/Helper.pm (revision 8143)
>> +++ lib/Catalyst/Helper.pm (working copy)
>> @@ -521,6 +521,19 @@
>> The helpers will read author name from /etc/passwd by default.
>> To override, please export the AUTHOR variable.
>>
>> +=head1 FAQ
>> +
>> +=over
>> +
>> +=item B
>> +
>> +For More information, see B.
>> +An example command of how this would be produced is as follows:
>> +
>> +perl -MDBIx::Class::Schema::Loader=make_schema_at,dump_to_dir:./lib
>> -e 'make_schema_at("My::Schema", { debug => 1, db_schema =>
>> "myschemaname" }, [ "dbi:Pg:host=localhost;dbname=mydbname", "user",
>> "pass" ])'
>> +
>> +=back
>> +
>> =head1 SEE ALSO
>>
>> L, L, L,
>>
>> ___
>> 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/
>>
>
>
> Thanks for your patch, but you are confusing projects. DBIx::Class
> and Catalyst are two distinct and separate projects and you won't see
> anything aside from references in the manuals for each.
>
> The DBIx::Class cookbook has the answer to the question you asked:
>
> http://search.cpan.org/~ash/DBIx-Class-0.08010/lib/DBIx/Class/Manual/Cookbook.pod#Creating_Schemas_From_An_Existing_Database
>
> ___
> 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/
>
>
--
Todd Rinaldo
[EMAIL PROTECTED]
___
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/
Re: [Catalyst] Catalyst-Devel Patch
On Sun, Jul 20, 2008 at 6:42 AM, Todd Rinaldo <[EMAIL PROTECTED]> wrote:
> Hi, yesterday, I asked a question in DBIC channel about how
> Catalyst::Helper auto-produces schema. It was answered with purl:
> make_schema_at. I suggest this be put in Catalyst::Helper so people
> can more easily find the answer
>
> I'm sorry if this is not in the right format, but diff -u -b does not
> work on OSX
>
>
> $>svn diff lib/Catalyst/Helper.pm
> Index: lib/Catalyst/Helper.pm
> ===
> --- lib/Catalyst/Helper.pm (revision 8143)
> +++ lib/Catalyst/Helper.pm (working copy)
> @@ -521,6 +521,19 @@
> The helpers will read author name from /etc/passwd by default.
> To override, please export the AUTHOR variable.
>
> +=head1 FAQ
> +
> +=over
> +
> +=item B
> +
> +For More information, see B.
> +An example command of how this would be produced is as follows:
> +
> +perl -MDBIx::Class::Schema::Loader=make_schema_at,dump_to_dir:./lib
> -e 'make_schema_at("My::Schema", { debug => 1, db_schema =>
> "myschemaname" }, [ "dbi:Pg:host=localhost;dbname=mydbname", "user",
> "pass" ])'
> +
> +=back
> +
> =head1 SEE ALSO
>
> L, L, L,
>
> ___
> 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/
>
Thanks for your patch, but you are confusing projects. DBIx::Class
and Catalyst are two distinct and separate projects and you won't see
anything aside from references in the manuals for each.
The DBIx::Class cookbook has the answer to the question you asked:
http://search.cpan.org/~ash/DBIx-Class-0.08010/lib/DBIx/Class/Manual/Cookbook.pod#Creating_Schemas_From_An_Existing_Database
___
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/
