Improved Phobos dox

[Vladimir Panteleev]

On Monday, 16 September 2013 at 16:37:06 UTC, Andrei Alexandrescu 
wrote:
> On 9/16/13 8:55 AM, Vladimir Panteleev wrote:
>> If it's not too much effort, I'd revert this change, however 
>> this is
>> more of a question of principle than practicality.
>
> One more argument in favor of using style classes.
>
> Consider the bug you found - parameters were not styled in 
> italics. (Whether or not we care to keep that particular 
> formatting is a different matter.)
>
> That format was enacted as follows:
>
> DDOC_PARAM = $(I $0)
>
> which expands to <i>$0</i>. To change that in any way, one 
> would have to do surgery on some .ddoc file, rebuild, and 
> upload the entire site.
>
> Alternatively, one could, as you mentioned, restyle <i> in the 
> css file, but then not only parameters would be restyled, but 
> ALL italic text! Not good.
>
> The new definition is:
>
> DDOC_PARAM=<span class="param">$0</span>
>
> The current style is:
>
> .param
> {
> 	font-style: italic;
> }
>
> Now whenever we want to change the styling of those particular 
> elements (and only those), we edit the css file and upload it 
> again to the site. This is very simple, economic, and modular.

This is correct and I agree. I think we misunderstood each other?

I noticed the change: dd -> div. This is bad, because it reduces 
semantics.

Your example is: i -> span class="param". This is good, because 
it improves semantics.