Markup for variable definitions

• From: Křištof Želechovski <giecrilj@stegny.2a.pl>
• Date: Mon, 18 Jul 2011 13:49:39 +0200
• To: www-html@w3.org
• Message-Id: <201107181349.41239.giecrilj@stegny.2a.pl>

Hello,

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.  So the DT should contain "blah" only.
However, the information of the variable type is important to the reader and it must precede the variable name by the rules of the programming language; breaking this order would confuse the reader.

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.

Option 1st contains a repetition that may be annoying to the reader while Option 2nd does not show that column 2nd contains the term being defined.

Any ideas?

Chris

Received on Monday, 18 July 2011 18:39:49 UTC