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. :]

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.


Andrei

On 9/16/13 9:28 AM, Adam D. Ruppe wrote:
> On Monday, 16 September 2013 at 16:22:13 UTC, Andrei Alexandrescu wrote:
>>> <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.
>
> <dl class="d_decl">
> <dd class="d_class"> or whatever
>
>
> Use the closest tag name to what it is, and then put a class in there to
> get more specific.

Why? To me it seems it makes no difference. Both are phrases that mean "this is a D declaration".

Andrei

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.

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

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.

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

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.

(I assume that "param" is now used with the meaning of the abstract value of the "class" HTML attribute, in contrast to its previous occurrence as the literal "param" CSS class from the <i> example)

> 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.

Is the Wikipedia link I posted earlier not applicable? I believe it discusses why it is beneficial to use HTML tags that reflect, or reflect closely the semantics of their contents. E.g. <nav> instead of <div> for navigation blocks, <address> instead of <span> for addresses, and respectively <dd> instead of <div> for definition lists.

> 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>.

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.

(Apologies to everyone for, once again, blowing up a nitpick matter into an overgrown discussion of a dozen posts.)

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

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?

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/