On Monday, 16 September 2013 at 16:49:25 UTC, Andrei Alexandrescu wrote:
> Now you're arguing that <dd class="param"> is better than <div class="param">. This is more interesting, and I'd like to get convinced one way or another.

The difference is the <dd> is part of a list. <div> is just a division of the webpage.

If you were using a generic program to fetch all the lists on the page, that could find <dd> better than it could find a <div>. Such a generic program might be a search engine, a screen reader, a customized browser, or something like my old improveddoc.d program. (Though the latter, being custom made for this site, could just use class names too.)

You lose nothing by using the most applicable tag, and gain the potential that generic programs will understand your page better.


BTW, you should use as many classes as possible as well. I think each and every ddoc macro should have its own html class. Even if you never use them in the css file, they can be useful for third party analyzer tools. improveddoc.d used a few hacks to reconstruct some ddoc semantics lost in the old setup - knowing that <i> was actually a param for instance, so good to see that fixed.


> For my part I prefer the minimal commitment of <div> - just leave it to the style to decide how to go about things.

The stylesheet has full control of appearance regardless of the tag. You can make a <dd> look like a rainbow circle with invisible text on the top of the page if you want to, or make it plain inline text. Same as <div>, <span>, or (almost*) anything else.

* browser bugs might come into play but they aren't supposed to.

On 9/16/13 9:57 AM, Dicebot wrote:
> On Monday, 16 September 2013 at 16:49:25 UTC, Andrei Alexandrescu wrote:
>> ...
>
> Sounds like you are exactly arguing over the concept of semantic web and
> related tools. Which is a bit weird because it basically repeats the
> debates from various web world articles I have been reading almost 5
> years ago :P Maybe we should use established wisdom of people who are
> doomed to deal with it on daily basis? :P

What is the established wisdom?

Andrei

On 9/16/13 9:56 AM, Vladimir Panteleev wrote:
> Right. I think I found the source of the misunderstanding: the idea is
> not to depend on the default formatting of <dd> - the idea is to remove
> the default styles using CSS, then use it like <div>, which is what the
> old code did.

I don't understand this paragraph.

Andrei

On Mon, Sep 16, 2013 at 06:49:01PM +0200, Vladimir Panteleev wrote:
> On Monday, 16 September 2013 at 16:44:56 UTC, Andrei Alexandrescu wrote:
> >I don't find disagreement with what I said.
> >[...]
> >Nice, but what I see here is "different", not "better".
> 
> I think we may be disagreeing regarding different things.
> 
> >>You could use both (<dl class="d_decl">) if you like.
> >
> >I guess '<dl class="d_decl">' is one iota more specific than '<div class="d_decl">' and would help if one wanted to view the HTML without any accompanying CSS. I doubt this is a goal to pursue.
> 
> I refer to my original argument about how this is borderline-nitpicking. I'd like to add, however, that user-agents such as screen readers might behave better when using appropriate HTML tags.

I can attest to that. I'm on another mailing list where one of the list members is sight-impaired, and she complains about how some websites (i.e. those that suffer from heavy divitis and spanitis) simply can't be read in any sane way by the screen reader. Using built-in semantic tags like <dl> can make a world of difference for these users, since the screen reader has no idea what class="d_decl" means, but it *does* know what <dl> means. I wouldn't be so quick to dismiss it.


T

-- 
It is the quality rather than the quantity that matters. -- Lucius Annaeus Seneca

On Mon, Sep 16, 2013 at 06:31:11PM +0200, Andrej Mitrovic wrote:
> On 9/16/13, Andrei Alexandrescu <SeeWebsiteForEmail@erdani.org> wrote:
> > I did it on purpose :o). I found the many adjacent underlines unsightly, and thought that "Jump to" would be evocative enough. Rollback?
> 
> Well, it looks like one giant sentence instead of a set of links, especially since some are capitalized and some are not. Perhaps separate them with a bullet? E.g.:
> 
> Appender • RefAppender • appender • array • assocArray • back...
> 
> I don't know. :]

I like the idea of delimiting with bullets.


T

-- 
Perhaps the most widespread illusion is that if we were in power we would behave very differently from those who now hold it---when, in truth, in order to get power we would have to become very much like them. -- Unknown

Am 16.09.2013 12:45, schrieb Andrei Alexandrescu:
> On 9/15/13 11:34 PM, Sönke Ludwig wrote:
>> I need some form of authoritative decision on how to go about making (or
>> not making) the transition before I can start to work on the necessary
>> changes to the make file and the rest of the site. There is a suggestion
>> I made in the pull request:
>>
>> https://github.com/D-Programming-Language/dlang.org/pull/267
>
> What other changes need to be made in addition to what's in 267 now?
>
> Andrei

My idea was to make a proper transition from the current docs to the new ones using a different path. Quoting from the pull:

 - Adjust the make file so that the ddox documentation goes to "library/" and "library-prerelease/" instead of "phobos/" - leave the original documentation there
 - Keep the main documentation links pointed to "phobos/", but add a small secondary link to "library/"
 - (Optional) In the ddox documentation, add a link at the top of each page to the corresponding old doc page
 - Make the pull in this state
 - Incorporate improvements for a while and eventually exchange the links, making "library/" the default

Maybe with "api" instead of "library".

The current state is that the new docs have a separate make target that needs to be invoked explicitly, but it will write to the same "phobos" folder.

