Improved Phobos dox

Adam D. Ruppe destructionator at gmail.com
Mon Sep 16 10:02:32 PDT 2013


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.


More information about the Digitalmars-d mailing list