W3C home > Mailing lists > Public > www-html@w3.org > July 2011

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 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Tuesday, 27 March 2012 18:16:19 GMT