Example suggestion
Lorenzo Gil Sanchez
guests and hotels is used to explain concepts. I think this is not the
best example we could have since we are mixing two meanings of the
'registration' word:
* A guest is registered in a hotel
* A component is registered in the ZCA
It's not a very important issue since the context of the text is
always clear and the it's hard to be confused but still, I think we
could all think in another example which wouldn't have this 'bug' :-)
What do you guys think?
Lorenzo
Kent Tenney
<lorenzo.g...@gmail.com> wrote:
>
> During the first 4 chapters of the book an example application about
> guests and hotels is used to explain concepts. I think this is not the
> best example we could have since we are mixing two meanings of the
> 'registration' word:
Very good point, any detail which could cause confusion is not good.
The hotel registration example has work behind it, but if we think another
example would be better, easier to change now than later.
I wonder if we could invent an example which has real world use, not
hypothetical.
I just happen to have a suggestion
:-]
It's code I want to implement, I'd love to have the kind of help that
would be provided by it being an example. Of course the teaching value
is paramount, and maybe someone else has a better suggestion, but
there is also added value if the example ends up with
code that people want to use.
I am investigating incorporating svg generation into documentation. I
think there's
potential for generating graphics to explain concepts. I think this
can go well beyond
the inheritance graphs and call flow charts I've seen.
Central to this would be a rich interface for generating svg elements,
both text and
graphic. Stuff like::
>>> svgdoc = SVGFactory(type=inkscape)
The inkscape svg editor project is great, they are commited to
offering Python extensibility
the type=inkscape produces svg with some inkscape namespace enhancements.
As a starting point, the code makes it convenient to create fairly raw
svg files which are then
refined in Inkscape.
>>> svgdoc.addClass('zope.interface.Interface', regions =
[{'signature':'clip'}])
this would create a text element consisting of the source for class Interface.
It would also define a clipping element which bounded the part of the
text element
containing the class declaration and docstring.
`regions` are a basic component of this concept, they define parts of
the text, the
image, or in this case, the image of the text.
Of course this is way down the road, it would start with a function to return a
simple svg tag, make that a class, extend it, interface it, adapt it.
There would be potential for the examples to generate graphics which
illustrated the concept being explained in that bit of code, sort of a
recursive example.
It would be suitable for demonstrating views, multi-adapters etc.
=============================================
If this doesn't sound appealing maybe someone else has code they would
like to see used for the example.
Thanks,
Kent
Baiju M
I agree that the example is bit
confusing because of the words,
register & registration used in different contexts. I chose an example
which itself may not require much explanation.
Kent, your idea of application is great. I am afraid we can use it as
an example
for this book, because it would be better to choose a simple and
more familiar domain/context.
Well, I cannot think of another example now. May be we can slightly
change the words? instead of 'registering' just 'adding' ?
or 'booking' but it may affect more sentences.
If we are going to change the example completely, I guess it will be a
lot of re-writes.
Regards,
Baiju M
Kent Tenney
> guests and hotels is used to explain concepts. I think this is not the
> best example we could have since we are mixing two meanings of the
> 'registration' word:
Since a good deal of effort has already gone into the Registration example,
but there is a real potential for confusion, how about:
Changing the spelling of 'Registration' to 'Booking'
Changing the spelling of 'Registrar' to 'FrontDesk'
Any objections or other suggestions?
Does it make sense to you to create 'Booking' with the 'FrontDesk'
Another spelling could be 'Reservation' but that could also be confused
with registration when they are being used together.
Thanks,
Kent
Baiju M
>
> On Nov 22, 2007 7:51 AM, Lorenzo Gil Sanchez
> <lorenzo.g...@gmail.com> wrote:
> >
> > During the first 4 chapters of the book an example application about
> > guests and hotels is used to explain concepts. I think this is not the
> > best example we could have since we are mixing two meanings of the
> > 'registration' word:
>
> Since a good deal of effort has already gone into the Registration example,
> but there is a real potential for confusion, how about:
>
> Changing the spelling of 'Registration' to 'Booking'
> Changing the spelling of 'Registrar' to 'FrontDesk'
+1
What will be the new method name ? register -> book ?
or book_room ?
Regards,
Baiju M
Lorenzo Gil Sanchez
On Nov 23, 6:53 pm, "Baiju M" <baiju.m.m...@gmail.com> wrote:
>
>
>
> > On Nov 22, 2007 7:51 AM, Lorenzo Gil Sanchez
>
> > > During the first 4 chapters of the book an example application about
> > > guests and hotels is used to explain concepts. I think this is not the
> > > best example we could have since we are mixing two meanings of the
> > > 'registration' word:
>
> > Since a good deal of effort has already gone into the Registration example,
> > but there is a real potential for confusion, how about:
>
> > Changing the spelling of 'Registration' to 'Booking'
> > Changing the spelling of 'Registrar' to 'FrontDesk'
>
> +1
>
the
confusion by choosing other words.
> What will be the new method name ? register -> book ?
> or book_room ?
>
Regards,
Lorenzo
Kent Tenney
method was book(), maybe greater chance of confusion with library book.
I think book_room() is better.
( so many words out there, yet we keep bumping into the same ones :-] )
I hope to keep blogging about the process of doing this at
http://gumpablog.blogspot.com
Thanks,
Kent
On Nov 24, 2007 4:06 AM, Lorenzo Gil Sanchez
Baiju M
>
> The use case Baiju is working on looks to be a library application, if the
> method was book(), maybe greater chance of confusion with library book.
>
> I think book_room() is better.
+1
That library application may make confusion again.
Regards,
Baiju M