DLang Spec rewrite (?)

[H. S. Teoh]

On Sat, May 25, 2013 at 08:28:06PM -0400, Andrei Alexandrescu wrote:
[...]
> My attitude on DDoc has evolved in threes:
> 
> 3 minutes: "wtf is this crap"
> 3 hours: "this sucks"
> 3 days: "grumble I'll make do with this although it totally sucks"
> 3 months: "this is pretty darn good"

LOL... Though for me, I think I stopped at the third step (or slightly
past that).


> To generate several formats from one source, a macro system is
> needed. One interesting thing I figured about macro systems is
> they're all dirty - they can't be really considered "languages"
> because they intermix the programming part with the very output
> generated. So, what macro system would you use? (Actual question.)
> Look at m4 - it won't win any beauty contests, either, and it's
> enormously complicated. DDoc is simple for what it does, it has
> somehow hit a sweet spot.
[...]

I don't know, to me DDoc is still lacking a major feature: a mechanism
for per-character translation. The problem is that many output formats
have a different scheme of metacharacters, and some (most notably LaTeX)
require special transcription of certain characters. Right now, the only
way to handle this correctly in DDoc is very painful: write macros for
every special character and logical entity (like mdash, nbsp, and the
like), which makes it very hard to write. Your text would look like:

	$(T)his is Mr$(DOT)$(NBSP)T$(APOS)s $(DOLLAR)0$(DOT)02
	recip$(EACUTE)$(MDASH)as seen on TV$(DOT)

This problem is mostly evaded when you're targeting a single output
format. Once you start targeting more than a single output format, the
number of required macros grow exponentially. Making the DDoc source
targetable to *arbitrary* output formats requires practically wrapping
every character inside a macro, which is impractical.

To work around this problem with the current version of DDoc, you'd need
an external utility to do the transcriptions for you, which is a hassle.


T

-- 
Real men don't take backups. They put their source on a public
FTP-server and let the world mirror it. -- Linus Torvalds