On Wed, Feb 27, 2013 at 02:28:44AM +0100, Adam D. Ruppe wrote: > On Wednesday, 27 February 2013 at 01:03:44 UTC, Walter Bright wrote: > >It's not actually a feature of ddoc at all. Ddoc just transmits > >its input to its output, expanding macros along the way.
Alas, the real world is not quite that simple. What if the output requires certain characters to be represented differently? There is currently no way to tell ddoc, the characters \{_^}% are metacharacters in the output format, and you need to escape them using macros $(BACKSLASH), $(OPENBRACE), ... etc.. You do NOT want to require the user to manually write these macros in the comment, because then it becomes completely unreadable, as Adam pointed out. But currently, if you want to target *multiple* output formats (say, you want to produce both HTML docs for your website and PDF via LaTeX for a printed documentation), then you have no choice but write macros for the union of all metacharacters in all output formats. At which point, you might as well say that every character should be written as a macro, which is clearly ludicrous. [...] > And now if we want it to work for both html AND json, we're writing: > > $(QUOTE)$(LT)b$(GT)text$(LT)$(SLASH)b$(GR) > > > And obviously, that's absurd. What was a readable comment (which > ddoc is supposed to aspire to) is now a hideous mess of macros. > > So, you say "nobody would output ddoc to json", but this is just one > easy example with different encoding rules than html. LaTeX I'm > pretty sure needs you to escape the backslash. I'm not sure, I've > barely used latex, so I wouldn't use those macros in my own code. LaTeX is a far more complex beast than one might imagine at first glance. Not only backslashes need to be escaped, under standard conditions you need to also escape: $ { } ~ -- --- & _ ^ \ % (Yes, multi-character sequences are included.) Not to mention that D source code is UTF-8, but standard LaTeX is not, which means characters like ΓΌ need to be output as \"u instead. Furthermore, there are very precise spacing rules, like \ is required following a '.' if it's not a sentence break (e.g., in "Mr. Appleseed"), otherwise the output formatting may have the wrong spacing. Now I said standard conditions. There's math mode, which you will end up in if you leave stray $'s lying around (but which, say, math-oriented software might want to actually use for typesetting equations and the like in the documentation), which has a *different* set of metacharacters, and all *spaces* must be escaped. The only thorough solution for a multi-target ddoc comment currently is to write the entire comment in macros. This is an unreasonable expectation, which also detracts greatly from one's desire to actually use ddoc for this purpose. > What if somebody else wants to apply his set of latex macros to my > code file expecting it to just work? It probably won't. > > And, again, this is very easy to solve in the vast majority of > cases: put that ESCAPES macro to good use by running it over the > input data ASAP. Then the data will be properly encoded for whatever > formats we need, without needing these bad preemptive macros. The ESCAPES macro will not completely solve the problem with formats like LaTeX, but it will help greatly. It will also nudge me slightly in the direction of embracing ddoc from my current position on the fence. ;-) T -- Computers are like a jungle: they have monitor lizards, rams, mice, c-moss, binary trees... and bugs.