On 9/16/13 6:20 AM, Wyatt wrote:
> On Sunday, 15 September 2013 at 18:02:10 UTC, Andrei Alexandrescu wrote:
>>
>> Sure. My goal with this upgrade is to get rid of the unsightly bag of
>> words at the top of most pages.
>>
> A few months ago, I made a prototype that turned the "bag of words" into
> a boxed out vertical list floating at the left.  It worked fairly well
> at all sorts of browser sizes and required zero Javascript.  (It will
> work even better when all the modules have introductory text as
> mentioned in another thread.</optimism>)
>
> I wonder if I should resurrect that branch?
>
> -Wyatt

Probably not. The consensus is to got the ddox way, and Walter and myself are on board with it. We're a bit concerned about switching to new tooling (dependencies, bus factor etc) but we think it's worth it.

Andrei

On Monday, 16 September 2013 at 13:32:29 UTC, Andrei Alexandrescu wrote:
> On 9/16/13 6:08 AM, Vladimir Panteleev wrote:
>> On Monday, 16 September 2013 at 12:59:28 UTC, Andrei Alexandrescu wrote:
>>> On 9/15/13 12:14 AM, Andrei Alexandrescu wrote:
>>> [snip]
>>>
>>> Got destroyed so I changed the jump-to list back, added a couple of
>>> minor improvements until we land
>>> https://github.com/D-Programming-Language/dlang.org/pull/267.
>>>
>>> http://erdani.com/d/phobos/std_array.html
>>
>> What happened to the margins/padding? The assocArray example block
>> shouldn't be glued to the uninitializedArray signature.
>
> Must have fallen through the cracks. Any chance you'd spot it in the pull request? I'll try the same when I'll find some time.

What before was <dd>, now is <div class="d_decl_dd"> (and the margin was a dd style). Why this change? You can apply any properties of one to the other through CSS.

On Monday, 16 September 2013 at 13:33:55 UTC, Andrei Alexandrescu wrote:
>
> Probably not. The consensus is to got the ddox way, and Walter and myself are on board with it. We're a bit concerned about switching to new tooling (dependencies, bus factor etc) but we think it's worth it.

Well, as long as it works (and works WELL) without Javascript, I guess that's a fine start.  Though I have to admit the example linked above hurts my eyes. :(  (So. Much. White.)

-Wyatt

On 9/16/13 7:30 AM, Wyatt wrote:
> On Monday, 16 September 2013 at 13:33:55 UTC, Andrei Alexandrescu wrote:
>>
>> Probably not. The consensus is to got the ddox way, and Walter and
>> myself are on board with it. We're a bit concerned about switching to
>> new tooling (dependencies, bus factor etc) but we think it's worth it.
>
> Well, as long as it works (and works WELL) without Javascript, I guess
> that's a fine start.  Though I have to admit the example linked above
> hurts my eyes. :(  (So. Much. White.)

Which example? Are you referring to the extra spacing I added between symbols?

Andrei

On Mon, Sep 16, 2013 at 08:58:31AM +0200, Jacob Carlborg wrote:
> 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.
[...]

The problem is that Walter wants DDOC to be a generic macro-expansion system. Adding any further smarts to it would tie it down to D-specific functionality, which reduces the likelihood of it being accepted.

But, you may be able to change his mind. :)


T

-- 
Computers are like a jungle: they have monitor lizards, rams, mice, c-moss, binary trees... and bugs.

On Mon, Sep 16, 2013 at 05:59:27AM -0700, Andrei Alexandrescu wrote:
> On 9/15/13 12:14 AM, Andrei Alexandrescu wrote:
> [snip]
> 
> Got destroyed so I changed the jump-to list back, added a couple of minor improvements until we land https://github.com/D-Programming-Language/dlang.org/pull/267.
> 
> http://erdani.com/d/phobos/std_array.html
[...]

Can we pretty-please-with-a-cherry-on-top reintroduce indentation for aggregate members? Right now, for example, RefAppender's members have no visual distinction from module-level symbols. This pretty much makes the docs unusable for me.


T

-- 
Marketing: the art of convincing people to pay for what they didn't need before which you can't deliver after.

On 9/16/13 6:40 AM, Vladimir Panteleev wrote:
> What before was <dd>, now is <div class="d_decl_dd"> (and the margin was
> a dd style). Why this change? You can apply any properties of one to the
> other through CSS.

Great, thanks. Now fixed. My intent was to use <div> and <span> for styling ddoc elements to the extent possible, in order to make styling as flexible as possible. But I forgot to give the appropriate style to d_decl_dd (hopefully not others).

Destroy: http://erdani.com/d/phobos/std_array.html


Andrei

On 9/16/13 7:43 AM, H. S. Teoh wrote:
> On Mon, Sep 16, 2013 at 05:59:27AM -0700, Andrei Alexandrescu wrote:
>> On 9/15/13 12:14 AM, Andrei Alexandrescu wrote:
>> [snip]
>>
>> Got destroyed so I changed the jump-to list back, added a couple of
>> minor improvements until we land
>> https://github.com/D-Programming-Language/dlang.org/pull/267.
>>
>> http://erdani.com/d/phobos/std_array.html
> [...]
>
> Can we pretty-please-with-a-cherry-on-top reintroduce indentation for
> aggregate members? Right now, for example, RefAppender's members have no
> visual distinction from module-level symbols. This pretty much makes the
> docs unusable for me.

Yah, apologies. It's the same bug as noted by Vladimir. Fixed now. Thanks for the feedback and keep it coming!

Andrei

On Monday, 16 September 2013 at 15:23:50 UTC, Andrei Alexandrescu wrote:
> Yah, apologies. It's the same bug as noted by Vladimir. Fixed now. Thanks for the feedback and keep it coming!

I'm opening these in two tabs and cycling between them:

http://dlang.org/phobos/std_array.html
http://erdani.com/d/phobos/std_array.html

One noticeable difference is that parameter names are no longer italicized. Is that on purpose, or a missing .param style?

Looks good otherwise!

On 9/16/13, Andrei Alexandrescu <SeeWebsiteForEmail@erdani.org> wrote:
> Thanks for the feedback and keep it coming!

The links at the top of std_array.html don't have an underline for some reason, making it hard to know they're links.

Also, the links are broken. E.g. RefAppencer points to this: http://erdani.com/d/phobos/std_array.html#RefAppender

But that doesn't lead to anywhere. The old page linked to:

http://dlang.org/phobos/std_array.html#.RefAppender (note the dot
before RefAppender).