Updating ddoc to support modern HTML tags

[Stewart Gordon via Digitalmars-d]

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.