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
