DLang Spec rewrite (?)

[Andrei Alexandrescu]

On 5/26/13 4:02 PM, H. S. Teoh wrote:
> On Sun, May 26, 2013 at 03:03:30AM -0400, Andrei Alexandrescu wrote:
>> ESCAPES has been recently defined to partially fix that.
>
> Is it working now?

Yes.

> 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.

I think you can configure things that way, but by default most 
characters are not active.

> 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?).

Agreed.

> 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.

Yah, paragraph breaks are special. LaTeX dedicates them a lot of 
attention (inserts \parbreak for two \n\n, collapses several consecutive 
\parbreak occurrences into one etc). Probably ddoc could do better at 
paragraphs.

> 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.

Agreed.


Andrei