On 9/15/13 7:15 PM, Adam D. Ruppe wrote:
> On Monday, 16 September 2013 at 01:52:38 UTC, Andrei Alexandrescu wrote:
>> It's not a combo box.
>
> http://msdn.microsoft.com/en-us/library/windows/desktop/bb775791%28v=vs.85%29.aspx
>
>
> check out the CBS_DROPDOWNLIST style.

Ha, it is. Thanks.

Andrei

On Sun, Sep 15, 2013 at 12:14:14AM -0700, Andrei Alexandrescu wrote:
> I finally gathered strength to rebase https://github.com/D-Programming-Language/dlang.org/pull/271 manually, which was every bit as involved as I feared.
> 
> I hope I didn't mess up anything, reviews appreciated.
> 
> That diff includes a new page navigation scheme. (Wasn't the main purpose of the diff but found it a nice perk.) I see it as a transitional stage toward the larger transition to one-page-per-entity that Sönke has proposed.
> 
> 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.
[...]

Not bad. I'd suggest replacing the default selection on the "slick" drop-down with a more helpful message, like "choose a declaration..." or something like that, instead of just a down arrow with lots of trailing blank space.

The one thing that I do NOT like, is the lack of indentation for aggregate members. For example, struct Appender's members aren't visually differentiated from other module-level symbols, which makes the documentation VERY confusing. For reference, this is the format I use for my own ddocs:

	http://eusebeia.dyndns.org/~hsteoh/tmp/doc/mda

which are generated by the minimalistic macros here:

	https://github.com/quickfur/Viola-ddoc-macros

The nesting of various identifiers are deliberately made very explicit visually (see, for example, the docs for `struct IndexRange`), so there's no confusion as to what symbol belongs in which aggregate. I think this is indispensible for the docs to be useful to newbies.


T

-- 
Error: Keyboard not attached. Press F1 to continue. -- Yoon Ha Lee, CONLANG

On Sunday, 15 September 2013 at 18:38:54 UTC, Sönke Ludwig wrote:
> Am 15.09.2013 19:20, schrieb Walter Bright:
>> 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.
>
> Just as a reminder, this is the current version:
> http://vibed.org/temp/d-programming-language.org/phobos/std/array.html

I'm sold, that is awesome !

On Sun, Sep 15, 2013 at 11:40:28AM -0700, Jonathan M Davis wrote:
> On Sunday, September 15, 2013 11:02:11 Andrei Alexandrescu wrote:
> > One obvious drawback of ^F working is that all symbols are there in sight.
> 
> I actually consider it a serious drawback when they're _not_ in sight. The problem that we have is not that all of the symbols are shown as links but how they're organized. Trying to hide them doesn't help.
[...]

+1.

What we need is not Yet Another Snake Oil Automagic Trick that will somehow magically make it all work. What we need is to sit down and put in the time to organize the module docs, grouping the symbols by logical categories (which a computer can't really figure out for us, unless we tag the code, which requires the same amount of effort anyway). I think std.algorithm and std.range's docs are a good model to follow. They set the minimum standard all Phobos docs should meet.

Of course, we can also improve on them even more, by figuring out a way to prevent the DRY violation currently in std.algorithm (to add a new symbol, you now have to add it in 3 places: at the navigation table at the top, then in the cheatsheet, then the actual code in the module body). Maybe some kind of DDoc tag or UDA that can be collected by a postprocessing script that autogenerates the relevant tables based on what information is there? For example:

	// Note: not actual syntax, I just made this up for illustration
	// purposes:

	/**
	 * @category: searching
	 * @cheatsheet: newHaystack = find(haystack, needle)
	 *
	 * Finds needle in haystack.
	 * ...
	 */
	R find(R,S)(R haystack, S needle)
	{
		...
	}

The postprocessing tool would then collect all the @category tags and @cheatsheet tags and assemble a table out of them, linked to the relevant symbols, and insert it at the top of the page. (Or, it could even split the files up into individual pages, which we've been talking about since, oh, last year?)


T

-- 
I think the conspiracy theorists are out to get us...

On Mon, Sep 16, 2013 at 06:15:35AM +0200, deadalnix wrote:
> On Sunday, 15 September 2013 at 18:38:54 UTC, Sönke Ludwig wrote:
> >Am 15.09.2013 19:20, schrieb Walter Bright:
> >>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.
> >
> >Just as a reminder, this is the current version: http://vibed.org/temp/d-programming-language.org/phobos/std/array.html
> 
> I'm sold, that is awesome !

Me too.  Why aren't we working towards that, instead of trying to cook up yet another hack on top of the current poor state of documentation?


T

-- 
The day Microsoft makes something that doesn't suck is probably the day they start making vacuum cleaners... -- Slashdotter

On Sunday, 15 September 2013 at 18:38:54 UTC, Sönke Ludwig wrote:
>
> Just as a reminder, this is the current version:
> http://vibed.org/temp/d-programming-language.org/phobos/std/array.html

This is way better
+1

Am 16.09.2013 02:54, schrieb Walter Bright:
> On 9/15/2013 11:38 AM, Sönke Ludwig wrote:
>> Am 15.09.2013 19:20, schrieb Walter Bright:
>>> 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.
>>
>> Just as a reminder, this is the current version:
>> http://vibed.org/temp/d-programming-language.org/phobos/std/array.html
>
> Much better!

I need some form of authoritative decision on how to go about making (or not making) the transition before I can start to work on the necessary changes to the make file and the rest of the site. There is a suggestion I made in the pull request:

https://github.com/D-Programming-Language/dlang.org/pull/267

On Monday, 16 September 2013 at 01:44:34 UTC, Andrei Alexandrescu wrote:
> On 9/15/13 11:25 AM, Vladimir Panteleev wrote:
>> 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.
>
> But search boxes with autocomplete are vastly better.

Search boxes with autocomplete are vastly better than the classical Ctrl+F dialog as implemented in Internet Explorer 6. Most browsers currently implement Ctrl+F as incremental search, which highlights results as you type. These have the advantage that simply typing the term will 1) scroll down and highlight the term, bringing into view the symbol's documentation on a "hit", and 2) highlight all occurrences of the term on the visible page, making e.g. overloads and related symbols immediately noticeable. You also don't need to focus a search box immediately after arriving at a page.

Anyway, no reason we can't have both. The CHM build tool generates an index of all Phobos/Druntime symbols and D keywords, and I think the dman tool does something similar as well - perhaps it could be used for a site-wide searchbox with autocomplete.

On 2013-09-16 03:54, Andrei Alexandrescu wrote:

> Aha, I now remember - you mentioned this once, really like it.
>
> http://ruby-doc.org/core-1.9.3/

I forgot the link, thanks.

-- 
/Jacob Carlborg

On 2013-09-16 06:50, H. S. Teoh wrote:

> What we need is not Yet Another Snake Oil Automagic Trick that will
> somehow magically make it all work. What we need is to sit down and put
> in the time to organize the module docs, grouping the symbols by logical
> categories (which a computer can't really figure out for us, unless we
> tag the code, which requires the same amount of effort anyway). I think
> std.algorithm and std.range's docs are a good model to follow. They set
> the minimum standard all Phobos docs should meet.
>
> Of course, we can also improve on them even more, by figuring out a way
> to prevent the DRY violation currently in std.algorithm (to add a new
> symbol, you now have to add it in 3 places: at the navigation table at
> the top, then in the cheatsheet, then the actual code in the module
> body). Maybe some kind of DDoc tag or UDA that can be collected by a
> postprocessing script that autogenerates the relevant tables based on
> what information is there? For example:
>
> 	// Note: not actual syntax, I just made this up for illustration
> 	// purposes:
>
> 	/**
> 	 * @category: searching
> 	 * @cheatsheet: newHaystack = find(haystack, needle)
> 	 *
> 	 * Finds needle in haystack.
> 	 * ...
> 	 */
> 	R find(R,S)(R haystack, S needle)
> 	{
> 		...
> 	}
>
> The postprocessing tool would then collect all the @category tags and
> @cheatsheet tags and assemble a table out of them, linked to the
> relevant symbols, and insert it at the top of the page. (Or, it could
> even split the files up into individual pages, which we've been talking
> about since, oh, last year?)

I think we should try and enhance the documentation generated automatically. Tagging and doing other things manually doesn't scale. This should only be used as a last option.

-- 
/Jacob Carlborg