www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - More ddoc complaints

reply "Adam D. Ruppe" <destructionator gmail.com> writes:
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!
Apr 07 2012
next sibling parent reply Stewart Gordon <smjg_1998 yahoo.com> writes:
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.
Apr 09 2012
next sibling parent Stewart Gordon <smjg_1998 yahoo.com> writes:
On 09/04/2012 14:34, Adam D. Ruppe wrote:
 On Monday, 9 April 2012 at 11:05:10 UTC, Stewart Gordon wrote:

 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?

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.
Apr 09 2012
prev sibling parent Ary Manzana <ary esperanto.org.ar> writes:
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?
Apr 09 2012
prev sibling parent "Adam D. Ruppe" <destructionator gmail.com> writes:
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!
Apr 09 2012