Worst Phobos documentation evar!

[Walter Bright via Digitalmars-d]

On 12/30/2014 10:10 AM, H. S. Teoh via Digitalmars-d wrote:
> Using blank lines to separate paragraphs would be fine, *if* ddoc
> processes them internally and wraps paragraphs in $(P...) automatically
> instead of inserting $(BLANKLINE). However, currently it doesn't. And I
> am loathe to change this because the PR will inevitably get rejected,
> since it will break every ddoc macro set that relies on $(BLANKLINE).

Ddoc should do the $(P ) thing instead of $(BLANKLINE). The latter is a mistake 
on my part, as when I originally build Ddoc I had a lesser understanding of what 
the right output should be.

It's a correctable mistake, and (as Andrei suggests) can coexist with BLANKLINE.


> The problem with this, is that ddoc is imposed upon all D users.  It
> tries to be readable, but fails to be beyond the most trivial of cases.
> Things like embedded code blocks and section headings have special
> meaning, and have a nice human-readable input syntax, but other common
> constructs such as lists and tables require ugly macro syntax. I'd
> rather that macro syntax is either used *everywhere* (make it a
> full-fledged markup language) or nowhere (make it a fully human-readable
> language), but what we have now is a halfway job.

Lists and tables are rarely used, and I don't find them unreadable.


> And then, having included macros, which are deemed necessary, it doesn't
> go far enough either -- certain things (like autoindexing symbols in a
> module for making a table of contents, for example) aren't possible
> without lots of manual work and duplication. There are no capabilities
> for working with the text itself -- like capitalization so that you can
> use macros for extracting and placing text snippets in different places,
> inserting escape sequences for sensitive characters in the target
> format, extracting symbols to make a table of contents, etc.. This is
> apparently a deliberate design choice, which makes it feel like we're
> dangling the enticing capability to be a powerful documentation system,
> yet we withhold actual text-processing capabilities so that you either
> have to live with inferior output, or implement custom post-processing
> tools. Again, it feels like another halfway job, it's neither here nor
> there.

Propose solutions. Your one about $(P ) is a good one.