View mode: basic / threaded / horizontal-split · Log in · Help
December 22, 2012
Re: dlang.org Library Reference
I don't know if this has been mentioned yet, but some modules 
have a link to the source while others do not. I suppose that's a 
problem with the documentation itself not including a link. I'm 
just mentioning this in case it has something to do with the 
formatting.

--rt
December 23, 2012
Re: dlang.org Library Reference
Am 23.12.2012 00:11, schrieb Rob T:
> I don't know if this has been mentioned yet, but some modules have a link to the source while others
> do not. I suppose that's a problem with the documentation itself not including a link. I'm just
> mentioning this in case it has something to do with the formatting.
> 
> --rt

What I did now was to hide the manually written "Source:" section (which is not in every module) and
instead generate a procedural "View source code" button on the top right of the page (which should
always be there).

So if you have any example where there still is a source section or no button, that would indeed be
a bug. But I'd hope that it was just an old cached version of the page.
December 23, 2012
Re: dlang.org Library Reference
On Sunday, 23 December 2012 at 07:38:04 UTC, Sönke Ludwig wrote:
> What I did now was to hide the manually written "Source:" 
> section (which is not in every module) and
> instead generate a procedural "View source code" button on the 
> top right of the page (which should
> always be there).
>
> So if you have any example where there still is a source 
> section or no button, that would indeed be
> a bug. But I'd hope that it was just an old cached version of 
> the page.

OK, I see it now. I was looking for the same old link as before. 
For whatever reason I just don't immediately notice the buttons 
way over to the upper right, and they appear grayed out which 
usually means they are disabled or inactive. Can you make it more 
noticeable somehow? A different color would help.

Note that I'm talking about the finer details here, the format is 
already a  really nice improvement, so big thanks for the effort!

--rt
December 23, 2012
Re: dlang.org Library Reference
Am 23.12.2012 10:11, schrieb Rob T:
> On Sunday, 23 December 2012 at 07:38:04 UTC, Sönke Ludwig wrote:
>> What I did now was to hide the manually written "Source:" section (which is not in every module) and
>> instead generate a procedural "View source code" button on the top right of the page (which should
>> always be there).
>>
>> So if you have any example where there still is a source section or no button, that would indeed be
>> a bug. But I'd hope that it was just an old cached version of the page.
> 
> OK, I see it now. I was looking for the same old link as before. For whatever reason I just don't
> immediately notice the buttons way over to the upper right, and they appear grayed out which usually
> means they are disabled or inactive. Can you make it more noticeable somehow? A different color
> would help.
> 
> Note that I'm talking about the finer details here, the format is already a  really nice
> improvement, so big thanks for the effort!
> 
> --rt

The border and the text are emphasized a bit more now + Opera now also renders a gradient.

I also disabled caching to avoid the necessity for endless page reloading.
December 23, 2012
Re: dlang.org Library Reference
Very nice-looking docs Sönke!

A minor nitpick: in some modules, the _-prefixed version appears as such (I
mean, with an underscore before the name). See for example:


http://vibed.org/temp/d-programming-language.org/phobos/std/parallelism.html

Where std.parallelism appears as `std._parallelism` in the intro text.
December 23, 2012
Re: dlang.org Library Reference
On 12/22/2012 9:36 AM, Andrei Alexandrescu wrote:
> Good idea. I'm a big fan of moving uninteresting stuff off the top of a page.
> Maybe the source does carry some interest though.
>
> More creative ideas is to represent all that information not in normal paragraph
> style, but as small print in a band (horizontal or even vertical) etc.

I agree with moving those sections to the bottom or some other innocuous place. 
Note that this is already done with the copyright section.
December 23, 2012
Re: dlang.org Library Reference
Am 23.12.2012 10:55, schrieb Philippe Sigaud:
> Very nice-looking docs Sönke!
> 
> A minor nitpick: in some modules, the _-prefixed version appears as such (I mean, with an underscore
> before the name). See for example:
> 
>  http://vibed.org/temp/d-programming-language.org/phobos/std/parallelism.html
> 
> Where std.parallelism appears as `std._parallelism` in the intro text.
> 
> 

Fixed.
December 23, 2012
Re: dlang.org Library Reference
On Saturday, 22 December 2012 at 23:04:47 UTC, Andrei 
Alexandrescu wrote:
> On 12/22/12 5:10 PM, foobar wrote:
>> On Friday, 21 December 2012 at 21:58:34 UTC, Jacob Carlborg 
>> wrote:
>>> On 2012-12-21 18:05, Andrei Alexandrescu wrote:
>>>
>>>> s/remove/integrate/
>>>> s/ugly/awesome/
>>>
>>> It's ugly that they are manually created. Over 300 lines of 
>>> comments
>>> that the doc generator should be doing automatically. I would 
>>> say that
>>> is far from awesome.
>>
>> I would add to that that duplicating both the FS and the D 
>> module system
>> by yet another method of grouping symbols is a *horrible* 
>> notion reeks
>> of poor design.
>
> What is FS? File system?
>
> Andrei

Yes, FS is the file system. sorry if it wasn't clear.

Any categorization IMO must be made *within* the language and not 
in comments/documentation just as other attributes such as purity 
and constancy are also better served being *within* the language. 
D has plenty of means to accomplish this: code can be organized 
into packages and modules and within a module, free functions can 
be organized within stateless structs for additional namespace 
categorization.

Using an all encompassing "algorithms" module is also unhelpful 
as all code is essentially an algorithm to accomplish some task. 
This is akin to opening a store called - "A store" or perhaps "A 
place to sell you stuff".
As a client of said shop, I want a better description if I to buy 
at the shop. Even a general "Clothes shop" is already much 
better. For 3rd party it also often makes sense to have a brand 
name - e.g we all know what "vibe.d" is all about.
December 23, 2012
Re: dlang.org Library Reference
On 12/23/12 6:44 AM, foobar wrote:
> Using an all encompassing "algorithms" module is also unhelpful as all
> code is essentially an algorithm to accomplish some task. This is akin
> to opening a store called - "A store" or perhaps "A place to sell you
> stuff".

That I disagree with a bit. I think it's rather clear that std.algorithm 
includes classic, consecrated algorithms the kind you'll find in a book 
entitled "Algorithms". By your argument a book called "Algorithms" would 
not make sense because it would need to describe the entire computing world.

So if I'm looking for sort, I'd open "algorithm". If I'm looking for 
parsing program options, I wouldn't expect it to be in the same place.

> As a client of said shop, I want a better description if I to buy at the
> shop. Even a general "Clothes shop" is already much better. For 3rd
> party it also often makes sense to have a brand name - e.g we all know
> what "vibe.d" is all about.

Such differentiation is also useful.


Andrei
December 23, 2012
Re: dlang.org Library Reference
On 2012-12-22 18:53, Sönke Ludwig wrote:

>   - jumps to line numbers on github (which are off because of changes after the release)

Can you lock it to the same hash that the docs are generated from?

-- 
/Jacob Carlborg
3 4 5 6 7 8 9
Top | Discussion index | About this forum | D home