weavejester/hiccup — Issue #39: Replace 'tag' with 'element' in documentation
Author: nxg
Created: 2012-02-23 12:43:16+00:00
State: open

The Hiccup documentation refers to (XML) elements as 'tags', with the result that it produces confusing error messages.

`` is a tag -- a 'start tag'. `` is _also_ a tag -- an 'end-tag'. Together they delimit the 'foo' _element_, that is, the element with element-name 'foo'. (Start-) Tags contain attributes; elements do not. Elements contain text and other elements; tags do not. Elements have names; there's no such thing as a "tag name" (that's like saying 'what is the name of a comma').

They're completely different things (one is a syntax fragment, the other a bit of large-scale structure in a document), but Hiccup conflates them, which means that it produces confusing error messages such as "[:li "boo"] is not a valid tag name", which had me seriously scratching my head, looking for Clojure maps where this appears as a map key (which seemed the most reasonable interpretation of "tag name" in this context).

Sorry if this sounds picky, and I know that a lot of people conflate the two terms, but it confuses the hell out of anyone who knows the difference!

All the best,

Norman