DLang Spec rewrite (?)

[H. S. Teoh]

On Sun, May 26, 2013 at 03:03:30AM -0400, Andrei Alexandrescu wrote:
> On 5/26/13 2:03 AM, H. S. Teoh wrote:
> >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.
> 
> ESCAPES has been recently defined to partially fix that.

Is it working now?


> Also, LaTeX has about the same limitation. Someone defined an
> "ActiveTeX" derivative in which each character was active (and
> therefore potentially definable as a macro). As far as I know it
> didn't catch up, which may be a sign that people were okay without
> that capability.
[...]

Oh? I thought TeX already had the capability. Well, at least, you could
redefine the default escape character "\" to be basically anything,
including a letter, so you can achieve strange things that way. I'm not
saying that's a good design though.

What I'm more concerned with was how to write DDocs that targets output
formats with incompatible metacharacters or different foreign character
encodings. For example, if the docs contained a character like é, I'd
like to be able to specify that it should be translated to \'e when
targeting LaTeX, and left as-is in HTML, for example. I *could* define a
macro $(EACUTE) for this purpose, of course, but it makes writing DDocs
rather painful (why should I resort to $(EACUTE) if the DDoc input is
already UTF-8 and can already represent such a character directly?).

Another annoyance, that somebody else already mentioned, is how to wrap
paragraphs in $(P ...) correctly, as is required for (X)HTML. Currently
we only have linebreaks, which does not reliably translate to <p> and
</p> with the correct nesting. I've tried to hack around that but still
cannot get it working correctly in all possible cases. This is rather
disappointing, since DDoc itself already defines what a paragraph is (or
at least claims to), yet it doesn't easily lend itself to correct <p>
nesting. One shouldn't have to dictate the manual use of $(P) in code
docs in order to generate correct output.

So in short, DDoc as it stands is quite a nice, clean, well-designed
macro expansion system, but it falls a bit short of being a nice
*documentation* generation system.


T

-- 
Blunt statements really don't have a point.