Improved Phobos dox

Mon Sep 16 09:44:54 PDT 2013

On 9/16/13 9:30 AM, Vladimir Panteleev wrote:
> On Monday, 16 September 2013 at 16:22:13 UTC, Andrei Alexandrescu wrote:
>> [citation needed]
>
> Sure, here you go:
>
> https://en.wikipedia.org/wiki/Semantic_HTML

I don't find disagreement with what I said.

>> 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".
>
> Well, the big difference with TeX and HTML is that with *TeX, you
> distribute the output, whereas with HTML, you distribute the source code
> - which can be interpreted by user agents other than web browsers
> rendering the page on a computer display.
>
>>> <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.
>
> 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.

>> 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).
>
> Good thing for that C in CSS! :) If you add a class to the <html> or
> <body> tag (or any other tag that wraps all symbol definitions), which
> only appears on Phobos documentation pages, you can create a CSS rule
> that only applies to those pages. E.g.:
>
> HTML:
>    <body class="library_dox">
>    ...
>    <dd>
>
> CSS:
>    .library_dox dd {
>      /* applies only to dd tags in library dox pages */
>    }

Nice, but what I see here is "different", not "better".

Andrei