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.
