I've just done a little bit of work on the ddoc documentation and it was brought to my attention that the HTML output of ddoc is actually quite old. Some of the current tags are deprecated. I've raised this as an issue here:

https://issues.dlang.org/show_bug.cgi?id=14473

Before starting on any work however, I thought there should be a discussion on what impact this would have and what tags should be used instead.

Here's a list of the current ddoc symbols (and tag output) that IMHO would need updating:

https://gist.github.com/nomad-software/333cd658ad88090dcb0a

and here are some proposed substitutions:

https://gist.github.com/nomad-software/20d2ab1f7d4c9e55a343

The changes seem quite simple but I'm wondering what knock on effect this would have on anything else? Can you see any problems this might create? Any comments on the new tags used?

The following files would need updating:
https://github.com/D-Programming-Language/dmd/blob/master/src/doc.c#L143-L186
https://github.com/D-Programming-Language/dlang.org/blob/master/ddoc.dd#L687-L720

On Monday, 20 April 2015 at 19:42:43 UTC, Gary Willoughby wrote:
> I've just done a little bit of work on the ddoc documentation and it was brought to my attention that the HTML output of ddoc is actually quite old. Some of the current tags are deprecated. I've raised this as an issue here:
>
> https://issues.dlang.org/show_bug.cgi?id=14473
>
> Before starting on any work however, I thought there should be a discussion on what impact this would have and what tags should be used instead.
>
> Here's a list of the current ddoc symbols (and tag output) that IMHO would need updating:
>
> https://gist.github.com/nomad-software/333cd658ad88090dcb0a
>
> and here are some proposed substitutions:
>
> https://gist.github.com/nomad-software/20d2ab1f7d4c9e55a343
>
> The changes seem quite simple but I'm wondering what knock on effect this would have on anything else? Can you see any problems this might create? Any comments on the new tags used?

It's possible that some of the dlang.org CSS would need to be updated too, but I like it. Always irked me to see <b> and such everywhere. It's still a long road before we even output correct HTML, but this is a nice low-effort (relatively) enhancement.

It would have to be mentioned clearly in the changelog so third-party users of DDoc can update their CSS and possibly JavaScript (although I don't expect any breakages in practice; good practice entails using classes).

> The following files would need updating:
> https://github.com/D-Programming-Language/dmd/blob/master/src/doc.c#L143-L186
> https://github.com/D-Programming-Language/dlang.org/blob/master/ddoc.dd#L687-L720

Also http://dlang.org/ddoc (Section "Predefined Macros")

On 4/20/2015 11:39 PM, Jakob Ovrum wrote:
> It's still a long road before we even output correct HTML,

??

On Tuesday, 21 April 2015 at 07:34:19 UTC, Walter Bright wrote:
> On 4/20/2015 11:39 PM, Jakob Ovrum wrote:
>> It's still a long road before we even output correct HTML,
>
> ??

Have you ever tried validating the HTML output for dlang.org? It's a mess, see this PR for some details[1].

[1] https://github.com/D-Programming-Language/dlang.org/pull/96

On 2015-04-20 21:42, Gary Willoughby wrote:

> and here are some proposed substitutions:
>
> https://gist.github.com/nomad-software/20d2ab1f7d4c9e55a343

I don't think you should use the "style" attribute at all. I think it's better to use classes, or similar.

-- 
/Jacob Carlborg

On 4/21/2015 12:39 AM, Jakob Ovrum wrote:
> On Tuesday, 21 April 2015 at 07:34:19 UTC, Walter Bright wrote:
>> On 4/20/2015 11:39 PM, Jakob Ovrum wrote:
>>> It's still a long road before we even output correct HTML,
>>
>> ??
>
> Have you ever tried validating the HTML output for dlang.org? It's a mess, see
> this PR for some details[1].
>
> [1] https://github.com/D-Programming-Language/dlang.org/pull/96

1. none of these are problems with Ddoc
2. they just look like a few typos to me
3. the PR is already merged

On Tuesday, 21 April 2015 at 23:48:04 UTC, Walter Bright wrote:
> 1. none of these are problems with Ddoc

No, but there's still a problem with dlang.org, the biggest user of DDoc.

> 2. they just look like a few typos to me

No, the main issue is nesting lists in paragraphs and other illegal nestings.

> 3. the PR is already merged

The PR only fixed the bare minimum to make it past kindlegen.

On 4/21/2015 5:45 PM, Jakob Ovrum wrote:
> On Tuesday, 21 April 2015 at 23:48:04 UTC, Walter Bright wrote:
>> 1. none of these are problems with Ddoc
>
> No, but there's still a problem with dlang.org, the biggest user of DDoc.
>
>> 2. they just look like a few typos to me
>
> No, the main issue is nesting lists in paragraphs and other illegal nestings.
>
>> 3. the PR is already merged
>
> The PR only fixed the bare minimum to make it past kindlegen.

You sound like the right person to do a PR to fix it!

On Tuesday, 21 April 2015 at 11:27:35 UTC, Jacob Carlborg wrote:
> On 2015-04-20 21:42, Gary Willoughby wrote:
>
>> and here are some proposed substitutions:
>>
>> https://gist.github.com/nomad-software/20d2ab1f7d4c9e55a343
>
> I don't think you should use the "style" attribute at all. I think it's better to use classes, or similar.

Yes it's always better to use classes and style them in a CSS file. However, in this instance these tags are used to give an immediate result regardless of whether or not an accompanying css file exists. We could also add classes to the spans in addition to the style tags in-case people wanted to use CSS files to style.

On 22/04/2015 08:47, Gary Willoughby wrote:
> On Tuesday, 21 April 2015 at 11:27:35 UTC, Jacob Carlborg wrote:
<snip>
>> I don't think you should use the "style" attribute at all. I think it's better to use
>> classes, or similar.
>
> Yes it's always better to use classes and style them in a CSS file. However, in this
> instance these tags are used to give an immediate result regardless of whether or not an
> accompanying css file exists.

Exactly.  Moreover, since these macros are designed to produce a specific presentational effect, I think specifying this presentational effect in the HTML directly is defensible.  CSS classes should ideally be semantic, rather than presentational.

> We could also add classes to the spans in addition to the
> style tags in-case people wanted to use CSS files to style.

I think that people who want to do this would probably define their own Ddoc templates to do so.  IIRC they would need to anyway, in order to make the HTML file include the <link> tag to import the CSS file.

Stewart.

-- 
My email address is valid but not my primary mailbox and not checked regularly.  Please keep replies on the 'group where everybody may benefit.