On 9/16/13, Vladimir Panteleev <vladimir@thecybershadow.net> wrote:
> One noticeable difference is that parameter names are no longer italicized. Is that on purpose, or a missing .param style?

Personally I never liked this italicization, it doesn't make reading the docs any simpler or easier to me.

On Mon, Sep 16, 2013 at 08:22:49AM -0700, Andrei Alexandrescu wrote:
> On 9/16/13 6:40 AM, Vladimir Panteleev wrote:
> >What before was <dd>, now is <div class="d_decl_dd"> (and the margin was a dd style). Why this change? You can apply any properties of one to the other through CSS.
> 
> Great, thanks. Now fixed. My intent was to use <div> and <span> for styling ddoc elements to the extent possible, in order to make styling as flexible as possible. But I forgot to give the appropriate style to d_decl_dd (hopefully not others).
> 
> Destroy: http://erdani.com/d/phobos/std_array.html
[...]

OK, that looks *much* better. Thanks!


T

-- 
The volume of a pizza of thickness a and radius z can be described by the following formula: pi zz a. -- Wouter Verhelst

On Monday, 16 September 2013 at 15:22:50 UTC, Andrei Alexandrescu wrote:
> On 9/16/13 6:40 AM, Vladimir Panteleev wrote:
>> What before was <dd>, now is <div class="d_decl_dd"> (and the margin was
>> a dd style). Why this change? You can apply any properties of one to the
>> other through CSS.
>
> Great, thanks. Now fixed. My intent was to use <div> and <span> for styling ddoc elements to the extent possible, in order to make styling as flexible as possible.

Although bordering on nitpicking, I'll mention that this is not a good change. It is recommended to use the appropriate HTML elements for their semantic meaning. <dl> is a definition list, which nicely fits documenting a list of entities. HTML5 even introduced additional HTML tags, such as <nav>. Styling is not a problem, since you can use CSS to remove the default styles from practically any layout tag, making it behave like <span> or <div>.

If it's not too much effort, I'd revert this change, however this is more of a question of principle than practicality.

On 9/16/13 8:27 AM, Vladimir Panteleev wrote:
> On Monday, 16 September 2013 at 15:23:50 UTC, Andrei Alexandrescu wrote:
>> Yah, apologies. It's the same bug as noted by Vladimir. Fixed now.
>> Thanks for the feedback and keep it coming!
>
> I'm opening these in two tabs and cycling between them:
>
> http://dlang.org/phobos/std_array.html
> http://erdani.com/d/phobos/std_array.html
>
> One noticeable difference is that parameter names are no longer
> italicized. Is that on purpose, or a missing .param style?
>
> Looks good otherwise!

Great catch. Fixed, along with a couple other nits.

Andrei

On 9/16/13 8:30 AM, Andrej Mitrovic wrote:
> On 9/16/13, Andrei Alexandrescu <SeeWebsiteForEmail@erdani.org> wrote:
>> Thanks for the feedback and keep it coming!
>
> The links at the top of std_array.html don't have an underline for
> some reason, making it hard to know they're links.

I did it on purpose :o). I found the many adjacent underlines unsightly, and thought that "Jump to" would be evocative enough. Rollback?

> Also, the links are broken. E.g. RefAppencer points to this:
> http://erdani.com/d/phobos/std_array.html#RefAppender
>
> But that doesn't lead to anywhere. The old page linked to:
>
> http://dlang.org/phobos/std_array.html#.RefAppender (note the dot
> before RefAppender).

Blurgh. Fixed. BTW what's the deal with all those \xNN in the javascript?

newText += ' &nbsp;\x3Ca class="jumpto" href="\x23.' + a +
  '"\x3E\x3Cspan class="notranslate donthyphenate"\x3E' + text + '\x3C/span\x3E\x3C/a\x3E';

I guess some care must be exercised so as to not confuse the HTML/Javascript parser, but only for things like </script> and probablt a couple more. No?


Andrei

On 9/16/13 8:34 AM, Andrej Mitrovic wrote:
> On 9/16/13, Vladimir Panteleev <vladimir@thecybershadow.net> wrote:
>> One noticeable difference is that parameter names are no longer
>> italicized. Is that on purpose, or a missing .param style?
>
> Personally I never liked this italicization, it doesn't make reading
> the docs any simpler or easier to me.

I agree, i.e. the only thing I like about it is that whenever I see it I think "nice, that's customizable" :o). Destroy?

Andrei

On 9/16/13 8:55 AM, Vladimir Panteleev wrote:
> On Monday, 16 September 2013 at 15:22:50 UTC, Andrei Alexandrescu wrote:
>> On 9/16/13 6:40 AM, Vladimir Panteleev wrote:
>>> What before was <dd>, now is <div class="d_decl_dd"> (and the margin was
>>> a dd style). Why this change? You can apply any properties of one to the
>>> other through CSS.
>>
>> Great, thanks. Now fixed. My intent was to use <div> and <span> for
>> styling ddoc elements to the extent possible, in order to make styling
>> as flexible as possible.
>
> Although bordering on nitpicking, I'll mention that this is not a good
> change.

I'm here to learn.

> It is recommended to use the appropriate HTML elements for their
> semantic meaning.

[citation needed]

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

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

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

> HTML5 even introduced additional HTML
> tags, such as <nav>.

Even better. The more semantic the better, but actual documents always have their own higher-level semantics.

> Styling is not a problem, since you can use CSS to
> remove the default styles from practically any layout tag, making it
> behave like <span> or <div>.

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.

> If it's not too much effort, I'd revert this change, however this is
> more of a question of principle than practicality.

I think this change makes things better, but am listening to arguments because I'm not an expert.


Andrei

On Monday, 16 September 2013 at 16:11:15 UTC, Andrei Alexandrescu wrote:
> BTW what's the deal with all those \xNN in the javascript?
>
> newText += '  \x3Ca class="jumpto" href="\x23.' + a +
>   '"\x3E\x3Cspan class="notranslate donthyphenate"\x3E' + text + '\x3C/span\x3E\x3C/a\x3E';
>
> I guess some care must be exercised so as to not confuse the HTML/Javascript parser, but only for things like </script> and probablt a couple more. No?

Not sure if this is the reason that applies to our case, but - you can use < and > in inline scripts in HTML, but not in XHTML, which must be well-formed XML. The exception is if the script code is wrapped in a CDATA block.

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.

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

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

> 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 */
  }