[Grok-dev] Re: FAQ section for Grok?

[Martijn Faassen]

Hi there,

A FAQ section on grok.zope.org would be very good to have! I heard 
earlier that Peter Bengtsson was working on something like this as well; 
perhaps you could contact him and ask him what the status is? (but don't 
wait forever for him; just go ahead and do it)

Danny Navarro wrote:
> Fernando Correa just explained me what is a grokker and what does 
> Upon your feedback I can start publishing the following questions:

I've put in my versions below.

> - What is a Grok directive?
> A Grok directive is a snippet of code meant to be interpreted by a 
> grokker. [Link to Grok directives reference grok 0.14dev?]

[I wouldn't use 'snippet of code']

A Grok directive is a class or module-level annotation that looks like this:

   grok.foo('information')

If in a class, it annotates the class with extra information used to 
configure the class. If in a module, it annotates the module with this 
extra information. A module-level directive can be used as the default 
for all classes, if it can also occur in a class itself.

Directives are often optional; if they are left out the default value 
for that directive kicks in. The ``grok.require`` directive for example 
has as its default ``zope.Public``, meaning views are public by default.

Grok directives are interpreted by a grokker.

> - What is a grokker?
> A grokker is a component that extracts grok directives from Python code 
> so that the components are coupled by Zope component machinery (site 
> manager?). You don't need to learn how to write grokkers unless you want 
> to extend Grok itself.

A grokker is a component that configures a class, module or instance 
with Grok. It uses annotations made by directives to determine the 
details of this confirmation. Configuration often entails the 
registration of a class with the Zope Component Architecture (ZCA); an 
adapter is for instance registered with the ZCA by what it adapts and 
what interface it adapts to.

You don't need to learn how to write grokkers unless you want to extend 
Grok itself with new configuration behavior.

> - What does someone mean when claiming that a component has been grokked?
> It means that the grokker has acted on the component and has been 
> configured by Zope machinery. It's one of the most frequent words you 
> will read from Grok developers if you follow Grok-dev mailing list.

It means that any relevant grokkers have acted on the component and the 
component has been configured.

> - What are the megrok packages about?
> The packages that are under megrok namespace package are non-essential 
> Grok packages that extend the basic functionality of Grok. Some of them 
> integrate different Zope 3 packages into an easier to use Grok package 
> which follows Grok conventions for sensible configuration.

[No amendments here. :)]

> - What are the grokcore packages?
> These are packages that actually make Grok. You don't need to deal with 
> them unless you want to understand how Grok works internally.
>

These are packages that implement certain features in Grok itself. You 
don't need to deal with them unless you want to understand how Grok 
works internally, or if you want to use bits of Grok outside of Grok 
itself, for instance in a non-Grok Zope 3 application or in a Zope 2 
setting.

> Actually I have been compiling a very long list of questions at the same 
> time I was learning Grok and Zope3, but instead of sending them all, I 
> can start publishing FAQs gradually as I learn more about Grok and get 
> feedback from people who can ensure my naive answers are correct.

I think a FAQ is a great initiative! It's definitely another very 
helpful way to help people learn Grok and understand discussions about it.

I think it'd be good if you posted a few more questions & answers you 
have to the mailing list. I'll be happy to write my answers. Even though 
I did write a lot of my own answers here, your answers were very helpful 
to me in writing my own, and it's also interesting to see what other 
people's answers are, so please do continue writing them (unless you 
really don't know the answer of course).

I also invite others to submit answers to the questions you ask here; we 
can combine multiple answers into a good FAQ answer that we can then 
publish to the site.

Regards,

Martijn