Worst Phobos documentation evar!

[H. S. Teoh via Digitalmars-d]

On Mon, Dec 29, 2014 at 05:45:08PM -0800, Andrei Alexandrescu via Digitalmars-d wrote:
> 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.

Of what quality? Have you actually looked at the LaTeX output to see if
it's actually correct? I doubt it's actually 100% correct. LaTeX is
quite sensitive in some places to extra spaces, or special ways of
writing certain text elements. If these details are not taken care of,
sure it will still produce output, but there will be little niggling
problems sprinkled throughout -- lines that don't line up properly,
words that aren't spaced properly, etc..


> >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 we should stop the false advertisement that ddoc input is supposed to
be "human readable", because it is not.


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

Yes, and the system degrades into something no better than writing raw
HTML or LaTeX, when every other element in your text is "special stuff".
Do you seriously believe that the ". " in "Mr. So-and-So" is "special
stuff"? And what if another formatter requires special markup for "-"
because it has special meaning? So now, a simple string like:

	Mr. So-and-So

must be written as:

	Mr$(DOTSPACE)So$(HYPHEN)and$(HYPHEN)So

Which is OK if that's the way things are intended to work, but we should
seriously stop selling ddoc as "human readable" because at this point,
it most certainly is not.


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

Yes, and therefore we should stop selling ddoc as a human-readable input
format, since the above example is anything but.


T

-- 
Caffeine underflow. Brain dumped.