Are there any default dmd optimizations

[H. S. Teoh]

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.