[Grok-dev] Re: proposal: grok.title() and grok.description()

[Wichert Akkerman]

Previously Martijn Faassen wrote:
> Hey,
> 
> Tres Seaver wrote:
> [snip]
> >>The arguments to both is a unicode string or a message id: human 
> >>readable text.
> >
> >Can we stay with the grokkish convention that ASCII strings are alllowed
> >as well?  I *hate* the dead chicken of the leading 'u'.
> 
> Yes, of course. Whenever I say 'unicode string', just read "unicode 
> strings and plain ascii strings". I pushed for that one in Grok. :) It 
> will get us in trouble if we ever convert to Python 3.0, but that'll be 
> only one of our troubles.
> 
> >>These directives should be usable on just about any class, ranging from 
> >>Model to View to Permission.
> >>
> >>The idea is then that an application's user interface can access this 
> >>data (this means we need to come up with a good API to access this kind 
> >>of grok-defined attribute in the grok module. Anyone have any ideas?). 
> >
> >How about assigning '__doc__' on the object ;)?  Actually, one might
> >hack the directives so that they *returned* the values when passed a
> >non-basestring / message ID object.
> 
> Isn't __doc__ used by docstrings? Not sure whether you're not kidding 
> (there's a smiley) but just to make it clear: docstrings tend towards 
> programmer-readable text and this is for UI text. Currently the admin UI 
> uses the docstring to present some information about an application, but 
> I'd rather have it use title and description. (then again, applications 
> are somewhat special, as typically you'd only want to see the title of 
> an application in a UI that *manages* applications such as the admin UI).
> 
> Hacking the directives to return the equivalent value when passed 
> something is an interesting idea. Generalizing this seems difficult 
> however, as grok.context() already can take class arguments.
> 
> [snip]
> >>We need sensible defaults for these two attributes. grok.description() 
> >>should default to grok.title().
> >
> >I'd rather see it default to empty.
> 
> Somewhat dangerous for the same reasons as spelled out below for 
> grok.title()... Then again, perhaps not as much of a problem as for 
> title, and that way you'd not see duplicated text. One wouldn't expect 
> to see the description very often without showing the title as well, 
> after all. So I think defaulting to the empty string is a better idea, 
> indeed.
> 
> >>What about grok.title()? I think it 
> >>would be bad if grok.title() defaulted to the empty string, as these 
> >>don't show up in the user interface and give no clue as to what object 
> >>you're dealing with. I therefore propose grok.title() should default to 
> >>the class name. This gives a good hint on what's going on in a user 
> >>interface where someone hasn't spelled out grok.title() yet for a 
> >>particular class, which can then be easily fixed.
> >
> >Defaulting to '__name__' is probably fine.  Another option is to do the
> >"first line, rest" splitting of '__doc__'.
> >
> >>What do people think?
> >
> >+1 overall.
> 
> Thanks for the feedback! To summarize, two modifications to the proposal 
> as prompted by your remarks:
> 
> * plain ascii text is allowed too.
> 
> * grok.description() should default to the empty string.

+1 with those modifications.

Wichert.

-- 
Wichert Akkerman <wichert at wiggy.net>    It is simple to make things.
http://www.wiggy.net/                   It is hard to make things simple.