www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - ddoc changes

reply "Adam D. Ruppe" <destructionator gmail.com> writes:
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.
Feb 18 2012
next sibling parent reply "Adam D. Ruppe" <destructionator gmail.com> writes:
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
Feb 18 2012
parent "Adam D. Ruppe" <destructionator gmail.com> writes:
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
Feb 18 2012
prev sibling parent reply Jonathan M Davis <jmdavisProg gmx.com> writes:
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
Feb 18 2012
parent "Adam D. Ruppe" <destructionator gmail.com> writes:
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.
Feb 18 2012