Hi Steven,
Is that still true even after I tweaked the documentation to
clarify exactly that point? (One of the first substantial things I
did to the Wiki when I started.) I know I found it a bit confusing
at first, but I believe the documentation as it stands now would
have clarified it for me.
http://rifers.org/wiki/display/RIFE/Alternative+tag+syntax
Sadly, yes. Today someone on IRC had the same doubts as before. Last
week also, someone that was evaluating RIFE asked me similar
questions. The problem is that people jump onto conclusions after
having seen a snippet of template code. The traditional criticisms
are that RIFE's template syntax is not invisible to the browser and
that it's arcane. Even though I don't like the XML-based <r:v name=""/
> myself very much, it really seems to create the least "first
contact" hurdles. People are used to scanning for XML tags and it is
invisible to browsers. Advanced tools can even auto-complete it using
the DTD and a namespace declaration. Using the ${} syntax all over
(even for block declarations) makes the template syntax look very not
HTML like, just compare this:
http://rifers.org:8088/browse/rifers/rife/trunk/src/examples/tutorial/
05_friends_basic/src/templates/add.html?r=3363
with this:
http://rifers.org:8088/browse/rifers/rife/trunk/src/examples/tutorial/
05_friends_basic/src/templates/add.html?r=3308
We do need to standardize on one consistent syntax in the
documentation, and I think that for those that don't know RIFE yet,
it has to be as close as possible to what they already know. The <r:v
name=""/> syntax seems the most appropriate to me. Of course, once
they do find the alternative tag syntax page in the docs, they can
still pick another alternative if they prefer it.
My main concerns are to confuse people as little as possible and to
dismiss the wrong conclusions immediately.
What do others think?
Best regards,
Geert
PS.: Steven, I'll look into your parametrized outer join post tomorrow
Having all variants being used in the user's guide and examples
seems to confuse people. We thus thought it might be a good idea
to use the <r:v name=""/> syntax as much as possible unless it
creates invalid XML, then the ${v /} could be used. If this gets
applied consistently, new users don't have to teach their eyes to
scan for different syntactic patterns. They know the XML pattern,
and most of them know the EL or Velocity pattern.
If that's the standard, then sure, I can comply with it when I
write/edit docs. I don't happen to *agree* with it, though: when I
was getting started it was the mixing of two syntaxes in the same
file that led to my confusion. It felt inconsistent and arbitrary,
or worse, inconsistent and meaningful. I initially thought that
maybe the "[!V" style would do URL-encoding or something like that;
I only ever saw it used in HTML attribute values which kind of
implied it was a special syntax that would do something different
for use inside HTML tags.
In my code I use the ${} syntax exclusively, inside tags or out.
That way when I'm showing my code to someone new I don't have to
launch into an explanation about nested tags and valid XHTML syntax
and alternative template formats. It seems like there's really no
way to avoid such an explanation if you ever use two syntaxes in
the same document.
So IMO it would be much better to just choose either the ${...} or
the [!...] format and use that throughout the documentation, maybe
with a periodic brief mention (linking to the alternative-syntaxes
page) that there are other options.
That mostly holds true for the user's guide in my opinion; the
cookbook has more latitude since the user will already be aware
that there are alternative syntaxes (if you keep mentioning it in
passing in the user's guide) by the time they're to the point of
wanting to browse around in the cookbook.
As always, just MHO.
--
Geert Bevin
Uwyn "Use what you need" - http://uwyn.com
RIFE Java application framework - http://rifers.org
Music and words - http://gbevin.com
_______________________________________________
Rife-users mailing list
[email protected]
http://lists.uwyn.com/mailman/listinfo/rife-users
