Worst Phobos documentation evar!

[Walter Bright via Digitalmars-d]

On 12/29/2014 4:45 PM, H. S. Teoh via Digitalmars-d wrote:
>>> 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.
>>
>> More correctly, Ddoc works well for any markup that has a
>> fundamentally nested structure. LaTeX does not.
>
> That's not true; LaTeX supports nested structures quite well.

'Supports' is not the same thing as 'is' a nested structure.


>> But at least you can make it work with LaTeX. Whatcha gonna do with
>> Markdown?
> Again, I wasn't defending Markdown.

Then I'm a bit lost on what the point of complaining about Ddoc is. Are you 
arguing that Ddoc should implement LaTeX?



> The only way to get it right is to turn your ddoc comments into tag
> soup. Are you seriously suggesting that we have to write ddoc tag soup
> while coding? Or that we first write in plain text then go back
> afterwards and wrap every paragraph in $(P ...) macros? The only reason
> zero source code changes were required, was because the ddoc comments
> were already written with the requisite tag soup to begin with. Which is
> OK, if that's the "correct" way to use ddoc... but in that case, the
> page on dlang.org that describes ddoc should be revised to not give the
> false impression that you can just write documentation comments in plain
> text format and expect to get nice output from it.

I think this is an unfair critique. The blank lines separating paragraphs work fine.

Ddoc is not intended to be LaTeX. That it can't do everything a professional 
typesetting language can is not remarkable, no other markup language can, either.