On 9/15/13, Vladimir Panteleev <vladimir@thecybershadow.net> wrote:
> I'm not sure this is an improvement, functionally.

It's not an improvement at all. Ctrl+F doesn't work with this (like
you mentioned), and the items list is not even sorted
alphabetically(!), so now we have to hunt down a symbol before we can
jump to it. Also, what used to be just one step (click), now becomes
more (click, scroll, click).

The categorical table at the top of http://dlang.org/phobos/std_algorithm.html is what I prefer the most, we could implemented this on other pages.

On 2013-09-15 13:32, Andrej Mitrovic wrote:

> It's not an improvement at all. Ctrl+F doesn't work with this (like
> you mentioned), and the items list is not even sorted
> alphabetically(!), so now we have to hunt down a symbol before we can
> jump to it. Also, what used to be just one step (click), now becomes
> more (click, scroll, click).
>
> The categorical table at the top of
> http://dlang.org/phobos/std_algorithm.html is what I prefer the most,
> we could implemented this on other pages.

The only improvement I can see is that it doesn't list non-module symbols. That is members in classes/structs and similar.

-- 
/Jacob Carlborg

Andrej Mitrovic:

> The categorical table at the top of
> http://dlang.org/phobos/std_algorithm.html is what I prefer the most, we could implemented this on other pages.

Speaking of JavaScript, can't that table be shown using no JavaScript at all, generating it statically?

Bye,
bearophile

On Sunday, 15 September 2013 at 07:53:23 UTC, Vladimir Panteleev wrote:
> I'm not sure this is an improvement, functionally.
>
> ...
>
> What happened with Ddox? This looks like an improvement in both function and aesthetics:
>
> http://vibed.org/temp/phobos/std/array.html

+1

The blob of links was bad, but a combo box isn't really much better.

Ddox is superior.

On Sunday, 15 September 2013 at 13:05:34 UTC, bearophile wrote:
> Speaking of JavaScript, can't that table be shown using no JavaScript at all, generating it statically?

yup.

http://arsdnet.net/d-web-site/std_datetime.html
http://arsdnet.net/d-web-site/std_stdio.html


I did this I think almost two years ago now so the program probably needs updating, but if someone wanted to integrate it into the website build process it is simple enough to run:

http://arsdnet.net/d-web-site/improveddoc.d

(yes, it would be nice if ddoc itself did this kind of thing, but still doing it ahead of time is better than doing it in js)

On 9/15/2013 12:53 AM, Vladimir Panteleev wrote:
> What happened with Ddox? This looks like an improvement in both function and
> aesthetics:
>
> http://vibed.org/temp/phobos/std/array.html

It doesn't document the parameters, return type, and doesn't recognize embedded hyperlinks.

On 15/09/13 13:32, Andrej Mitrovic wrote:
> It's not an improvement at all. Ctrl+F doesn't work with this (like
> you mentioned), and the items list is not even sorted
> alphabetically(!), so now we have to hunt down a symbol before we can
> jump to it. Also, what used to be just one step (click), now becomes
> more (click, scroll, click).

Agree, being able to use Ctrl+F is crucial.  Anything that kills that is a problem.

> The categorical table at the top of
> http://dlang.org/phobos/std_algorithm.html is what I prefer the most,
> we could implemented this on other pages.

I seem to recall that table having some issues, e.g. stuff that appeared in the table but no longer appeared elsewhere in the docs, because it had been deprecated.  Was that because it's hand-written rather than autogenerated?

In any case, it's a nice design -- the combination of the category/functions summary table at the top, and the cheat sheet further down, gives a very good overview of the module.

If that sort of category table and cheat sheet could be automatically and statically generated as part of the docs build process, it would be great.  It's definitely preferable to avoid JavaScript as much as possible, not just because some people prefer to disable it but also because if the Ddoc build process can create smart module summaries in this way, it means that everyone using Ddoc can use that for their projects.

On 9/15/13 12:53 AM, Vladimir Panteleev wrote:
> On Sunday, 15 September 2013 at 07:14:15 UTC, Andrei Alexandrescu wrote:
>> Check out the new navigation at
>> http://erdani.com/d/phobos/std_array.html. The ugly "Jump to" list as
>> the top gets replaced by a slick drop-down. Once you jump to a name,
>> you can go back by pressing the up arrow on the right or simply go to
>> top.
>
> I'm not sure this is an improvement, functionally. Finding the right
> item in much faster when you can see all items at once, and not lined up
> on only one direction.

Not sure what that's based on, but at least for me that only works up to a few words. For large modules that's hopeless. Just look at:

http://dlang.org/phobos/std_datetime.html

Can you really pick up the desired term? I think http://erdani.com/d/phobos/std_datetime.html is a real improvement over that (it also reduces the size of the list to the top-level ones, which helps).

> Also, Ctrl+F was more likely to find the link to
> the correct item before than now (and if you used your browser's inline
> search feature, then you could activate that link by pressing Enter).
>
> I think some kind of outline would be more useful.

Of course better designs are welcome. One possibility is an incremental search box.

> What happened with Ddox? This looks like an improvement in both function
> and aesthetics:
>
> http://vibed.org/temp/phobos/std/array.html

That would be a larger, future step. Walter noted some issues. Also things are a bit messed up right now - appender.html is missing, and the others don't expand D_RUN_CODE ARGS.


Andrei

On 9/15/13 12:54 AM, Walter Bright wrote:
> On 9/15/2013 12:14 AM, Andrei Alexandrescu wrote:
>> I hope I didn't mess up anything, reviews appreciated.
>
>
> Can you build the .mobi file with these changes?

Yah, and a cursory skim suggests the generated document is okay.

Andrei

On 9/15/13 1:48 AM, bearophile wrote:
> Andrei Alexandrescu:
>
>> http://erdani.com/d/phobos/std_array.html
>
> One thing I'd like is for every function a link to the GitHub page &
> line of code where that Phobos function is defined. This is handy
> because I sometimes need to take a look at the implementation of
> functions I use. And I think that encourages people to fix the
> documentation faster, etc.

That would be nice. It would require either the mythical compiler-as-library or the simpler approach of making the file and line of each symbol available as ddoc symbols.

> Another small ddoc improvement, is for each of the recently introduced
> functions a small note that tells compiler version number when it appeared.

Interesting. That would be some serious work though.


Andrei