Improved Phobos dox

[Andrei Alexandrescu]

On 9/16/13 8:55 AM, Vladimir Panteleev wrote:
> On Monday, 16 September 2013 at 15:22:50 UTC, Andrei Alexandrescu wrote:
>> On 9/16/13 6:40 AM, Vladimir Panteleev wrote:
>>> What before was <dd>, now is <div class="d_decl_dd"> (and the margin was
>>> a dd style). Why this change? You can apply any properties of one to the
>>> other through CSS.
>>
>> Great, thanks. Now fixed. My intent was to use <div> and <span> for
>> styling ddoc elements to the extent possible, in order to make styling
>> as flexible as possible.
>
> Although bordering on nitpicking, I'll mention that this is not a good
> change.

I'm here to learn.

> It is recommended to use the appropriate HTML elements for their
> semantic meaning.

[citation needed]

On the contrary, from what I've read in LaTeX and typography is that you 
want to keep formatting semantics high level, e.g. "This is a chapter 
title" as opposed to "this is heading text" or (worse) "this is large 
text with large spacing".

> <dl> is a definition list, which nicely fits
> documenting a list of entities.

It is, but it seems to me the more specific "list of symbols introduced" 
is better.

In this case the distinction is actually material because we have one 
style file for both Phobos and the larger dlang.org, and we may want to 
format regular <dd> differently from Phobos symbols description. This 
seems to be a Good Thing (tm).

> HTML5 even introduced additional HTML
> tags, such as <nav>.

Even better. The more semantic the better, but actual documents always 
have their own higher-level semantics.

> Styling is not a problem, since you can use CSS to
> remove the default styles from practically any layout tag, making it
> behave like <span> or <div>.

Actually as I noted above that's an issue because we share the same 
style file between dlang.org and phobos. Of course, we could have two 
files, but I don't find using classes a shameful alternative.

> If it's not too much effort, I'd revert this change, however this is
> more of a question of principle than practicality.

I think this change makes things better, but am listening to arguments 
because I'm not an expert.


Andrei