ddoc has some flaws that I'd like to fix.

The first one is that it passes stuff directly to the output,
without encoding the characters.

Consider the following comment, that you might see in a html
library:

/// Given this html: <b>bold</b>, you can assert(element.tagName == "b");


You don't see <b>bold</b> in the ddoc output. You see bold text. That's
wrong.

  a) It makes documenting html things a huge pain
  b) It ties ddoc to one particular output.

     Suppose I want to output this to pdf or something. It won't
     have the same content there; you'll see <b> (as I intended),
     which is different than html output.

  c) It encourages non-portable documentation. You might write html
     in there intending to render it, which obviously won't work
     right for non-html output.

     Suppose you manually encode it. $(LT)b$(GT)bold$(LT)/$(GT).

     Not only is that hideous - not readable anymore in source form -
     it is *still* wrong for certain output! What if the / needed to
     be escaped for my other format? Are you going to make every
     character a macro, just in case someone needs it?


My proposal is to encode all content, before macro expansion,
using an escape table.

/**
Macros:
BOLD=<b>$1</b>
ESCAPES = \
    /</&lt;/\
    />/&gt;/\
    /&/&amp;/


I can now write <b>html</b> and show the content correctly,
without breaking the $(BOLD bold macro).
*/


If you want to output html code to be interpreted by the browser,
you must use a macro instead of writing it directly in the source.


Downside of this implementation is stuff in the macros is never
escaped. You might want that... but that's a lot harder to set up.


Pre-encoding all the content before macro expansion is relatively
easy. I've already implemented it in a fork of my compiler; was
actually only a few lines.




Any objections here? I know some old files used direct html in
their ddoc, and this is going to break that, but I think it is
well, well, worth it. I think most new ddoc has been moving away
from that anyway.



For my next post, I'll talk about my plan to fix up the anchors
and attributes too.

On Saturday, 18 February 2012 at 22:05:40 UTC, Adam D. Ruppe wrote:
> I've already implemented it in a fork of my compiler; was
> actually only a few lines.

Here's a link to the code:

https://github.com/adamdruppe/dmd/commit/6aa03d529794bdf048526da908eea808d7f40bd1

On Saturday, 18 February 2012 at 22:11:56 UTC, Adam D. Ruppe wrote:
> Here's a link to the code:

Well, it was a little more than that. Less, actually. Had
to cut some old stuff out to avoid double encoding:

https://github.com/adamdruppe/dmd/commit/2dc42a7c68af7f4b3e3deb3e8951060993bcb905#commitcomment-981738

On Saturday, February 18, 2012 23:05:39 Adam D. Ruppe wrote:
> If you want to output html code to be interpreted by the browser, you must use a macro instead of writing it directly in the source.

There are definitely cases where I've had to use naked HTML for links, because the macros didn't do what I needed, but arguably that just means that the macros need to be improved.

> Any objections here? I know some old files used direct html in their ddoc, and this is going to break that, but I think it is well, well, worth it. I think most new ddoc has been moving away from that anyway.

In general, it certainly sounds like the right approach, though actually doing it in practice may reveal some issues. Certainly in general, ddoc should be using macros rather than HTML. My only concern is the cases where you actually need HTML for some reason (as unideal as that may be). But maybe for that, a macro could be created which specifically wrapped HTML.

- Jonathan M Davis

On Saturday, 18 February 2012 at 22:47:49 UTC, Jonathan M Davis wrote:
> My only concern is the cases where you actually need HTML for some reason (as unideal as that may be). But maybe for that, a macro could be created which specifically wrapped HTML.

Indeed, it isn't too bad:

/**
	$(my_html)

	Macros:
	my_html=<b>I can still write <i>html</i> by using a macro</b>.
	  I can even go through <br>many lines<br>.
*/

That would still work.