On 9/16/13 10:01 AM, Brad Anderson wrote:
> On Monday, 16 September 2013 at 16:49:25 UTC, Andrei Alexandrescu wrote:
>> On 9/16/13 9:44 AM, Vladimir Panteleev wrote:
>>> I noticed the change: dd -> div. This is bad, because it reduces
>>> semantics.
>>
>> The change was from unqualified <dd> to <div class="param">. Big
>> difference.
>>
>> Now you're arguing that <dd class="param"> is better than <div
>> class="param">. This is more interesting, and I'd like to get
>> convinced one way or another.
>>
>> For my part I prefer the minimal commitment of <div> - just leave it
>> to the style to decide how to go about things. So I have minimal
>> hardcoding of semantics in the generated html, and maximum flexibility
>> in the CSS - I can get to hide the thing altogether, or format it in
>> ways that are very different from classic <dd>.
>>
>>> Your example is: i -> span class="param". This is good, because it
>>> improves semantics.
>>
>> Great.
>>
>>
>> Andrei
>
> Why not just make every element a div with a class in that case?

The point of using specific elements is to get their default attributes "for free". Otherwise one would need to specify a bunch in the class definitions.

I can see how using specific elements may help the browser if the user alters the defaults.

> There is a reason HTML 4 offered many element types and HTML 5 expanded
> this even more so.  It improves code readability and has other benefits
> beyond that including assisting screen readers and other accessibility
> services for disabled people.
>
> http://coding.smashingmagazine.com/2013/01/18/the-importance-of-sections/

Sections would be nice to use.


Andrei

On 9/16/13 10:02 AM, Adam D. Ruppe wrote:
> On Monday, 16 September 2013 at 16:49:25 UTC, Andrei Alexandrescu wrote:
>> Now you're arguing that <dd class="param"> is better than <div
>> class="param">. This is more interesting, and I'd like to get
>> convinced one way or another.
>
> The difference is the <dd> is part of a list. <div> is just a division
> of the webpage.
>
> If you were using a generic program to fetch all the lists on the page,
> that could find <dd> better than it could find a <div>. Such a generic
> program might be a search engine, a screen reader, a customized browser,
> or something like my old improveddoc.d program. (Though the latter,
> being custom made for this site, could just use class names too.)
>
> You lose nothing by using the most applicable tag, and gain the
> potential that generic programs will understand your page better.

Weakly agreed.

> BTW, you should use as many classes as possible as well. I think each
> and every ddoc macro should have its own html class. Even if you never
> use them in the css file, they can be useful for third party analyzer
> tools. improveddoc.d used a few hacks to reconstruct some ddoc semantics
> lost in the old setup - knowing that <i> was actually a param for
> instance, so good to see that fixed.

The problem now is I need to worry about two things: class _and_ element. With div/span I only need to worry about paragraph/inline (a simpler Boolean decision) and class.


Andrei

On Monday, 16 September 2013 at 17:14:01 UTC, Andrei Alexandrescu wrote:
> On 9/16/13 10:01 AM, Brad Anderson wrote:
>> On Monday, 16 September 2013 at 16:49:25 UTC, Andrei Alexandrescu wrote:
>>> On 9/16/13 9:44 AM, Vladimir Panteleev wrote:
>>>> I noticed the change: dd -> div. This is bad, because it reduces
>>>> semantics.
>>>
>>> The change was from unqualified <dd> to <div class="param">. Big
>>> difference.
>>>
>>> Now you're arguing that <dd class="param"> is better than <div
>>> class="param">. This is more interesting, and I'd like to get
>>> convinced one way or another.
>>>
>>> For my part I prefer the minimal commitment of <div> - just leave it
>>> to the style to decide how to go about things. So I have minimal
>>> hardcoding of semantics in the generated html, and maximum flexibility
>>> in the CSS - I can get to hide the thing altogether, or format it in
>>> ways that are very different from classic <dd>.
>>>
>>>> Your example is: i -> span class="param". This is good, because it
>>>> improves semantics.
>>>
>>> Great.
>>>
>>>
>>> Andrei
>>
>> Why not just make every element a div with a class in that case?
>
> The point of using specific elements is to get their default attributes "for free". Otherwise one would need to specify a bunch in the class definitions.
>
> I can see how using specific elements may help the browser if the user alters the defaults.
>

The point is the semantics, not the default styling.  The default styling exists just to give them a sane default to work with.

On Monday, 16 September 2013 at 17:08:21 UTC, Andrei Alexandrescu wrote:
> On 9/16/13 9:56 AM, Vladimir Panteleev wrote:
>> Right. I think I found the source of the misunderstanding: the idea is
>> not to depend on the default formatting of <dd> - the idea is to remove
>> the default styles using CSS, then use it like <div>, which is what the
>> old code did.
>
> I don't understand this paragraph.

You presented the example regarding replacing <i> with <div class="param">. We agree that this is a good change.

I understood that your argument against using <dd> is its *stylistic* (not semantic) properties: by default, a <dd> has additional CSS styles that are not present on <div> tags.

We agreed that tags that have only stylistic properties, such as <i>, should not be used. <i> has no semantic meaning (its recommended replacement is <em>, short for "emphasized", which has the same default stylistic properties, but now also has semantic meaning).

I understood that you applied the above arguments together, to conclude that <dd> should not be used for the same reasons that that <i> should not be used - <i> has the same semantic properties as <span>.

However, the difference between <dd> and <div class="d_decl_dd"> is that the former has semantics which the latter doesn't. (To clarify, by "semantics" I mean meaning that can be useful to user-agents reading the HTML, such as screen readers.)