On Wed, Aug 26, 2009 at 11:36 AM, vegas<[email protected]> wrote: > > Hey guys, > > I'm working my way through all the newbie docs so as to decide if > pylons is the answer to somethings I don't like about django or if I > should just get down with django-alchemy or something instead. > > While working through the quickwiki tutorial, I've come across a few > bits that I think could use a bit of clarification, and superfly on > IRC said this would be the appropriate place to mention them. > > The first thing is that most all of the paths are given relative to > the inner quickwiki folder(the app folder?) rather than the outer > QuickWiki folder. Obviously this won't trip up any experienced > hackers, but I've got a friend of mine working through the tutorial as > well, and I'm curious to see how he responds to the mentions of all > these files that actually live at different places.
It looks like the tutorial needs some updates. I haven't looked at it closely myself, but this double-directory structure is a basic characteristic in Pylons. The inner directory is the Python package, the outer directory is the application, yet they both have the same name. Capitalization helps to distinguish these, but you may want to rename the application further. "paster create" doesn't give you much choice in the names if I remember right, but you can rename the outer directory to anything you like afterward. (The inner directory is hardcoded all over the place so it's harder to change.) The tutorial probably just needs a note to point out this difference. Most relative paths in Pylons documentation refer to the inner directory, because the outer directory matters in only a couple ways (the INI files and setup.py). > Later, under the heading Application Setup, we are asked to edit > websetup.py. We insert the line > > meta.metadata.create_all(bind=meta.engine) > > but then in the explication this is discussed as if we had inserted > > meta.metadata.bind = meta.engine > model.metadata.create_all(checkfirst=True) > > which I presume is from an earlier version of the code, as find|grep > showed me no occurances of this text. Both variations are common in Pylons applications. It is probably as you expect, that a different editor changed the style but failed to notice all occurrences. The first style is arguably better because the second does more than it appears to: "metadata.bind=engine" has a global effect across all threads and functions. It doesn't matter in Application Setup because there's only one thread, but it's best to understand what's going on so it doesn't bite you in some other situation. (The Session bind is different because Session keeps track of which objects belong to which thread.) > In general, the code sections seem to be presented as a mix of "here's > an entire file" and "here's a code snippet to add". Sometimes the > lines of "the entire file" are partially present in what paster has > generated, which leads me to just edit the file and stick in what I > think is different. This can be a bit error prone and lead the reader > to miss out on an import statement or something. It's solely a > stylistic complaint, but I feel like presenting a "patch" or a diff > file here will lead to a better experience for the user of the > tutorial. A side by side diff would of course be the most explicit > thing, but I don't know how much of a pain in the ass that would be to > provide and maintain. Autogenerating a side-by-side diff for these > code sections could potentially help with keeping the prose in sync > with the code. The wording should be more precise, especially in a tutorial. > Also, I just noted while trying to resolve whether or not I wanted to > create the pages controller under QuickWiki or QuickWiki/quickwiki > that there is no mercurial repo up at > http://www.knowledgetap.com/hg/QuickWiki That's old. All the knowledgetap packages have moved to Bitbucket (http://bitbucket.org/bbangert). The current repository looks like it's is http://bitbucket.org/bbangert/quickwiki/ . -- Mike Orr <[email protected]> --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "pylons-discuss" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/pylons-discuss?hl=en -~----------~----~----~----~------~----~------~--~---
