www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Updating ddoc to support modern HTML tags

reply "Gary Willoughby" <dev nomad.so> writes:
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
next sibling parent reply "Jakob Ovrum" <jakobovrum gmail.com> writes:
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")
Apr 20 2015
parent reply Walter Bright <newshound2 digitalmars.com> writes:
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
parent reply "Jakob Ovrum" <jakobovrum gmail.com> writes:
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
Apr 21 2015
parent reply Walter Bright <newshound2 digitalmars.com> writes:
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
Apr 21 2015
parent reply "Jakob Ovrum" <jakobovrum gmail.com> writes:
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.
Apr 21 2015
parent Walter Bright <newshound2 digitalmars.com> writes:
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!
Apr 21 2015
prev sibling next sibling parent reply Jacob Carlborg <doob me.com> writes:
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
Apr 21 2015
parent reply "Gary Willoughby" <dev nomad.so> writes:
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.
Apr 22 2015
parent Stewart Gordon <smjg_1998 yahoo.com> writes:
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.
Apr 25 2015
prev sibling next sibling parent reply Stewart Gordon <smjg_1998 yahoo.com> writes:
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
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
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
parent reply Stewart Gordon <smjg_1998 yahoo.com> writes:
On 26/04/2015 03:58, Andrei Alexandrescu wrote:
 On 4/25/15 5:41 PM, Stewart Gordon wrote:
<snip>
 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.
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.
Apr 26 2015
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 4/26/15 12:56 PM, Stewart Gordon wrote:
 On 26/04/2015 03:58, Andrei Alexandrescu wrote:
 On 4/25/15 5:41 PM, Stewart Gordon wrote:
<snip>
 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.
LaTeX is where? The "text only" and "verbatim" ddoc files are where?
https://github.com/D-Programming-Language/dlang.org -- Andrei
Apr 27 2015
prev sibling parent "Kagamin" <spam here.lot> writes:
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
More 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