Ready to make page-per-item ddocs the default?

[Andrei Alexandrescu via Digitalmars-d]

On 1/6/15 8:54 PM, Manu via Digitalmars-d wrote:
> On 7 January 2015 at 08:43, Andrei Alexandrescu via Digitalmars-d
> <digitalmars-d at puremagic.com> wrote:
>> Let's crowdsource the review. Please check the entries linked from here:
>> http://dlang.org/library/index.html.
>>
>> Andrei
>
> Very first function I looked at: http://dlang.org/library/std/string/format.html
>
> I find all the horizontal bar's throughout the docs quite noisy and
> tiring, and somewhat antiquated stylistically.

FWIW the table styling is the least problem with that page. Apparently 
the indexer messes up things quite a lot, making text red when it 
shouldn't and not rendering code correctly etc.

> I expected the parameters to jump out at me, but I didn't notice that
> that block surrounded by black lines and bold headings was actually
> the parameter list. I don't think I need headings to tell me which
> column is the name and which is the description. Ie, the parameters
> didn't jump out at me, the noise surrounding them did, and distracted
> me from the parameters themselves.

So Name/Description should go?

Also parameters should be in code font.

> There's obviously a bug here where the text is red too.

Yah that's a biggie. Notice the code snippets that were supposed to be 
syntax colored too...

Looks like that's a problem in the source. This looks just as bad: 
http://dlang.org/phobos/std_string.html#.format

> My suggestions to make that page look more professional:
>
> * Prototype needs proper syntax highlighting, and elements (builtin
> types, types, template args, runtime args, and the function name
> itself) need to be styled distinctly (and tastefully).
> * The noise around the parameter listing can be removed completely.
> * The parameter name string in the parameter listing should match the
> styling of the prototype, so you can immediately recognise the thing
> in the prototype's description on the page.
> * The coloured box that houses the prototype is 6 times wider than it
> needs to be (on my monitor). I think it should be horizontally sized
> to fit the content.
> * Authors, license, and other uninteresting information should be
> spaced from the content (give an extra line-break or 2), and also the
> text should be significantly smaller. This is, literally, the
> fine-print.

Noice.

> Comment box at the bottom is awesome!
>
> Taking another random sample: http://dlang.org/library/std/csv.html
>
> My previous criticisms stand equally.
> I feel like 'see also' should be the last thing before the 'fine
> print', not the first thing.
>
> Clicking through to see a class:
> http://dlang.org/library/std/csv/csv_exception.html
>
> Prior criticisms apply, but looks okay otherwise.
> There is 'fields' and 'methods', but they look the same. This is
> unexpected, since methods are functions, with return types, and
> arguments... why can't I see those?
>
> I'll leave it there for a moment.
>
>
> How do we style this stuff? Is there some way that we can experiment
> with styling ourselves?

Mainly css, see 
https://github.com/D-Programming-Language/dlang.org/tree/master/css. 
Some styling in the html.ddoc and other .ddoc files, see 
https://github.com/D-Programming-Language/dlang.org/tree/master/.


Andrei