digitalmars.D - More ddoc complaints
- Adam D. Ruppe (16/16) Apr 07 2012 I have a pull request up to remove the big misfeature
- Stewart Gordon (10/22) Apr 09 2012 What have you done - just made it convert < > & in documentation
- Adam D. Ruppe (29/34) Apr 09 2012 In ddoc's source code, there was a macro called ESCAPES
- Stewart Gordon (10/17) Apr 09 2012 Then they would define LT, GT and AMP differently.
- Ary Manzana (2/9) Apr 09 2012 What other formats is ddoc producing right now that people are using?
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
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 < > & 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
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 < > & 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 = /</</ />/>/ /&/&/ (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
Stewart Gordon <smjg_1998 yahoo.com> On 09/04/2012 14:34, Adam D. Ruppe wrote:On Monday, 9 April 2012 at 11:05:10 UTC, Stewart Gordon wrote:<snip>Then they would define LT, GT and AMP differently.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?<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.
Apr 09 2012
On 4/9/12 7:05 PM, Stewart Gordon wrote:On 08/04/2012 02:08, Adam D. Ruppe wrote:What other formats is ddoc producing right now that people are using?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 < > & before processing? What is the user who wants some output format other than HTML or XML to do?
Apr 09 2012