On 12/29/14 3:47 PM, H. S. Teoh via Digitalmars-d wrote:
On Mon, Dec 29, 2014 at 11:12:54PM +0000, Adam D. Ruppe via Digitalmars-d wrote:
On Monday, 29 December 2014 at 23:11:09 UTC, Walter Bright wrote:
$(TROW all , `all!"a > 0"([1, 2, 3, 4])` returns `true` )
Would that still work if the first column was something like (0,0) -
including a comma?
I've advocated nicer macros before, ddoc's recursive expansion makes
for a lot of nice options, but the comma being a separator kinda
worries me.
We've already had to resort to $(COMMA) hacks to work around comma
issues in Phobos docs. :-(
That's to be expected from any macro system.
Not to mention that as it stands, ddoc is only really convenient for
HTML output; while it's certainly *possible* to target it for non-HTML
output, it's a pain. Take LaTeX, for example.
I have successfully generated LaTeX from dlang.org and phobos.
You have things like
"Mr.\ So-and-so" (i.e., backslash followed by a single space) for
inserting space of the appropriate width after a period (.) that doesn't
end a sentence, where a normal "." would introduce end-of-sentence
spacing. The only way to fully support this in ddoc is to use $(DOT) or
some such hack instead of writing a literal ".". Or take the various
dashes: "--" for ndash, "---" for mdash in LaTeX, but "–" or
"—" for HTML, respectively. Again, the only way to correctly
support this in ddoc is to define $(MDASH) and $(NDASH) macros.
And what's the problem? This is exactly right, and fine. A macro system
supports any formatter, present or future. One that's based on tricks
needs to add a new trick for each formatter idiosyncrasy.
So
instead of writing dashes in your ddocs, you now have to write the much
more verbose and far uglier $(MDASH) and $(NDASH). But it gets worse.
No it does not get worse. That's pretty much it.
Certain character sequences in LaTeX need to be escaped; for example "$"
needs to be written as "\$", whereas it can appear literally in HTML.
Again, the only solution is $(DOLLAR).
Yah, as I said that's pretty much it. You need to encapsulate special
stuff in macros, which is all uniform and simple.
Ditto for opening/closing
quotation marks, which are `` and '' in LaTeX, and “ and ”
in HTML. And non-breaking space, which is ~ in LaTeX, and in
HTML. So now, what was originally an easily-readable documentation
comment:
Returns: A range of dollar amounts -- if the input is $100 or
more, as stated in Dr. Watson's "A One" specs; otherwise an
empty range.
becomes this monstrosity:
Returns: A range of dollar amounts$(MDASH)if the input is
$(DOLLAR)100 or more$(COMMA) as stated in Dr$(DOTSPACE)Watson's
$(RDQUO)A$(NBSP)One$(LDQUO) specs; otherwise an empty range.
That's an extreme example. BTW it doesn't look much worse than TDPL's
source.
Andrei
