Bug 9731 – Ddoc should output per-paragraph macro instead of $(DDOC_BLANKLINE)

Currently, ddoc does not have a direct way of identifying paragraphs in ddoc comments. The only thing support right now is $(DDOC_BLANKLINE), which defaults to <br><br>. This (more-or-less) works for HTML output, but it doesn't work so well for more semantically-driven output formats that want to know paragraph boundaries explicitly. There is a way to hack this to work in HTML by defining DDOC_BLANKLINE=</p><p> and DDOC_SECTION=<p>$0</p>, but this doesn't work if you define DDOC_SECTION_H=<h4>$0</h4>, because then the h4 is nested inside the p, which is non-compliant. Basically, there is no way to correctly support correct element nesting in HTML (or other strictly-nested formats like DocBook) without post-processing (e.g., set DDOC_BLANKLINE to some marker string that gets substituted by an external tool with suitable open/close tags depending on the surrounding context). It would be nice if ddoc could output macros based on paragraph boundaries rather than linebreaks, say $(DDOC_PARAGRAPH) or something similar, so that translation into other formats than HTML 4.x is easier.

Andrei proposed on the forum a backward-compatible fix, wherein $(DDOC_BLANKLINE) continues to be emitted, but paragraphs are also wrapped in a paragraph macro.

Commit pushed to master at https://github.com/D-Programming-Language/dmd https://github.com/D-Programming-Language/dmd/commit/0f97ab5a73241782cc7e621ddca22b6b35909d6b Merge pull request #4338 from quickfur/ddoc_para Issue 9731: implement $(DDOC_PARAGRAPH)

Commit pushed to revert-4338-ddoc_para at https://github.com/D-Programming-Language/dmd https://github.com/D-Programming-Language/dmd/commit/a7a7095bbbc30021852295eb7ffd1077cc5587c4 Revert "Issue 9731: implement $(DDOC_PARAGRAPH)"

Commits pushed to master at https://github.com/D-Programming-Language/dmd https://github.com/D-Programming-Language/dmd/commit/a7a7095bbbc30021852295eb7ffd1077cc5587c4 Revert "Issue 9731: implement $(DDOC_PARAGRAPH)" https://github.com/D-Programming-Language/dmd/commit/3208762f9720ec97b986033be00b11f075763c9f Merge pull request #4342 from D-Programming-Language/revert-4338-ddoc_para Revert "Issue 9731: implement $(DDOC_PARAGRAPH)"

Related: https://issues.dlang.org/show_bug.cgi?id=17594 https://github.com/dlang/dmd/pull/5344 and https://github.com/dlang/dlang.org/pull/1795 fix this issue, albeit somewhat differently than requested.

Commit pushed to master at https://github.com/dlang/dmd https://github.com/dlang/dmd/commit/f197169c5a573a3dcef72fac503a35b724775082 Fix Issue 9731 - Ddoc should output per-paragraph macro instead of $(DDOC_BLANKLINE)

Commit pushed to newCTFE at https://github.com/dlang/dmd https://github.com/dlang/dmd/commit/f197169c5a573a3dcef72fac503a35b724775082 Fix Issue 9731 - Ddoc should output per-paragraph macro instead of $(DDOC_BLANKLINE)

Commit pushed to stable at https://github.com/dlang/dmd https://github.com/dlang/dmd/commit/f197169c5a573a3dcef72fac503a35b724775082 Fix Issue 9731 - Ddoc should output per-paragraph macro instead of $(DDOC_BLANKLINE)