On Sunday, 15 September 2013 at 17:47:06 UTC, Andrei Alexandrescu wrote:
> 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).

I believe that example is invalid. std.datetime is too big, as abundantly discussed previously. The module's documentation web page is over 130000 pixels long (for me)!

For the example you presented (std.array), my opinion is as aforementioned.

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

I believe this is an old proof-of-concept. Wasn't there a more recent and polished version in a pull request?

On Sunday, 15 September 2013 at 17:20:16 UTC, Walter Bright wrote:
> 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.

It actually does. It simply shows stripped definition of the symbol which includes all of those.

On 9/15/13 4:32 AM, Andrej Mitrovic wrote:
> 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)

Again, that would be nicer done with an inline search box. We don't have to support the exact navigation mode in the new API. One obvious drawback of ^F working is that all symbols are there in sight.

Vladimir, do you think you could easily implement such an incremental search box (with autocompletion)?

>, 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).

Sorting can be done, I thought natural order would impart some logic to the list.

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

Sure. My goal with this upgrade is to get rid of the unsightly bag of words at the top of most pages.


Andrei

On 9/15/13 6:05 AM, bearophile wrote:
> 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?

I don't think we use javascript there.

Andrei

On 9/15/2013 10:52 AM, Andrei Alexandrescu wrote:
> the simpler approach of making the file and line of each symbol available as
> ddoc symbols.


I think that would make for a nice enhancement to ddoc. Enhancement request to bugzilla?

On 9/15/2013 10:49 AM, Andrei Alexandrescu wrote:
> 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.

Great!

On 15/09/13 19:47, Andrei Alexandrescu wrote:
> 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?

It's very unwieldy as is, but what if it was split up into a categorized table and cheat-sheet à la std.algorithm?

On 9/15/13 11:22 AM, Joseph Rushton Wakeling wrote:
> On 15/09/13 19:47, Andrei Alexandrescu wrote:
>> 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?
>
> It's very unwieldy as is, but what if it was split up into a categorized
> table and cheat-sheet à la std.algorithm?

That would help either scheme. Again, my focus right now is to get rid of the bag of words without creating much aggravation.

Andrei

On Sunday, 15 September 2013 at 18:02:10 UTC, Andrei Alexandrescu wrote:
> Vladimir, do you think you could easily implement such an incremental search box (with autocompletion)?

Sorry, that idea does not appeal to me either. Web browsers already have the function of searching within a page. An in-page search box is not a common UI element, users would need to learn to use it, and that's bad UX - we should stick to existing UI conventions to avoid forcing the users to think to get to their dox.

I think an index like the one std.algorithm has, and that ddox attempts to generate automatically, is really the best solution from all sides. It provides a birds-eye view of the whole module useful to new users; it allows quickly finding the sought function through its table layout and categorization; and, the first Ctrl+F hit for a symbol name will likely be a link to the symbol, with a short synopsis nearby it. It's pretty hard to beat.

I think this is the direction we need, and that it's not worth considerably changing things with interim solutions (which will impact D users who consult the documentation often) that are more of a trade-off rather than an improvement.

Implementation-wise:

I assume Ddox has failed to be integrated because it was a server-side process. It also places each symbol in its own file, which will break existing links. Perhaps it be feasible to reimplement only its basic index-table functionality in JavaScript, to replace the word-blob/dropdown?

Symbol documentation could contain macros which render to invisible HTML, which is picked up by the index-table JS for metadata like categorization.

On Sunday, 15 September 2013 at 18:25:03 UTC, Vladimir Panteleev wrote:
> Implementation-wise:
>
> I assume Ddox has failed to be integrated because it was a server-side process. It also places each symbol in its own file, which will break existing links. Perhaps it be feasible to reimplement only its basic index-table functionality in JavaScript, to replace the word-blob/dropdown?

Admitting that server-side process has failed and moving to JS is akin to accepting failure to do proper documentation at all. Static documentation which requires JS to be conveniently usable is disaster.