Worst Phobos documentation evar!

[Andrei Alexandrescu via Digitalmars-d]

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