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.
