[Scribus] this whole wiki thing

[Craig Ringer]

On Fri, 2005-02-04 at 21:23 -0500, Gregory Pittman wrote:

> 2. There is a wealth of information in the scribus at nashi.altmuehlnet.de 
> archives, as well as some very interesting discussions on a wide range 
> of DTP-related topics.  The wiki could give someone (or lots of 
> someones) a chance to scan the archive and give a collected summary of a 
> given discussion, along with appropriate links to the more interesting 
> individual mailings. Anyone who scans the Fedora list, for example, 
> realizes that there is such a repetitive nature to many of the questions 
> and many of the problems, because people don't spend much time scanning 
> the archives, and who can blame them?  It's a lot of work.

However, when good stuff turns up here in the future, dropping in a link
to the archive copy in the wiki seems like a good idea. Documenting
interesting threads and issues, etc.

> 3. As someone trying to learn Python, I can say that generally speaking, 
> the information out there to learn Python from the bottom up is not 
> easy.  There's a 'Catch-22' sort of a problem: if you know Python 
> already, you can easily get help.  But getting help with learning Python 
> up to that point is very difficult.  I bought two books, Learning 
> Python, and Python Cookbook.  Having read Learning Perl I was expecting 
> more -- it's very helpful, and entertaining.  Learning Python is a very 
> dry text and what passes for humor, well, it doesn't pass.

I found Learning Python's style somewhat unattractive - and in my view
it tries to "push" Python unrealistically, and irritatingly often. On
the other hand, the book is in my view well written and it'll help
clarify your understanding of some important concepts (understanding
name lookups/binding rules in scopes, classes, and instances,
namespaces, etc) even if you've been using Python for a while.

> So getting back to what I started with, the wiki could be of big help to 
> someone trying to modify a script or write a new one.  Just showing some 
> generic and complete examples (useful ones, not just the obtuse 
> fragments which abound in Python documentation) would be of great 
> value.

In general, I think solid and complete examples should probably go into
the Scribus distribution in the scripter examples directory. That means
they get tested regularly, updated to follow the current API, and
they're easy to find. That way they can also double as compatibility and
breakage tests :-)

> Conceptually, I find Python a very interesting language, but it 
> has become quite complex -- it makes learning regexp's look easy.

I tend to agree. It looks simple on the surface, but isn't as simple as
it seems once you get into the details. That said, one can code
perfectly good Python code without knowing or caring about a lot of said
details (though if you know them, you can often work faster or smarter
and avoid a few pitfalls). Users don't even have to understand classes,
for example, though they're immensely handy.

I agree with you that, at least for the purposes of scripting Scribus,
some more approachable documentation would be extremely useful.
Documentation that teaches basic Python while teaching the Scripter API.
Someone who wants to do some scripting for the app probably doesn't want
to learn to be a "proper" programmer - and so long as we can provide
some guidelines for them to follow, that should be fine too. Currently,
they often need to learn to think like a programmer first, then learn
the Scribus API. Not trivial.

-- 
Craig Ringer