Worst Phobos documentation evar!

[H. S. Teoh via Digitalmars-d]

On Mon, Dec 29, 2014 at 04:10:35PM -0800, Walter Bright via Digitalmars-d wrote:
> On 12/29/2014 3:47 PM, H. S. Teoh via Digitalmars-d wrote:
> >We've already had to resort to $(COMMA) hacks to work around comma
> >issues in Phobos docs. :-(
> 
> It's not a hack. The macro system is designed to work that way. All
> markup systems require some sort of escape mechanism. Including
> Markup.

I wasn't defending Markdown, btw. As you pointed out elsewhere, it does
have its own set of limitations... but OTOH, it was never *designed* to
be all-encompassing. It was just an attempt to reduce the tedium of HTML
tag soup by using shorter, more visually-appealing syntax to represent
some of the most common constructs. I'm not a big fan of Markdown,
though. It's better than raw HTML, but only just so.


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


> But at least you can make it work with LaTeX. Whatcha gonna do with
> Markdown?

Again, I wasn't defending Markdown.


> Ddoc has worked extremely well for being adaptible for different HTML
> output

Yes, it works well with HTML, but not so well for other output formats.


> - like the online docs have undergone numerous facelifts while
> requiring zero changes to the Ddoc source code. It also has been able
> to generate ebooks from the documentation, again with zero source code
> changes, just a new set of macro definitions.
> 
> CandyDoc has been done with it, also with zero source changes.

This is not really accurate... if all you care for is plain text
copy-n-pasted from source code comments, with a smattering of tags added
on top to eliminate the most egregious eyesores, then sure, you can just
write straight text in the ddoc comments and it will Just Work(tm).

But as soon as you try to do anything more with it -- output
correctly-formed XHTML, for example, ddoc doesn't work.  Try making it
output paragraphs correctly encapsulated in <p>...</p> blocks sometime.
It doesn't work, because ddoc doesn't understand what paragraphs are, it
only knows what blank lines are, but blank lines are not a reliable
indicator of paragraph breaks (e.g., what about the break between a
section heading and a paragraph? Or between a quoted code block and a
paragraph before/after the code?).

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.


T

-- 
Живёшь только однажды.