I have a pull request up to remove the big misfeature
of embedded html in ddoc, and it is pending action,
from me, to answer some of Walter's concerns.

But, I was updating the documentation for some of my
code (using std.ddoc and my improveddoc post-processor
to make it prettier and remove Javascript), and
I hit pain.


http://arsdnet.net/web.d/std_dom.html#Form.addValueArray

It is extremely difficult to document a HTML library
when your HTML examples are mis-interpreted as
markup!


Also, ddoc should outdent the code examples:

http://arsdnet.net/web.d/std_cgi.html#Cgi.request

The examples are indented in my source to line up
with the declarations, but this indentation doesn't
make sense in the output!

On 08/04/2012 02:08, Adam D. Ruppe wrote:
> I have a pull request up to remove the big misfeature
> of embedded html in ddoc, and it is pending action,
> from me, to answer some of Walter's concerns.

What have you done - just made it convert < > & in documentation comments to &lt; &gt; &amp; before processing?

What is the user who wants some output format other than HTML or XML to do?

<snip>
> http://arsdnet.net/web.d/std_dom.html#Form.addValueArray
>
> It is extremely difficult to document a HTML library
> when your HTML examples are mis-interpreted as
> markup!

Create LT, GT and AMP macros and use them in your code examples.

> Also, ddoc should outdent the code examples:
>
> http://arsdnet.net/web.d/std_cgi.html#Cgi.request
>
> The examples are indented in my source to line up
> with the declarations, but this indentation doesn't
> make sense in the output!

I agree.  Ddoc should remove the lowest common level of indentation from each code sample it picks up.

Stewart.

Stewart.

On Monday, 9 April 2012 at 11:05:10 UTC, Stewart Gordon wrote:
> What have you done - just made it convert < > & in documentation comments to &lt; &gt; &amp; before processing?

In ddoc's source code, there was a macro called ESCAPES
already, but it wasn't actually used.

My patch enables the use of that macro and runs the input
text, before macro processing, through it.

The default is this:
ESCAPES = /</&lt;/
          />/&gt;/
          /&/&amp;/

(check out doc.c in dmd's source, it is already there)

And you can redefine it to whatever you want in your
macro file.

My patch also removes other html specific processing
in the compiler, since I'm pretty sure it is all
obsolete with an escaping run.


If you want to output html, you just make a macro:

B = <b>$1</b>

and that still works.

> What is the user who wants some output format other than HTML or XML to do?

That's the beauty of the ESCAPES macro - you can
redefine it however you want.

> Create LT, GT and AMP macros and use them in your code examples.

There's two problems with that: 1) it is hideous
and 2) what if the user wants some format other
than html?

Suppose your format escapes \. Should I defensively
make a $(BACKSLASH) macro too?

What if a dot is special?

And so on, the only correct solution is proper
escaping, and as an added bonus, it looks infinitely
better in source!

On 09/04/2012 14:34, Adam D. Ruppe wrote:
> On Monday, 9 April 2012 at 11:05:10 UTC, Stewart Gordon wrote:
<snip>
>> Create LT, GT and AMP macros and use them in your code examples.
>
> There's two problems with that: 1) it is hideous
> and 2) what if the user wants some format other
> than html?

Then they would define LT, GT and AMP differently.

> Suppose your format escapes \. Should I defensively
> make a $(BACKSLASH) macro too?
<snip>

No, since you don't have any idea in what formats I might want to generate docs for your lib.  But I would know I need to be on the lookout for characters that have a special meaning in my chosen output format.

But indeed, the ESCAPES macro is a much better solution.

Stewart.

On 4/9/12 7:05 PM, Stewart Gordon wrote:
> On 08/04/2012 02:08, Adam D. Ruppe wrote:
>> I have a pull request up to remove the big misfeature
>> of embedded html in ddoc, and it is pending action,
>> from me, to answer some of Walter's concerns.
>
> What have you done - just made it convert < > & in documentation
> comments to &lt; &gt; &amp; before processing?
>
> What is the user who wants some output format other than HTML or XML to do?

What other formats is ddoc producing right now that people are using?