Geert Bevin wrote:
Just a small note, on IRC we've been discussing template syntax variants since now that we've got the 4 alternatives, it seems that new users have trouble understanding that they're just syntactic sugar.
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
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. -Steve _______________________________________________ Rife-users mailing list [email protected] http://lists.uwyn.com/mailman/listinfo/rife-users
