On 9/16/13 11:08 AM, Vladimir Panteleev wrote:
> On Monday, 16 September 2013 at 17:59:11 UTC, Andrei Alexandrescu wrote:
>> What's a good small circular central bullet for HTML?
>
> ·

Done, looks nice. http://erdani.com/d/phobos/std_array.html

Anyhow enough with this - it's just a patch until ddox. Somebody please pull the blessed thing :o).


Andrei

On Monday, 16 September 2013 at 18:14:23 UTC, Andrei Alexandrescu wrote:
> On 9/16/13 11:08 AM, Vladimir Panteleev wrote:
>> On Monday, 16 September 2013 at 17:59:11 UTC, Andrei Alexandrescu wrote:
>>> What's a good small circular central bullet for HTML?
>>
>> ·
>
> Done, looks nice. http://erdani.com/d/phobos/std_array.html
>
> Anyhow enough with this - it's just a patch until ddox. Somebody please pull the blessed thing :o).
>
>
> Andrei

My 2 cents: links without the underline look quite counter-intuitive.
Not that I care that much, I'd rather see ddox up and running by default.

On 2013-09-16 18:22, Andrei Alexandrescu wrote:

> [citation needed]

http://en.wikipedia.org/wiki/Semantic_HTML

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

This is not LaTeX. When using the proper tags you're adding semantic meaning to your content. Example, a proper table with an header and footer should look like this:

<table>
  <thead>
    <tr>
      <th>Header</th>
      <th>Header 2</th>
    </tr>
  </thead>

  <tfoot>
    <tr>
      <td>Footer data</th>
      <td>Footer data 2</th>
    </tr>
  </tfoot>

  <tbody>
    <tr>
      <td>Data</td>
      <td>Data 2</td>
    </tr>
  </tbody>
</table>

The reason for adding proper tags like "thead", "tfoot" and "tbody" is it gives semantic meaning to the content. A browser can choose to scroll the content in "tbody" while having the content in "thead" and "tfoot".

The same idea can be applied to navigation as well. Using the "nav" tag a browser could probably choose to scroll the main content and but not the content of the "nav" tag.

> It is, but it seems to me the more specific "list of symbols introduced"
> is better.

Then you add a class in addition to the correct tag.

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

Then you use different classes, but still uses the correct tag.

Another example. If you want to emphasis text one uses the "em" tag, not the "i" tag. The it's up to the style sheet (CSS) to decide if the emphasized text should be italic, bold or some other font.

It's the same thing why one should use the type "bool" (D, C++) instead of "int". It gives the correct semantic meaning.

> Actually as I noted above that's an issue because we share the same
> style file between dlang.org and phobos. Of course, we could have two
> files, but I don't find using classes a shameful alternative.

We most likely should.

-- 
/Jacob Carlborg

On 2013-09-16 18:49, Andrei Alexandrescu wrote:

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

It's doesn't matter if it's a <dd> tag or a <div> tag. You can style both the same way.

We might want to add some style sheet that resets an unifies the default styling for all element a cross all browsers.

This is an example: http://necolas.github.io/normalize.css/

That one is used by Bootstrap and other libraries.

-- 
/Jacob Carlborg

On 9/16/13 11:18 AM, Tourist wrote:
> On Monday, 16 September 2013 at 18:14:23 UTC, Andrei Alexandrescu wrote:
>> On 9/16/13 11:08 AM, Vladimir Panteleev wrote:
>>> On Monday, 16 September 2013 at 17:59:11 UTC, Andrei Alexandrescu wrote:
>>>> What's a good small circular central bullet for HTML?
>>>
>>> ·
>>
>> Done, looks nice. http://erdani.com/d/phobos/std_array.html
>>
>> Anyhow enough with this - it's just a patch until ddox. Somebody
>> please pull the blessed thing :o).
>>
>>
>> Andrei
>
> My 2 cents: links without the underline look quite counter-intuitive.
> Not that I care that much, I'd rather see ddox up and running by default.

Sure, fixed.

Andrei

On 9/16/13 11:21 AM, Jacob Carlborg wrote:
> On 2013-09-16 18:22, Andrei Alexandrescu wrote:
>> 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".
>
> This is not LaTeX. When using the proper tags you're adding semantic
> meaning to your content.

Same principles apply to LaTeX. Anyhow, the discussions has been settled. You are right, and I got convinced.

>> Actually as I noted above that's an issue because we share the same
>> style file between dlang.org and phobos. Of course, we could have two
>> files, but I don't find using classes a shameful alternative.
>
> We most likely should.

Yah, we already have separate ddoc files for the main site and for the library. I suspect at a point we'll segregate the css files, too. We haven't gotten to the necessity yet.


Andrei

On Monday, 16 September 2013 at 17:08:02 UTC, Andrei Alexandrescu wrote:
> 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

AFAIR there has been an article about semantic web linked in this thread. I am not web dev myself by any means but general motto I hear from Internet publications on topic can be summarized as:

- HTML is for semantics, CSS is for style
- HTML should never interfere with how stuff is viewed
- HTML should be meaningful on its own, even without any CSS
- Meaning of HTML elements is standardized, not so for classes

Importance of last point is often underestimated. Screen readers have been already mentioned but it also applies for stuff like search engine robots - better HTML element selection can result in better search output.

(After traveling on Sunday and Monday, and after wondering why people still argue with me after I'd sent the message below, I opened my laptop to find it, still unsent, in Drafts. I must have forgotten to send it, or sending failed... sorry.)

On 9/16/13 10:07 AM, H. S. Teoh wrote:
> 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.

OK, I think this is a solid argument (Adam also made it but I hadn't grokked it).

So the idea here is that the specific HTML attributes do have meaning to the renderer that are difficult or impossible to specify in, or infer from, the stylesheet. A google search for divitis spanitis destroyed my former opinion.


Andrei

On Monday, 16 September 2013 at 17:08:38 UTC, H. S. Teoh wrote:
> 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.

Haven't followed the thread closely but one thing I've missed when trying to define a nicer stylesheet is something more specific that "d_decl".

d_decl is used for all declarations which means that you cannot style enums, templates, functions etc. differently in the docs.
It would be nice to have an additional class added to the class attribute. For example: class="d_decl d_enum" or class="d_decl d_template".

/Jonas