On 7 January 2015 at 08:43, Andrei Alexandrescu via Digitalmars-d <digitalmars-d@puremagic.com> wrote:
> Let's crowdsource the review. Please check the entries linked from here: http://dlang.org/library/index.html.
>
> Andrei

Another thought, since per-page docs result in a lot more page loads,
this page *really* needs to be populated by ajax requests. It's
wasteful to reload the whole page on every click.
I'm in Australia, we don't really have internet in this country anymore!

Is there a server that serves the raw data for the docs? It would be ideal for the client to format the page. We don't need to be sending HTML around.

On 7/01/2015 7:20 p.m., Manu via Digitalmars-d wrote:
> On 7 January 2015 at 08:43, Andrei Alexandrescu via Digitalmars-d
> <digitalmars-d@puremagic.com> wrote:
>> Let's crowdsource the review. Please check the entries linked from here:
>> http://dlang.org/library/index.html.
>>
>> Andrei
>
> Another thought, since per-page docs result in a lot more page loads,
> this page *really* needs to be populated by ajax requests. It's
> wasteful to reload the whole page on every click.
> I'm in Australia, we don't really have internet in this country anymore!
>
> Is there a server that serves the raw data for the docs? It would be
> ideal for the client to format the page. We don't need to be sending
> HTML around.

I was thinking a little similarly.
But using DDOC to generate JSON.
Serve that from web server.

Something like https://github.com/rikkimax/client-templating could be used to fill out based upon the data via widgets.

Of course then it won't be prefilled when served but meh.
Think Facebook's Big Pipe only more open.

On Wed, Jan 07, 2015 at 07:44:39AM +0200, ketmar via Digitalmars-d wrote:
> On Tue, 06 Jan 2015 14:43:45 -0800
> Andrei Alexandrescu via Digitalmars-d <digitalmars-d@puremagic.com>
> wrote:
> 
> > Let's crowdsource the review. Please check the entries linked from here: http://dlang.org/library/index.html.
> so looking at the function documentation i lost that nice indexes. if i got to the function directly (which will be very likely with googling), now i have to either drop keyboard and use mouse to click on module name (which is not immideately pops like a link, btw), possibly scrolling the page to top, or try to use keyboard navigation, which has only one thing in common for various browsers: it's awful.
[...]

You should use Vimperator. :-P  I started using it recently, didn't like it that much at first, but I'm starting to like it more and more. Thanks to the hinting system, my rodent is even more out-of-use nowadays, which I consider a Good Thing(tm).


T

-- 
LINUX = Lousy Interface for Nefarious Unix Xenophobes.

On 1/6/15 7:27 PM, Paul O'Neil wrote:
> On 01/06/2015 05:43 PM, Andrei Alexandrescu wrote:
>> Let's crowdsource the review. Please check the entries linked from here:
>> http://dlang.org/library/index.html.
>>
>> Andrei
>
> On that page itself, the descriptions for at least std.regex and std.uni
> include the headers (e.g Intro, Overview) from those pages.

Fixed in http://dlang.org/library-prerelease/index.html. -- Andrei

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@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

On 1/6/15 10:09 PM, Manu via Digitalmars-d wrote:
> On 7 January 2015 at 08:43, Andrei Alexandrescu via Digitalmars-d
> <digitalmars-d@puremagic.com> wrote:
>> Let's crowdsource the review. Please check the entries linked from here:
>> http://dlang.org/library/index.html.
>>
>> Andrei
>
> Another one; I tried to use the search box on the top right corner...
> it just resulted in a google search.
> Can we do better than that? When people go to the documentation page,
> they want to search the docs, not get a standard google results page.

That would be quite an involved project. -- Andrei

On Wednesday, 7 January 2015 at 06:48:23 UTC, Andrei Alexandrescu
wrote:
> On 1/6/15 10:09 PM, Manu via Digitalmars-d wrote:
>> On 7 January 2015 at 08:43, Andrei Alexandrescu via Digitalmars-d
>> <digitalmars-d@puremagic.com> wrote:
>>> Let's crowdsource the review. Please check the entries linked from here:
>>> http://dlang.org/library/index.html.
>>>
>>> Andrei
>>
>> Another one; I tried to use the search box on the top right corner...
>> it just resulted in a google search.
>> Can we do better than that? When people go to the documentation page,
>> they want to search the docs, not get a standard google results page.
>
> That would be quite an involved project. -- Andrei

