Thread overview | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
April 20, 2015 Updating ddoc to support modern HTML tags | ||||
---|---|---|---|---|
| ||||
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 |
April 21, 2015 Re: Updating ddoc to support modern HTML tags | ||||
---|---|---|---|---|
| ||||
Posted in reply to Gary Willoughby | 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") |
April 21, 2015 Re: Updating ddoc to support modern HTML tags | ||||
---|---|---|---|---|
| ||||
Posted in reply to Jakob Ovrum | On 4/20/2015 11:39 PM, Jakob Ovrum wrote:
> It's still a long road before we even output correct HTML,
??
|
April 21, 2015 Re: Updating ddoc to support modern HTML tags | ||||
---|---|---|---|---|
| ||||
Posted in reply to Walter Bright | 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 |
April 21, 2015 Re: Updating ddoc to support modern HTML tags | ||||
---|---|---|---|---|
| ||||
Posted in reply to Gary Willoughby | 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 |
April 21, 2015 Re: Updating ddoc to support modern HTML tags | ||||
---|---|---|---|---|
| ||||
Posted in reply to Jakob Ovrum | 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
|
April 22, 2015 Re: Updating ddoc to support modern HTML tags | ||||
---|---|---|---|---|
| ||||
Posted in reply to Walter Bright | 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. |
April 22, 2015 Re: Updating ddoc to support modern HTML tags | ||||
---|---|---|---|---|
| ||||
Posted in reply to Jakob Ovrum | 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!
|
April 22, 2015 Re: Updating ddoc to support modern HTML tags | ||||
---|---|---|---|---|
| ||||
Posted in reply to Jacob Carlborg | 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.
|
April 25, 2015 Re: Updating ddoc to support modern HTML tags | ||||
---|---|---|---|---|
| ||||
Posted in reply to Gary Willoughby | 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. |
Copyright © 1999-2021 by the D Language Foundation