Re: Markup for variable definitions

18.07.2011 14:49, Křištof Želechovski wrote:

> I have been confronted with documentation that says:
>
> <DT>char *blah<DD>This variable contains lorem ipsum.
>
> I wonder whether this markup is correct, as the variable
 > type is not part of the variable blah, it is a property thereof.

It’s not correct if <DL> is taken as meaning a definition list, as it 
nominally is in the HTML 4.01 spec, but the spec also says strange 
things about it. It even mentions using <DL> for a discussion where <DT> 
would give the speaker—which would be absurd under the “definition list” 
semantics, as a person or a name is surely not defined by the words he 
utters in some situation.

In practice, it is best to interpret that HTML 4.01 means that <DL> is a 
list of name/value pairs, for some loose meanings for “name” and 
“value.” This is being formalized in HTML5.

> I can see two basic options:
>
> 1.<DT>blah<DD><PRE>char *blah;</PRE><DD><P>This variable contains lorem ipsum.
> 2,<TR><TD>char *<TD>blah<TD><P>This variable contains lorem ipsum.

There is no adequate markup for definitions, so you can just as well use 
<DL> if it makes things easier. Or you can use a table. But option 1 
would be an unnecessary complication.

You can, if you like, use <DFN> markup, though it only indicates its 
content as term being defined, without saying what constitutes the 
definition:

<DT>char *<DFN>blah</DFN><DD>This variable contains lorem ipsum.

If you do so, beware that some browsers use italics for <DFN> by 
default, so you may wish to set the font-style property for it in CSS 
(to normal or italic, by your choice).

I wouldn’t really bother using <DFN>. I don’t know of any search engine, 
browser, or other relevant software that makes some use of its defined 
semantics. Much like they don’t care about the semantics of <DL> (and 
this is understandable because <DL> is so widely used for constructs 
other than definition lists, and the name/value pair list interpretation 
is semi-semantic at most).

In theory, it would be great if defining occurrences of terms were 
marked up consistently. Search engines could then search for definitions 
(a common need) or exclude defining occurrences (a less common, yet real 
need) better than they do now. But that hasn’t happened and that isn’t 
happening.

Besides, such behavior would not even be particularly useful when the 
term is a programming language variable. Surely they can be regarded as 
terms, which may have definitions, but they are a rather special kind of 
a term, comparable to casual notations that people may use, like an 
abbreviation defined for and used in a single document only. It would 
seldom be interesting to search for occurrences of words as terms in 
definitions in such a sense.

-- 
Yucca, http://www.cs.tut.fi/~jkorpela/

Received on Monday, 18 July 2011 19:08:53 UTC