[Catalyst] RFC: The paradox of choice in web development

[Kieren Diment]

On 15/02/2009, at 1:57 PM, Kevin Monceaux wrote:

> Catalyst Fans,
>
> On Fri, 13 Feb 2009, David Steiner wrote:
>
>> i added my comments to the article, suggesting that we step up on the
>> documentation and marketing! we need to give the layperson a easier  
>> ride in
>> starting out with catalyst. and that requires more tutorials/ 
>> screencasts,
>> better official documentation, and more books being written. tell  
>> me what you
>> people think of the article and how we can get catalyst more used  
>> and known.
>
> As a newbie I can certainly agree that all of the above suggestions  
> regarding documentation/books/tutorials/screencasts would be good  
> things. I have a couple of sites I'm considering switching to  
> Catalyst, one of which is currently Django based and still running  
> running version 0.97. I haven't really been keeping up with Django  
> lately and have hardly looked at the 1.x branch yet.  I keep trying  
> to develop a fondness for Python, but it hasn't happened yet.  But,  
> a recent Django documentation discovery has me considering trying  
> harder to love Python.  A couple of days ago I discovered that with  
> the documentation sources included in the Django source tarball one  
> can generate documentation in a variety of formats, including pdf.   
> Projects with pdf documentation always score extra points with me.   
> It would be better if the pdf manual was available on the Django  
> site, but being able to generate it from sources is still a plus in  
> Django's favor.  Even if viewing on screen, I like documentation  
> that at least looks like a book.  And, I frequently print out bits  
> of documentation to read in bed.  I generated the available pdf  
> Django docs and ended up with a 748 page manual!!!  And, from a  
> quick search on Amazon it appears half a dozen up-to-date Django  
> books have come out in the last few months.  I'm impressed with the  
> available Django docs.
>
>


Hmm,

quick and dirty but apparently it works:  I'm doing it from an svk  
checkout, but I suppose it would be even simpler if you did it in the  
right bit of @INC:

find Catalyst-Runtime/5.80/trunk/lib/ Catalyst-Manual/5.70/trunk/lib/ - 
name '*' > /tmp/files

# change the order of stuff in /tmp/files around here if you want.

for i in `cat /tmp/files`; do  perldoc -T -u $i >> /tmp/catpod.pod ;  
done;

cd /tmp/

pod2latex -full -out catpod.tex catpod.pod

pdflatex catpod.tex

and there you go, a pdf of all 363 pages of the catalyst docs.

(actually this is a similar process to  what we're doing to make the  
first drafts of the catalyst book (err with our own original material,  
not the catalyst project pod).  Unfortunately for us, the publisher's  
workflow eventually requires that we use file format compatible with a  
word processor we will not name™)


Oh if you want super brownie points, go and learn haskell, and provide  
a pod translator for pandoc (http://johnmacfarlane.net/pandoc).  Or  
even better an equivalent arbitrary-markup-language parser written in  
perl.