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.

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

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.

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?

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