[Issue 16110] ddoc should emit paragraphs not hard-coded line-breaks

June 01, 2016

Posted by ag0aep6g@gmail.com

Permalink

ag0aep6g@gmail.com

Permalink

https://issues.dlang.org/show_bug.cgi?id=16110

ag0aep6g@gmail.com changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |ag0aep6g@gmail.com
           Hardware|x86_64                      |All
                 OS|Linux                       |All

--- Comment #1 from ag0aep6g@gmail.com ---
(In reply to greensunny12 from comment #0)
> There are many pages which are not visually appealing, like
> 
> https://dlang.org/phobos/std_format.html
> http://dlang.org/phobos/std_digest_md.html
> http://dlang.org/phobos/std_bigint.html
> http://dlang.org/phobos/std_datetime.html
> http://dlang.org/phobos/std_experimental_logger.html
> ...

For the visuals I have a pull request against dlang.org:

https://github.com/dlang/dlang.org/pull/1317

The generated HTML still isn't the nicest, though.

> For a detailed list either browse the docs or see [1].
> 
> Imho ddoc should learn from the markdown approach and translate block to paragraphs and not insert hard-coded newlines.
> 
> a
> b
> c
> 
> <p>a b c</p>

One problem with that is that Ddoc isn't aware of lists, tables, etc. It can't emit a <p> element for every paragraph it sees, because what's a paragraph to Ddoc may become a list in HTML which must not be wrapped in <p>.

Making Ddoc drastically more content aware, i.e. going full Markdown, would be a solution. It would need to be a separate documentation generator, though. A sort of Ddoc2 with a opt-in compiler switch.

Another, less principled solution could be to emit something like <div class="ddoc-paragraph"> instead of <p>. That is, Ddoc wraps every paragraph it sees in a `DDOC_PARAGRAPH` macro with a nop default definition:

    DDOC_PARAGRAPH = $0

On dlang.org, we then redefine things like so:

    DDOC_BLANKLINE =
    DDOC_PARAGRAPH = <div class="ddoc-paragraph">$0</div>

--

Forums