Re: [Freemarker-devel] interested in feedback with new template engine

Monday, June 30, 2008, 7:27:54 PM, Joe Hudson wrote:

> Good, I'm glad no offense was taken because that is the last thing
> I would want to do.  I wrote a bunch of documentation between
> talking to Daniel and submitting to this list including:
> - Developers Guide: http://www.zipscript.org/docs/current/bk02.html

- ZipEngine.getInstance() is a design mistake as the ZipEngine object
  is mutable, e.g., with init(initProperties).

- What is a *static* template? Are there non-static ones too?

- The expression 'foo.bar' is not a string literal? You use it to
  access a top-level variable with dotted name as ${'foo.bar'}.

- variable.nonSilencedNullError, defaults to true: The name lead to a
  double denial. Should be "supressNullErrors" that defaults to false.
  
> - Users Guide: http://www.zipscript.org/docs/current/bk01.html

- "The standard variable format is ${varName}": It's not just a
  variable reference there. ZipScript has the ${expression} thing, and
  within the expression you can just write varName without the
  enclosing ${}. So the ${expression} is one thing (we call them
  interpolations), and varName is another thing (belongs to the
  expression syntax, and is usually called a variable reference), and
  these two are independent.

- "$!{bar} will not print anything": When is that useful in practice
  (with concrete examples), to printing *nothing*? If it occurs
  rarely, does it warrant a special interpolation syntax, when you
  could just write ${bar!""}?

- ${foo!somethingElseMissing!bar}:
  You could mention what about ${(foo + somethingElseMissing)!bar}

- ${myDate|t:short}: Why ":"? You have reserved the words "short",
  etc. after the "|", so why not "t_short" (or even "t.short" maybe).

- "Variable references inside directive statements do not need to be
  wrapped with ${} (although they can be)": When would you encourage
  somebody to do use ${} there? If never, then I would just disallow
  that. (And BTW, it's not a directive *statement*. You just called
  them directive earlier.)

- "[#elseif foo%2==0]" and like: Should be "[#elseif foo % 2 == 0]",
  according to all widespread source code formatting guidelines.

- The http://www.zipscript.org/docs/current/bk01ch03s04.html contains
  some extremely difficult sentences, that I can't understand:
  "Referencing macros defined in a macro library requires the
  namespace to be added to the reference name." and "Any macros that
  are defined within a macro library do not need to refer to any other
  macros defined in the same library with a namespace." Also, you call
  a macro as "[@abc.foo]", but none of the example snippets shows
  where do you specify the "abc" name itself. When you call
  engine.addMacroLibrary, you don't specify "abc" as its parameter, so
  where do you do that, and what addMacroLibrary actually does?

> - Quickstart Guide:
> http://code.google.com/p/zipscript/wiki/QuickStartGuide

(At least at this stage that rather could be the part of a "Cheat
sheet".)

> I'm not saying they couldn't be improved upon, in fact quite the
> opposite.  But I did attempt to write documentation...

As far as feedback from FM guys is concerned, you should explain the
object-oriented parameter stuff much deeply. That's the most important
and most interesting feature here after all. It's quite confusing
topic, as some of the nested macro calls and directives are executed
before the enclosing macro is called, etc. So these "what happens
*when*" things should be explained, preferably trough showing a more
complex example where some of the object-oriented parameters are added
inside a #foreach or #if.

Also, I think from now it's a freemarker-devel list topic. Could we
move over here? If so, answer there.

> Joe

-- 
Best regards,
 Daniel Dekany


-------------------------------------------------------------------------
Sponsored by: SourceForge.net Community Choice Awards: VOTE NOW!
Studies have shown that voting for your favorite open source project,
along with a healthy diet, reduces your potential for chronic lameness
and boredom. Vote Now at http://www.sourceforge.net/community/cca08