Re: Pod at __END__
On 6/7/07, Eric Wilhelm <[EMAIL PROTECTED]> wrote: # from Joshua ben Jore # on Thursday 07 June 2007 05:14 pm: >On 6/7/07, Eric Wilhelm <[EMAIL PROTECTED]> wrote: >> I've never seen the benefit of pod after __END__. IMO, your code >> and docs should follow the same order/groupings. > >It has two benefits. >...readable without syntax highlighting. The first is pretty moot with the right tools, which are easy to find. As for the browser, that can be highlighted or pod2html'd. Yeah, I'm just expecting that the common tool is code that is unhighlighted, monospace text. Your code should always look readable even with all the bells and whistles turned off. Heck, /usr/bin/less is a pretty common way of inspecting source too. It comes right after going to http://search.cpan.org/src/JJORE/Carp-Clan-5.9/lib/Carp/Clan.pm or similar. If your code isn't readable in the "default" configuration then you need tools to reform your code for your editing convenience or something. It's not the form that it ought to be saved in. Josh
Re: Pod at __END__
On 8 Jun 2007, at 01:14, Joshua ben Jore wrote: On 6/7/07, Eric Wilhelm <[EMAIL PROTECTED]> wrote: I've never seen the benefit of pod after __END__. IMO, your code and docs should follow the same order/groupings. That, and you have to It has two benefits. Separating code from pod prevents it from being wholely unreadable without syntax highlighting. I ran into this face first once while trying to read CPAN code or something similar through a browser. I ended up mistaking code in pod for real code and mostly it was pretty unpleasant. [snip] I'll be annoying and just go with "it depends"! If I have a whole bunch of public subroutines that I can have in a reasonable order for reading I'll inline the POD. I find it helps to have it nearby. That Knuth bloke and his literate programming wasn't completely nuts in my opinion :-) When I have a bunch of private subroutines, or the sensible code order doesn't match the sensible reading order, I'll stick it all at the end. Sometimes I'll switch back and forth a few times as I refactor. Adrian
Re: podlifter
On 8 Jun 2007, at 04:14, Eric Wilhelm wrote: Getting it interleaved back into the right spot without leaving a token behind would probably be difficult, particularly if an =head2 gets stuck in while out of line. (You would probably need tokens in both the code and the pod to do it right.) Yeah, it's hard to make it do the right thing with arbitrary POD. It'd probably have to enforce a particular POD structure to work. And I'd probably only use it so Andy didn't scoff at my code - and I'm not /that/ bothered about his scoffing :) -- Andy Armstrong, hexten.net
Re: Pod at end
On 8 Jun 2007, at 13:04, Andy Armstrong wrote: [snip] I can see the benefits of keeping a method and its documentation adjacent. Intuition would would pull me in that direction - but practice pulls me in the other direction. When I have my documentation head on I just want to see documentation. [snip] Something I find trez useful when writing pod is this little script http://www.perlmonks.org/index.pl?node_id=227856 (my local version has been hacked a bit since, but I imagine this still works)
Re: Pod::Critic?
On 8 Jun 2007, at 09:03, Piers Cawley wrote: Have we been round the 'use a folding editor then' route yet? I forget. Yes I think so :) I don't really want to change my POD writing habits though. My reasons for preferring POD at the end are just as valid /for me/ as someone else's reasons for preferring interleaved POD. Better / different tools could certainly make it moot. The ideal is surely that I should be able to write POD in the way that suits me and you should be able to work on the same code and have it structured according to your preferences. perltidy solves that problem for formatting. If you send me some code and I really can't get on with your layout I just perltidy it to suit me. If you send me your perltidyrc I'll flip it back to your preferences before I commit or send it back to you or whatever. It'd be nice to have a similar tool that worked at the structural level. -- Andy Armstrong, hexten.net
Re: Pod at __END__
On 8 Jun 2007, at 08:24, Adrian Howard wrote: If I have a whole bunch of public subroutines that I can have in a reasonable order for reading I'll inline the POD. I find it helps to have it nearby. That Knuth bloke and his literate programming wasn't completely nuts in my opinion :-) Except that's not quite LP. LP (AFAIK) has the documentation form the primary narrative and the code gets assembled into the correct order by a preprocessor. When I have a bunch of private subroutines, or the sensible code order doesn't match the sensible reading order, I'll stick it all at the end. Sometimes I'll switch back and forth a few times as I refactor. That's the key. Currently you have to decide which layout to use - it should be easy to switch. -- Andy Armstrong, hexten.net
Re: Pod at end
On 8 Jun 2007, at 07:09, chromatic wrote: Fiddling with the POD before I’m done is beyond pointless. I'm willing to bet that you write documentation as the last task before bundling a release too. That's also my style. Sometimes I write the POD as a storyboard of how the module's interface should work then write the code to implement it - tweaking the story the POD tells as I go. Sometimes I write a bunch of code with no POD and then document it. Sometimes POD and code evolve in parallel. Aristotle's point about being able to read the POD as a continuous narrative is a big factor for me. I can see the benefits of keeping a method and its documentation adjacent. Intuition would would pull me in that direction - but practice pulls me in the other direction. When I have my documentation head on I just want to see documentation. -- Andy Armstrong, hexten.net
Re: Pod::Critic?
On 07/06/07, Andy Armstrong <[EMAIL PROTECTED]> wrote: On 7 Jun 2007, at 23:16, Andy Lester wrote: > On Jun 7, 2007, at 5:13 PM, Andy Armstrong wrote: > >> So: Interleaved for the first draft, at the end for maintenance. > > To me, this is the same as saying "I turn off warnings and strict > when I'm done writing the program." It's a compromise. Nothing is compromised by leaving warnings and strict turned on but - for me - ease of navigation is compromised by inline documentation. Have we been round the 'use a folding editor then' route yet? I forget.
Re: Pod::Critic?
On Thursday 07 June 2007 12:54, David Cantrell wrote: > Nadim Khemir wrote: > > 'method docs have examples': I believe the examples should be tested. > > I have to disagree. And that would be your priviledge. If you have code in you POD and that code is not tested then you POD is not tested. You can find all the excuses in the world (may be completely valid technical excuses) that won't change the fact the POD is not tested. Dominique gave you some answers. I'm sure other have other methods that they can share with all of us. Testing is fun because it's also more difficult and that what's makes it fun. Cheers, Nadim.
Re: Pod::Critic?
On Friday 08 June 2007 00:04, Matisse Enzer wrote: > I wonder how you all feel these days about the "put the pod at > the __END__" approach? I've been trying it for over a year now > and am not really sure its the best way to go (vs. having the pod > for each method right next to it.) I put the POD _in_ the methode. Nadim.
