digitalmars.D - Updating ddoc to support modern HTML tags
- Gary Willoughby (19/19) Apr 20 2015 I've just done a little bit of work on the ddoc documentation and
- Jakob Ovrum (10/29) Apr 20 2015 It's possible that some of the dlang.org CSS would need to be
- Walter Bright (2/3) Apr 21 2015 ??
- Jakob Ovrum (4/7) Apr 21 2015 Have you ever tried validating the HTML output for dlang.org?
- Walter Bright (4/12) Apr 21 2015 1. none of these are problems with Ddoc
- Jakob Ovrum (6/9) Apr 21 2015 No, but there's still a problem with dlang.org, the biggest user
- Walter Bright (2/9) Apr 21 2015 You sound like the right person to do a PR to fix it!
- Jacob Carlborg (5/7) Apr 21 2015 I don't think you should use the "style" attribute at all. I think it's
- Gary Willoughby (6/12) Apr 22 2015 Yes it's always better to use classes and style them in a CSS
- Stewart Gordon (12/20) Apr 25 2015 Exactly. Moreover, since these macros are designed to produce a specifi...
-
Stewart Gordon
(32/36)
Apr 25 2015
- Andrei Alexandrescu (7/14) Apr 25 2015 Make this a hackathon project! We've improved the default ddoc template
- Stewart Gordon (8/15) Apr 26 2015 LaTeX is where? The "text only" and "verbatim" ddoc files are where? I...
- Andrei Alexandrescu (2/15) Apr 27 2015 https://github.com/D-Programming-Language/dlang.org -- Andrei
- Kagamin (5/10) Apr 27 2015 More importantly, ddoc need semantic-oriented markup tags, see
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
Apr 20 2015
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-L720Also http://dlang.org/ddoc (Section "Predefined Macros")
Apr 20 2015
On 4/20/2015 11:39 PM, Jakob Ovrum wrote:It's still a long road before we even output correct HTML,??
Apr 21 2015
On Tuesday, 21 April 2015 at 07:34:19 UTC, Walter Bright wrote:On 4/20/2015 11:39 PM, Jakob Ovrum wrote: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/96It's still a long road before we even output correct HTML,??
Apr 21 2015
On 4/21/2015 12:39 AM, Jakob Ovrum wrote:On Tuesday, 21 April 2015 at 07:34:19 UTC, Walter Bright wrote:1. none of these are problems with Ddoc 2. they just look like a few typos to me 3. the PR is already mergedOn 4/20/2015 11:39 PM, Jakob Ovrum wrote: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/96It's still a long road before we even output correct HTML,??
Apr 21 2015
On Tuesday, 21 April 2015 at 23:48:04 UTC, Walter Bright wrote:1. none of these are problems with DdocNo, but there's still a problem with dlang.org, the biggest user of DDoc.2. they just look like a few typos to meNo, the main issue is nesting lists in paragraphs and other illegal nestings.3. the PR is already mergedThe PR only fixed the bare minimum to make it past kindlegen.
Apr 21 2015
On 4/21/2015 5:45 PM, Jakob Ovrum wrote:On Tuesday, 21 April 2015 at 23:48:04 UTC, Walter Bright wrote:You sound like the right person to do a PR to fix it!1. none of these are problems with DdocNo, but there's still a problem with dlang.org, the biggest user of DDoc.2. they just look like a few typos to meNo, the main issue is nesting lists in paragraphs and other illegal nestings.3. the PR is already mergedThe PR only fixed the bare minimum to make it past kindlegen.
Apr 21 2015
On 2015-04-20 21:42, Gary Willoughby wrote:and here are some proposed substitutions: https://gist.github.com/nomad-software/20d2ab1f7d4c9e55a343I don't think you should use the "style" attribute at all. I think it's better to use classes, or similar. -- /Jacob Carlborg
Apr 21 2015
On Tuesday, 21 April 2015 at 11:27:35 UTC, Jacob Carlborg wrote:On 2015-04-20 21:42, Gary Willoughby wrote: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.and here are some proposed substitutions: https://gist.github.com/nomad-software/20d2ab1f7d4c9e55a343I don't think you should use the "style" attribute at all. I think it's better to use classes, or similar.
Apr 22 2015
On 22/04/2015 08:47, Gary Willoughby wrote:On Tuesday, 21 April 2015 at 11:27:35 UTC, Jacob Carlborg wrote:<snip>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.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.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.
Apr 25 2015
On 20/04/2015 20:42, Gary Willoughby wrote: <snip>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<snip> A few issues with some of these: - B - According to http://dlang.org/ddoc.html the meaning is "boldface the argument" (a presentational concept) as opposed to "place strong emphasis on the argument" (a semantic concept), and so the appropriate markup is <b>, or maybe <span style="font-weight: bold;">. Though it would be more appropriate still to have a macro whose semantic meaning is "strong emphasis". - I - similar issue here. - SMALL - this is absent from your version with substitutions, but you have used it nonetheless. (FTR, HTML5 redefines <small> as meaning 'small print' in the idiomatic sense. But Ddoc still defines SMALL as "argument is one font size smaller" - thereby begging the question of what "one font size" means exactly.) - D_CODE and D_INLINECODE - changing from <pre> to <code> has a number of consequences: -- reinstates the collapsing of whitespace - the whole point of <pre> is to suppress this -- changes the node from block-level to inline (at least according to the W3C validator, which matches my inkling, though the HTML 4.01 spec seems to contradict this). But D_INLINECODE was broken as it is by trying to use a block-level element as an inline element. So D_CODE should probably use <pre> (or possibly <pre><code>, as I have taken to using), whereas D_INLINECODE should probably use <code>. This would then break only the inline code snippets that relied on whitespace being preserved. But last time I knew, the default Ddoc template as a whole was generally incapable of producing logically structured HTML output, never mind which tags are used. I ended up redefining a number of the macros in my custom Ddoc template to get around this. Even then, I wasn't able to do it perfectly. Has anybody tried to use Ddoc to generate (for example) LaTeX, RTF, XML or JSON output, for that matter? In my mind, any well-designed documentation macro system should be capable of doing all these. 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.
Apr 25 2015
On 4/25/15 5:41 PM, Stewart Gordon wrote:But last time I knew, the default Ddoc template as a whole was generally incapable of producing logically structured HTML output, never mind which tags are used. I ended up redefining a number of the macros in my custom Ddoc template to get around this.Make this a hackathon project! We've improved the default ddoc template (and others) a fair bit over time.Even then, I wasn't able to do it perfectly. Has anybody tried to use Ddoc to generate (for example) LaTeX, RTF, XML or JSON output, for that matter?LaTeX is there. I also wrote "text only" and "verbatim" ddoc files, they're all there in the distribution. There are a few issues with JSON that could be easily fixed but seems like a low impact issue. Andrei
Apr 25 2015
On 26/04/2015 03:58, Andrei Alexandrescu wrote:On 4/25/15 5:41 PM, Stewart Gordon wrote:<snip>LaTeX is where? The "text only" and "verbatim" ddoc files are where? I've just downloaded the latest DMD package and can't see any sign of these anywhere. 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.Even then, I wasn't able to do it perfectly. Has anybody tried to use Ddoc to generate (for example) LaTeX, RTF, XML or JSON output, for that matter?LaTeX is there. I also wrote "text only" and "verbatim" ddoc files, they're all there in the distribution. There are a few issues with JSON that could be easily fixed but seems like a low impact issue.
Apr 26 2015
On 4/26/15 12:56 PM, Stewart Gordon wrote:On 26/04/2015 03:58, Andrei Alexandrescu wrote:https://github.com/D-Programming-Language/dlang.org -- AndreiOn 4/25/15 5:41 PM, Stewart Gordon wrote:<snip>LaTeX is where? The "text only" and "verbatim" ddoc files are where?Even then, I wasn't able to do it perfectly. Has anybody tried to use Ddoc to generate (for example) LaTeX, RTF, XML or JSON output, for that matter?LaTeX is there. I also wrote "text only" and "verbatim" ddoc files, they're all there in the distribution. There are a few issues with JSON that could be easily fixed but seems like a low impact issue.
Apr 27 2015
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=14473More importantly, ddoc need semantic-oriented markup tags, see https://issues.dlang.org/show_bug.cgi?id=2060 RED? Why RED? What if a site visual style is black and white, still RED?
Apr 27 2015