Citing HTML tags in docs?

["Geoff Hart (by way of \"Eric J. Ray\" <ejray -at- raycomm -dot- com>)" <ght -at- MTL -dot- FERIC -dot- CA>]

Susan Kocher asked for advice on referring to HTML tags in
documentation:

<<The question arises, should we use uppercase in naming tags and
attributes Lower case? Should tag names have angle brackets around
them when we refer to them in paragraph text?>>

If it's an instructional book, don't create any distance between the
reader and the concept by making the citation in the text look
different from the citation in the code: that requires extra skull
sweat. If the code uses all caps (e.g., because that's the default
for the tool you're documenting), then you should use all caps.
Other than that, I'm not aware that HTML is case-sensitive (I write
in lower case without problems), so use lower case: that way, readers
needn't wear out their shift or caps lock keys. Be consistent in your
own use, and between the text and the code. Don't neglect the
angle brackets (<tag>) format: angle brackets are a very strong cue
about what to look for in the code listings, and a reminder that
angle brackets are necessary if you enter the code yourself. If
you're in any doubt, define your conventions in the text in an
introductory chapter, and make it clear that although there's no
difference from a coding perspective, you've chosen one format for
the sake of consistency. That way readers understand what you're
doing, and can choose a different approach without fearing that
they're doing somethng illegal.

<<related question: "a" or "an" /HTML tag?>>

"An", unless you pronounce it "haish-tee-em-ell" instead of
"aitch-tee...". I don't know anyone who pronounces it the former way.

<<The href attribute points to a name attribute in another
location.>>

Since href isn't a tag itself, but rather an attribute of a tag, I
suggest using the standard approach: "change font to Courier" (or
whatever font you're using in your code examples) to identify the
tag, as has been done in programming guides for decades. If you don't
want to be playing the game of alternating fonts, italics should do
just fine. Quotes are unnecessary and potentially confusing, since
some readers will try to type the quotes too.

<<User readability should be our primary concern, and obviously
uppercase is easier to pick out and identify as tag/attribute names.
In the HTML course I took through the STC, I was taught to get in the
habit of always using uppercase in my own markup so that I could more
easily analyze it later.>>

Readability is important, and capping the tags does make them stand
out, but I hate programming languages that make me do things that the
computer should be doing for me. The computer doesn't care whether I
capitalize, so why should I do the extra work? Indentation and use of
white space are more effective. One important exception: If you're
documenting a tool that inserts its own tags entirely in upper case,
then you should follow the same practice. It makes no difference from
the standpoint of coding the page, but differing from the tool
creates an unresolved inconsistency for the reader to figure out.

--Geoff Hart @8^{)}
geoff-h -at- mtl -dot- feric -dot- ca

"By God, for a moment there it all made sense!"--Gahan Wilson

 From ??? -at- ??? Sun Jan 00 00:00:00 0000=