I don't think so, since vibed.org has exactly that.
I'm not familiar with JS, but I believe
https://github.com/rejectedsoftware/vibed.org/blob/master/public/scripts/ddox.js
could be a good starter place.

On 1/6/15 11:02 PM, Mathias LANG wrote:
> On Wednesday, 7 January 2015 at 06:48:23 UTC, Andrei Alexandrescu
> wrote:
>> On 1/6/15 10:09 PM, Manu via Digitalmars-d wrote:
>>> On 7 January 2015 at 08:43, Andrei Alexandrescu via Digitalmars-d
>>> <digitalmars-d@puremagic.com> wrote:
>>>> Let's crowdsource the review. Please check the entries linked from
>>>> here:
>>>> http://dlang.org/library/index.html.
>>>>
>>>> Andrei
>>>
>>> Another one; I tried to use the search box on the top right corner...
>>> it just resulted in a google search.
>>> Can we do better than that? When people go to the documentation page,
>>> they want to search the docs, not get a standard google results page.
>>
>> That would be quite an involved project. -- Andrei
>
> I don't think so, since vibed.org has exactly that.
> I'm not familiar with JS, but I believe
> https://github.com/rejectedsoftware/vibed.org/blob/master/public/scripts/ddox.js
>
> could be a good starter place.

Oh, nice. I would, however, hope we fix the many more pressing issues with dub right now. For starters, I have no idea how to fix http://dlang.org/library-prerelease/std/string/format.html in spite of having operated this: https://github.com/D-Programming-Language/phobos/commit/e03e647cea5a2cff0ff72195e8c7907127b3b5e6.

How does documentation in std.format make it in std.string's documentation?


Andrei

On 1/6/2015 10:48 PM, Andrei Alexandrescu wrote:
>> Another one; I tried to use the search box on the top right corner...
>> it just resulted in a google search.
>> Can we do better than that? When people go to the documentation page,
>> they want to search the docs, not get a standard google results page.
> That would be quite an involved project. -- Andrei

I find dman.exe to be very handy and use it all the time, but since it is a hand-built index, it is always hopelessly out of date.

On Wednesday, 7 January 2015 at 07:06:42 UTC, Andrei Alexandrescu wrote:
> On 1/6/15 11:02 PM, Mathias LANG wrote:
>> On Wednesday, 7 January 2015 at 06:48:23 UTC, Andrei Alexandrescu
>> wrote:
>>> On 1/6/15 10:09 PM, Manu via Digitalmars-d wrote:
>>>> On 7 January 2015 at 08:43, Andrei Alexandrescu via Digitalmars-d
>>>> <digitalmars-d@puremagic.com> wrote:
>>>>> Let's crowdsource the review. Please check the entries linked from
>>>>> here:
>>>>> http://dlang.org/library/index.html.
>>>>>
>>>>> Andrei
>>>>
>>>> Another one; I tried to use the search box on the top right corner...
>>>> it just resulted in a google search.
>>>> Can we do better than that? When people go to the documentation page,
>>>> they want to search the docs, not get a standard google results page.
>>>
>>> That would be quite an involved project. -- Andrei
>>
>> I don't think so, since vibed.org has exactly that.
>> I'm not familiar with JS, but I believe
>> https://github.com/rejectedsoftware/vibed.org/blob/master/public/scripts/ddox.js
>>
>> could be a good starter place.
>
> Oh, nice. I would, however, hope we fix the many more pressing issues with dub right now. For starters, I have no idea how to fix http://dlang.org/library-prerelease/std/string/format.html in spite of having operated this: https://github.com/D-Programming-Language/phobos/commit/e03e647cea5a2cff0ff72195e8c7907127b3b5e6.
>
> How does documentation in std.format make it in std.string's documentation?
>
>
> Andrei

That's funny. Looks like symbol publicly imported are generated (but not indexed). For example, icmp is there as well.