www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - dlang.org Library Reference

reply Ellery Newcomer <ellery-newcomer utulsa.edu> writes:
Is anyone else noticing e.g. std.datetime taking upwards of 30 seconds 
to render the blob of links at the top? It's freakin freezing my entire 
browser.
Dec 09 2012
next sibling parent reply 1100110 <0b1100110 gmail.com> writes:
On 12/09/2012 08:10 PM, Ellery Newcomer wrote:

 Is anyone else noticing e.g. std.datetime taking upwards of 30 seconds
 to render the blob of links at the top? It's freakin freezing my entire
 browser.


Yeah, I see it.

Not browser stalling though, just annoying.

It renders without the links, freezes the page, turns white, adds the 
links and becomes visible.

The whole process only takes 5-7 seconds here.
Dec 09 2012
parent reply "Peter Alexander" <peter.alexander.au gmail.com> writes:
On Monday, 10 December 2012 at 03:18:30 UTC, 1100110 wrote:

 On 12/09/2012 08:10 PM, Ellery Newcomer wrote:

 The whole process only takes 5-7 seconds here.


"Only" is not the right word to use here.
Dec 10 2012
parent reply Nick Sabalausky <SeeWebsiteToContactMe semitwist.com> writes:
On Mon, 10 Dec 2012 11:54:52 +0100
"Peter Alexander" <peter.alexander.au gmail.com> wrote:


 On Monday, 10 December 2012 at 03:18:30 UTC, 1100110 wrote:

 On 12/09/2012 08:10 PM, Ellery Newcomer wrote:

 The whole process only takes 5-7 seconds here.


 
 "Only" is not the right word to use here.


Yea, there's nothing about that page that has any reason whatsoever
to take 5-7 seconds on even 10-year-old hardware, let alone on anything
more common. I had a 500*MHz* in the late 90's that could render a
nice-looking HTML page the same size faster than that. There's no
justification here.
Dec 10 2012
parent reply 1100110 <0b1100110 gmail.com> writes:
On 12/10/2012 04:20 PM, Nick Sabalausky wrote:

 On Mon, 10 Dec 2012 11:54:52 +0100
 "Peter Alexander"<peter.alexander.au gmail.com>  wrote:


 On Monday, 10 December 2012 at 03:18:30 UTC, 1100110 wrote:

 On 12/09/2012 08:10 PM, Ellery Newcomer wrote:

 The whole process only takes 5-7 seconds here.


 "Only" is not the right word to use here.


 Yea, there's nothing about that page that has any reason whatsoever
 to take 5-7 seconds on even 10-year-old hardware, let alone on anything
 more common. I had a 500*MHz* in the late 90's that could render a
 nice-looking HTML page the same size faster than that. There's no
 justification here.


I've had dail-up, I've had satelite internet.
"Only" is indeed the appropriate word to use.
Dec 10 2012
parent Walter Bright <newshound2 digitalmars.com> writes:
On 12/10/2012 2:31 PM, 1100110 wrote:

 I've had dail-up, I've had satelite internet.
 "Only" is indeed the appropriate word to use.


I've had floppy disks :-)

It's still hard to get used to the superfast disks we have these days.
Dec 21 2012
prev sibling next sibling parent Jonathan M Davis <jmdavisProg gmx.com> writes:
On Sunday, December 09, 2012 18:10:42 Ellery Newcomer wrote:

 Is anyone else noticing e.g. std.datetime taking upwards of 30 seconds
 to render the blob of links at the top? It's freakin freezing my entire
 browser.


The link situation definitely needs to be fixed. People keep making noise
abouet 
it, but nothing has yet actually made it into dmd or d-programming-
language.org to fix it. Also, std.datetime should be split up into sub-modules, 
but I don't want to do that until some form of DIPs 15 or 16 is implemented. 
That way, no code will break or be be forced to change as a result.

http://www.prowiki.org/wiki4d/wiki.cgi?LanguageDevel/DIPs/DIP15
http://www.prowiki.org/wiki4d/wiki.cgi?LanguageDevel/DIPs/DIP16

But until the link situation is fixed or std.datetime is split up, I'm not 
aware of anything that can really be done to fix the problem.

- Jonathan M Davis
Dec 09 2012
prev sibling next sibling parent Denis Shelomovskij <verylonglogin.reg gmail.com> writes:
10.12.2012 6:10, Ellery Newcomer пишет:

 Is anyone else noticing e.g. std.datetime taking upwards of 30 seconds
 to render the blob of links at the top? It's freakin freezing my entire
 browser.


Personally I disable JavaScript for dlang.org a long time ago and happy 
now. At least because the hyphenation is just terrible.

Also consider bootDoc generated Phobos documentation:
http://jakobovrum.github.com/bootdoc-phobos/

-- 
Денис В. Шеломовский
Denis V. Shelomovskij
Dec 10 2012
prev sibling next sibling parent reply "Mr. Anonymous" <mailnew4ster gmail.com> writes:
On Monday, 10 December 2012 at 02:10:43 UTC, Ellery Newcomer 
wrote:

 Is anyone else noticing e.g. std.datetime taking upwards of 30 
 seconds to render the blob of links at the top? It's freakin 
 freezing my entire browser.


ddox* on dlang.org, anyone?
http://vibed.org/temp/phobos/index.html

* https://github.com/rejectedsoftware/ddox
Dec 10 2012
parent reply 1100110 <0b1100110 gmail.com> writes:
On 12/10/2012 05:16 AM, Mr. Anonymous wrote:

 On Monday, 10 December 2012 at 02:10:43 UTC, Ellery Newcomer wrote:

 Is anyone else noticing e.g. std.datetime taking upwards of 30 seconds
 to render the blob of links at the top? It's freakin freezing my
 entire browser.


 ddox* on dlang.org, anyone?
 http://vibed.org/temp/phobos/index.html

 * https://github.com/rejectedsoftware/ddox


Man, how did I miss that?  I like that.
Dec 10 2012
parent reply "Rob T" <rob ucora.com> writes:
On Monday, 10 December 2012 at 22:33:49 UTC, 1100110 wrote:

 On 12/10/2012 05:16 AM, Mr. Anonymous wrote:

 On Monday, 10 December 2012 at 02:10:43 UTC, Ellery Newcomer 
 wrote:

 Is anyone else noticing e.g. std.datetime taking upwards of 
 30 seconds
 to render the blob of links at the top? It's freakin freezing 
 my
 entire browser.


 ddox* on dlang.org, anyone?
 http://vibed.org/temp/phobos/index.html

 * https://github.com/rejectedsoftware/ddox


 Man, how did I miss that?  I like that.


http://vibed.org/temp/phobos/std/datetime.html

Wow, that's a HUGE improvement to what has been a very difficult 
read for std.datetime.

I'd like to bookmark the Vibe Phobos reference page for use as my 
library reference. Will it remain there at least until the 
official web page reference is improved in a similar or identical 
way?

--rt
Dec 11 2012
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/11/12 3:54 PM, Rob T wrote:

 On Monday, 10 December 2012 at 22:33:49 UTC, 1100110 wrote:

 On 12/10/2012 05:16 AM, Mr. Anonymous wrote:

 On Monday, 10 December 2012 at 02:10:43 UTC, Ellery Newcomer wrote:

 Is anyone else noticing e.g. std.datetime taking upwards of 30 seconds
 to render the blob of links at the top? It's freakin freezing my
 entire browser.


 ddox* on dlang.org, anyone?
 http://vibed.org/temp/phobos/index.html

 * https://github.com/rejectedsoftware/ddox


 Man, how did I miss that? I like that.


 http://vibed.org/temp/phobos/std/datetime.html

 Wow, that's a HUGE improvement to what has been a very difficult read
 for std.datetime.

 I'd like to bookmark the Vibe Phobos reference page for use as my
 library reference. Will it remain there at least until the official web
 page reference is improved in a similar or identical way?


Do whom do we talk about Borging the vibe dox into dlang.org?

Andrei
Dec 11 2012
next sibling parent reply "Pragma Tix" <bizprac orange.fr> writes:
On Tuesday, 11 December 2012 at 21:13:25 UTC, Andrei Alexandrescu 
wrote:

 On 12/11/12 3:54 PM, Rob T wrote:

 On Monday, 10 December 2012 at 22:33:49 UTC, 1100110 wrote:

 On 12/10/2012 05:16 AM, Mr. Anonymous wrote:

 On Monday, 10 December 2012 at 02:10:43 UTC, Ellery Newcomer 
 wrote:

 Is anyone else noticing e.g. std.datetime taking upwards of 
 30 seconds
 to render the blob of links at the top? It's freakin 
 freezing my
 entire browser.


 ddox* on dlang.org, anyone?
 http://vibed.org/temp/phobos/index.html

 * https://github.com/rejectedsoftware/ddox


 Man, how did I miss that? I like that.


 http://vibed.org/temp/phobos/std/datetime.html

 Wow, that's a HUGE improvement to what has been a very 
 difficult read
 for std.datetime.

 I'd like to bookmark the Vibe Phobos reference page for use as 
 my
 library reference. Will it remain there at least until the 
 official web
 page reference is improved in a similar or identical way?


 Do whom do we talk about Borging the vibe dox into dlang.org?

 Andrei


Soenke Ludwig, or ask here
http://news.rejectedsoftware.com/groups/rejectedsoftware.vibed/
IMO dlang should be powered by vibe.d
Dec 11 2012
parent "Rob T" <rob ucora.com> writes:
On Tuesday, 11 December 2012 at 21:41:10 UTC, Pragma Tix wrote:

 Soenke Ludwig, or ask here
 http://news.rejectedsoftware.com/groups/rejectedsoftware.vibed/
 IMO dlang should be powered by vibe.d


If Vibe.d is stable enough at this point (it's a WIP) then yes 
that would be a good idea, and a good pitch for both D and Vide.

--rt
Dec 12 2012
prev sibling next sibling parent =?UTF-8?B?U8O2bmtlIEx1ZHdpZw==?= <sludwig outerproduct.org> writes:
Am 11.12.2012 22:13, schrieb Andrei Alexandrescu:

 On 12/11/12 3:54 PM, Rob T wrote:

 On Monday, 10 December 2012 at 22:33:49 UTC, 1100110 wrote:

 On 12/10/2012 05:16 AM, Mr. Anonymous wrote:

 On Monday, 10 December 2012 at 02:10:43 UTC, Ellery Newcomer wrote:

 Is anyone else noticing e.g. std.datetime taking upwards of 30 seconds
 to render the blob of links at the top? It's freakin freezing my
 entire browser.


 ddox* on dlang.org, anyone?
 http://vibed.org/temp/phobos/index.html

 * https://github.com/rejectedsoftware/ddox


 Man, how did I miss that? I like that.


 http://vibed.org/temp/phobos/std/datetime.html

 Wow, that's a HUGE improvement to what has been a very difficult read
 for std.datetime.

 I'd like to bookmark the Vibe Phobos reference page for use as my
 library reference. Will it remain there at least until the official web
 page reference is improved in a similar or identical way?


 
 Do whom do we talk about Borging the vibe dox into dlang.org?
 
 Andrei
 


Sorry, didn't see this until now. So from the top of my head these would be the
points that are
necessary to properly integrate it:

 1. Need to write a template that integrates nicely with dlang.org (simple
part).

 2. Some adjustments to the Phobos DDOC comments are necessary. Some macros
insert manual links or
other things that may not be needed or would insert the wrong target URLs (e.g.
$(MYREF) in
std.algorithm). The docs automatically get full cross linking by searching the
doc comments for
identifiers. This also means that there may be a (higher) number of false
positives which need to be
escaped with "_" as per the DDOC specification.

 3. Some adjustments for (or an alternative version of) std.ddoc to leave out
some HTML styling or
linking

 4. There are probably some smaller glitches that need to be resolved over time
(such as the
"See_Also:" section, which should probably be displayed as "See also" or in a
whole different way).

 5. The JSON output is a bit sparse and buggy in some places (templates,
enums), which results in
missing bits in some places. I'm counting on
https://github.com/D-Programming-Language/dmd/pull/1179
to fix this at some point.


I could make a repository and put everything needed for 1, 3 and 4, as well as
a generator script,
in there. 2 mostly needs to be tackled in the Phobos sources but shouldn't be
that big of a deal.
Dec 12 2012
prev sibling parent reply =?UTF-8?B?U8O2bmtlIEx1ZHdpZw==?= <sludwig outerproduct.org> writes:
Am 11.12.2012 22:13, schrieb Andrei Alexandrescu:

 On 12/11/12 3:54 PM, Rob T wrote:

 On Monday, 10 December 2012 at 22:33:49 UTC, 1100110 wrote:

 On 12/10/2012 05:16 AM, Mr. Anonymous wrote:

 On Monday, 10 December 2012 at 02:10:43 UTC, Ellery Newcomer wrote:

 Is anyone else noticing e.g. std.datetime taking upwards of 30 seconds
 to render the blob of links at the top? It's freakin freezing my
 entire browser.


 ddox* on dlang.org, anyone?
 http://vibed.org/temp/phobos/index.html

 * https://github.com/rejectedsoftware/ddox


 Man, how did I miss that? I like that.


 http://vibed.org/temp/phobos/std/datetime.html

 Wow, that's a HUGE improvement to what has been a very difficult read
 for std.datetime.

 I'd like to bookmark the Vibe Phobos reference page for use as my
 library reference. Will it remain there at least until the official web
 page reference is improved in a similar or identical way?


 
 Do whom do we talk about Borging the vibe dox into dlang.org?
 
 Andrei
 


Okay, I have prepared a small repository which generates Phobos/Druntime
documentation and
integrates it into dlang.org (it currently needs vibe.d installed to build the
ddox binary):

https://github.com/s-ludwig/phobos-docs


The paths are currently adjusted for working side-by-side with phobos, druntime
and
d-programming-language.org:

-----
/
	/dprogramming-language.org/
	/druntime/
	/phobos/
	/phobos-docs/
-----


There are some batch files that generate the documentation. Running the
following sequence will
yield HTML docs in ../d-programming-language.org/phobos/:

-----
cd phobos-docs
vibe build
generate_json
filter_json
generate_html
-----

Example generated site is here:

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


Is any further work on this desired? If so, what would be the next steps to
integrate it into the
general dlang.org workflow? (or rather, how is that workflow in terms of folder
structure, build
scripts etc.?)

It would also need a phase of bug fixing regarding some macros used in the
Phobos ddoc comments.
Dec 21 2012
next sibling parent reply Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
On 12/21/12, S=F6nke Ludwig <sludwig outerproduct.org> wrote:

 Is any further work on this desired?


The start of the code section needs to be moved a little bit to the
right so the text doesn't appear to touch the edge:
http://i.imgur.com/VuXE1.png

And maybe the color scheme should match the one before, dark text on
light background, since that's the color scheme of the rests of the
text. Personally I use a similar theme like yours, but for the website
it might be better to match the way it already looks.
Dec 21 2012
parent =?ISO-8859-1?Q?S=F6nke_Ludwig?= <sludwig outerproduct.org> writes:
Am 21.12.2012 15:20, schrieb Andrej Mitrovic:

 On 12/21/12, Snke Ludwig <sludwig outerproduct.org> wrote:

 Is any further work on this desired?


 
 The start of the code section needs to be moved a little bit to the
 right so the text doesn't appear to touch the edge:
 http://i.imgur.com/VuXE1.png
 
 And maybe the color scheme should match the one before, dark text on
 light background, since that's the color scheme of the rests of the
 text. Personally I use a similar theme like yours, but for the website
 it might be better to match the way it already looks.
 


Done. (I forgot about the code styling all together)

Btw. is there a good syntax highlighter written in D, ideally with
multi-language support? Currently
I'm using a modified version of Google Prettify (JavaScript). But it would be
nice to have the
highlighting baked into the static HTML.
Dec 21 2012
prev sibling next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2012-12-21 13:24, Sönke Ludwig wrote:


 Example generated site is here:

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


 Is any further work on this desired? If so, what would be the next steps to
integrate it into the
 general dlang.org workflow? (or rather, how is that workflow in terms of
folder structure, build
 scripts etc.?)


Nice. Now we need to just remove those ugly manually create tables. I'm 
thinking mainly on those on top of std.algorithm.

What also would be nice is to have the methods inline, expandable.

I get a JavaScript error when I'm selecting the search field:

SyntaxError: syntax error
[Break On This Error] 	

if(this.value ==

github...769e.js (line 3, col 17)

-- 
/Jacob Carlborg
Dec 21 2012
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/21/12 10:43 AM, Jacob Carlborg wrote:

 On 2012-12-21 13:24, Sönke Ludwig wrote:


 Example generated site is here:

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


 Is any further work on this desired? If so, what would be the next
 steps to integrate it into the
 general dlang.org workflow? (or rather, how is that workflow in terms
 of folder structure, build
 scripts etc.?)


 Nice. Now we need to just remove those ugly manually create tables. I'm
 thinking mainly on those on top of std.algorithm.


s/remove/integrate/
s/ugly/awesome/

The cheat sheet in std.algorithm is unnecessary (though I liked the 
brief examples), but there's a lot of value in the symbols grouped by 
category (searching, comparison, ...) at the top. So we need to have a 
means to group things in the new interface.


 What also would be nice is to have the methods inline, expandable.


That would be awesome!

Andrei
Dec 21 2012
next sibling parent reply "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Fri, Dec 21, 2012 at 12:05:47PM -0500, Andrei Alexandrescu wrote:

 On 12/21/12 10:43 AM, Jacob Carlborg wrote:

On 2012-12-21 13:24, Snke Ludwig wrote:


Example generated site is here:

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


Is any further work on this desired? If so, what would be the next
steps to integrate it into the general dlang.org workflow? (or
rather, how is that workflow in terms of folder structure, build
scripts etc.?)


Nice. Now we need to just remove those ugly manually create tables.
I'm thinking mainly on those on top of std.algorithm.




We need a way to group methods by (manually-assigned) category.



 s/remove/integrate/
 s/ugly/awesome/
 
 The cheat sheet in std.algorithm is unnecessary (though I liked the
 brief examples), but there's a lot of value in the symbols grouped by
 category (searching, comparison, ...) at the top. So we need to have a
 means to group things in the new interface.


+1. The blob of links generated by JS at the top of the current pages is
(1) ugly, and (2) useless. Grouping symbols by category is by far more
useful. We need to keep that.



What also would be nice is to have the methods inline, expandable.


 
 That would be awesome!


[...]

That would be nice, but could we make that optional please? As in, I'd
still like to be able to scroll down to read the perhaps longer and more
detailed description.

Alternatively, have the method signature and perhaps first paragraph or
two in the expandable header, which links to the full description
further down the page.


T

-- 
Try to keep an open mind, but not so open your brain falls out. -- theboz
Dec 21 2012
parent reply "Rob T" <rob ucora.com> writes:
On Friday, 21 December 2012 at 17:23:41 UTC, H. S. Teoh wrote:

 +1. The blob of links generated by JS at the top of the current 
 pages is
 (1) ugly, and (2) useless. Grouping symbols by category is by 
 far more
 useful. We need to keep that.


Yes, a category list is far more useful. The best the blob serves 
is as an appendix for the module, but it should be at the bottom 
of the page not at the top, and perhaps make it hidden requiring 
a click to view it.

--rt
Dec 21 2012
parent "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Fri, Dec 21, 2012 at 07:20:16PM +0100, Rob T wrote:

 On Friday, 21 December 2012 at 17:23:41 UTC, H. S. Teoh wrote:

+1. The blob of links generated by JS at the top of the current pages
is (1) ugly, and (2) useless. Grouping symbols by category is by far
more useful. We need to keep that.


 
 Yes, a category list is far more useful. The best the blob serves is
 as an appendix for the module, but it should be at the bottom of the
 page not at the top, and perhaps make it hidden requiring a click to
 view it.


[...]

This is a good idea. Put it at the bottom of the page as an index of
some sort.


T

-- 
Береги платье снову, а здоровье смолоду.
Dec 21 2012
prev sibling next sibling parent reply =?UTF-8?B?U8O2bmtlIEx1ZHdpZw==?= <sludwig outerproduct.org> writes:
Am 21.12.2012 18:05, schrieb Andrei Alexandrescu:

 (...)
 
 The cheat sheet in std.algorithm is unnecessary (though I liked the brief
examples), but there's a
 lot of value in the symbols grouped by category (searching, comparison, ...)
at the top. So we need
 to have a means to group things in the new interface.


Ideally, we would invent some standard DDOC syntax to specify groups then. But
generally an
ungrouped list also has its advantages when you try to look something up _by
name_. I've found
myself in the past, skimming over the category table multiple times, looking
for a certain function,
until deciding that I had to guess the category first, which may not always be
obvious.

So maybe keeping the manual category quick index table (and maybe putting it in
a separate
"Categories:" section) is a viable option for the time being? Most modules
probably wouldn't need
one anyway.


 What also would be nice is to have the methods inline, expandable.




Would that mean the Classes/Structs/... tables as f.ex. in std.datetime?
So there would be a small clickable thing and all members would fly out below
it as direct links?
and possibly with the short description?
What about different kinds of members? Only methods, all grouped by type or all
in one list?

I'm just asking because I don't have any preferences for how such a thing
should look like.
Dec 21 2012
next sibling parent Jacob Carlborg <doob me.com> writes:
On 2012-12-21 19:31, Sönke Ludwig wrote:


 What also would be nice is to have the methods inline, expandable.




 Would that mean the Classes/Structs/... tables as f.ex. in std.datetime?
 So there would be a small clickable thing and all members would fly out below
it as direct links?
 and possibly with the short description?
 What about different kinds of members? Only methods, all grouped by type or
all in one list?

 I'm just asking because I don't have any preferences for how such a thing
should look like.


I was mostly thinking of the free functions. Instead of going to a new 
page when clicking on a function it would just expand the same content 
inline. For classes and structs we might want to keep the separate page 
since it will contain additional members. But I'm not sure.

-- 
/Jacob Carlborg
Dec 21 2012
prev sibling parent "foobar" <foo bar.com> writes:
On Friday, 21 December 2012 at 18:31:48 UTC, Sönke Ludwig wrote:

 Am 21.12.2012 18:05, schrieb Andrei Alexandrescu:

 (...)
 
 The cheat sheet in std.algorithm is unnecessary (though I 
 liked the brief examples), but there's a
 lot of value in the symbols grouped by category (searching, 
 comparison, ...) at the top. So we need
 to have a means to group things in the new interface.


 Ideally, we would invent some standard DDOC syntax to specify 
 groups then. But generally an
 ungrouped list also has its advantages when you try to look 
 something up _by name_. I've found
 myself in the past, skimming over the category table multiple 
 times, looking for a certain function,
 until deciding that I had to guess the category first, which 
 may not always be obvious.

 So maybe keeping the manual category quick index table (and 
 maybe putting it in a separate
 "Categories:" section) is a viable option for the time being? 
 Most modules probably wouldn't need
 one anyway.


 What also would be nice is to have the methods inline, 
 expandable.




 Would that mean the Classes/Structs/... tables as f.ex. in 
 std.datetime?
 So there would be a small clickable thing and all members would 
 fly out below it as direct links?
 and possibly with the short description?
 What about different kinds of members? Only methods, all 
 grouped by type or all in one list?

 I'm just asking because I don't have any preferences for how 
 such a thing should look like.


Other docs systems provide a sorted index of symbols and also the 
module tree can be further expanded to see the contained symbols. 
Both very handy features.
Dec 22 2012
prev sibling parent reply Jacob Carlborg <doob me.com> writes:
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.

-- 
/Jacob Carlborg
Dec 21 2012
parent reply "foobar" <foo bar.com> writes:
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.
Dec 22 2012
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
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
Dec 22 2012
parent reply "foobar" <foo bar.com> writes:
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.
Dec 23 2012
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
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
Dec 23 2012
parent reply "foobar" <foo bar.com> writes:
On Sunday, 23 December 2012 at 13:21:16 UTC, Andrei Alexandrescu 
wrote:

 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


Does it mean you agree with the rest? :)

Regarding std.algorithm, the module isn't called - 'classic, 
consecrated algorithms the kind you'll find in a book entitled 
"Algorithms"'. It is simply called 'std.algorithm' and there are 
many, *many* books on algorithms. Should this module include 
concurrent algorithms? Should it include distributed algorithms? 
Should it include statistic algorithms? Should it include natural 
language processing algorithms? Should it include genetic 
algorithms? I think it's clear by now that the name does not 
convey what you intend it to convey.

A much better and more user friendly scheme would be to classify 
the algorithms by their *functionality* and not by some undefined 
"belongs to classical algorithms books" relation.
e.g. "Sorting algorithms", "Set operations", etc.
Now, if I want to sort something I know to "shop" at the "sorting 
algorithms" outlet and don't need to spend time going over a 
potentially infinite list of algorithms.
Dec 23 2012
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/23/12 9:08 AM, foobar wrote:

 Regarding std.algorithm, the module isn't called - 'classic, consecrated
 algorithms the kind you'll find in a book entitled "Algorithms"'. It is
 simply called 'std.algorithm' and there are many, *many* books on
 algorithms. Should this module include concurrent algorithms? Should it
 include distributed algorithms? Should it include statistic algorithms?
 Should it include natural language processing algorithms? Should it
 include genetic algorithms? I think it's clear by now that the name does
 not convey what you intend it to convey.


Importing std.container doesn't mean all containers conceivable will be 
there, and so on. Sense and sensibility must always be exercised.


 A much better and more user friendly scheme would be to classify the
 algorithms by their *functionality* and not by some undefined "belongs
 to classical algorithms books" relation.
 e.g. "Sorting algorithms", "Set operations", etc.
 Now, if I want to sort something I know to "shop" at the "sorting
 algorithms" outlet and don't need to spend time going over a potentially
 infinite list of algorithms.


I like std.algorithm the way it is.


Andrei
Dec 23 2012
parent reply "John Colvin" <john.loughran.colvin gmail.com> writes:
On Sunday, 23 December 2012 at 14:43:25 UTC, Andrei Alexandrescu 
wrote:

 On 12/23/12 9:08 AM, foobar wrote:

 Regarding std.algorithm, the module isn't called - 'classic, 
 consecrated
 algorithms the kind you'll find in a book entitled 
 "Algorithms"'. It is
 simply called 'std.algorithm' and there are many, *many* books 
 on
 algorithms. Should this module include concurrent algorithms? 
 Should it
 include distributed algorithms? Should it include statistic 
 algorithms?
 Should it include natural language processing algorithms? 
 Should it
 include genetic algorithms? I think it's clear by now that the 
 name does
 not convey what you intend it to convey.


 Importing std.container doesn't mean all containers conceivable 
 will be there, and so on. Sense and sensibility must always be 
 exercised.


 A much better and more user friendly scheme would be to 
 classify the
 algorithms by their *functionality* and not by some undefined 
 "belongs
 to classical algorithms books" relation.
 e.g. "Sorting algorithms", "Set operations", etc.
 Now, if I want to sort something I know to "shop" at the 
 "sorting
 algorithms" outlet and don't need to spend time going over a 
 potentially
 infinite list of algorithms.


 I like std.algorithm the way it is.


 Andrei


On Sunday, 23 December 2012 at 14:43:25 UTC, Andrei Alexandrescu
wrote:

 On 12/23/12 9:08 AM, foobar wrote:

 Regarding std.algorithm, the module isn't called - 'classic, 
 consecrated
 algorithms the kind you'll find in a book entitled 
 "Algorithms"'. It is
 simply called 'std.algorithm' and there are many, *many* books 
 on
 algorithms. Should this module include concurrent algorithms? 
 Should it
 include distributed algorithms? Should it include statistic 
 algorithms?
 Should it include natural language processing algorithms? 
 Should it
 include genetic algorithms? I think it's clear by now that the 
 name does
 not convey what you intend it to convey.


 Importing std.container doesn't mean all containers conceivable 
 will be there, and so on. Sense and sensibility must always be 
 exercised.


 A much better and more user friendly scheme would be to 
 classify the
 algorithms by their *functionality* and not by some undefined 
 "belongs
 to classical algorithms books" relation.
 e.g. "Sorting algorithms", "Set operations", etc.
 Now, if I want to sort something I know to "shop" at the 
 "sorting
 algorithms" outlet and don't need to spend time going over a 
 potentially
 infinite list of algorithms.


 I like std.algorithm the way it is.


 Andrei


Same here. In my mind it's about generality:

General purpose algorithms (sort, partition etc.) belong in
std.algorithm and more specific algorithms belong in their own
appropriately named modules.
Dec 23 2012
parent reply "Peter Alexander" <peter.alexander.au gmail.com> writes:
On Sunday, 23 December 2012 at 16:06:57 UTC, John Colvin wrote:

 On Sunday, 23 December 2012 at 14:43:25 UTC, Andrei 
 Alexandrescu wrote:

 I like std.algorithm the way it is.


 Andrei


 Same here. In my mind it's about generality:

 General purpose algorithms (sort, partition etc.) belong in
 std.algorithm and more specific algorithms belong in their own
 appropriately named modules.


Levenshtein distance is general purpose?

I'm not too fussed about std.algorithm, but I think it could be 
better. Here's some criticisms I have:

1. The iteration algorithms should be std.range. I find it 
confusing that (for example) joiner and chain are in different 
modules when they are so similar.

2. The set algorithms should be in their own module. They are 
rarely used and quite specific in what they do.

3. The sorting algorithms should be in their own module. There 
are many different sorting algorithms that could be added, and if 
they stay in std.algorithm then it is going to get quite bloated.

Interestingly, EASTL also decided to split C++'s <algorithm> into 
sorting, set, and heap components. I think this is the right 
thing to do.

http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2271.html

My main worry is that std.algorithm becomes std.miscellaneous -- 
a place where things go when you can't think where else to put 
them. The reason this happens is because of the name. As someone 
mentioned earlier, just about every function implements an 
"algorithm" of some sort, so people can feel justified in putting 
everything in std.algorithm. Heck, if "min" is an "algorithm" 
then anything is!

Would it be possible to split the library up and add public 
imports to std.algorithm of the moved symbols?
Dec 23 2012
next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/23/12 12:54 PM, Peter Alexander wrote:

 On Sunday, 23 December 2012 at 16:06:57 UTC, John Colvin wrote:

 On Sunday, 23 December 2012 at 14:43:25 UTC, Andrei Alexandrescu wrote:

 I like std.algorithm the way it is.


 Andrei


 Same here. In my mind it's about generality:

 General purpose algorithms (sort, partition etc.) belong in
 std.algorithm and more specific algorithms belong in their own
 appropriately named modules.


 Levenshtein distance is general purpose?


There's always stuff on the fringes that could be debated one way or 
another.


 I'm not too fussed about std.algorithm, but I think it could be better.
 Here's some criticisms I have:

 1. The iteration algorithms should be std.range. I find it confusing
 that (for example) joiner and chain are in different modules when they
 are so similar.


I agree, but then I guess it's not too bad the way it is.


 2. The set algorithms should be in their own module. They are rarely
 used and quite specific in what they do.


But then there's stuff such as group that is set-oriented yet quite 
useful in general.


 3. The sorting algorithms should be in their own module. There are many
 different sorting algorithms that could be added, and if they stay in
 std.algorithm then it is going to get quite bloated.


I guess. But then approaches could be implemented as policies to sort etc.


 Interestingly, EASTL also decided to split C++'s <algorithm> into
 sorting, set, and heap components. I think this is the right thing to do.

 http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2271.html

 My main worry is that std.algorithm becomes std.miscellaneous -- a place
 where things go when you can't think where else to put them. The reason
 this happens is because of the name. As someone mentioned earlier, just
 about every function implements an "algorithm" of some sort, so people
 can feel justified in putting everything in std.algorithm. Heck, if
 "min" is an "algorithm" then anything is!

 Would it be possible to split the library up and add public imports to
 std.algorithm of the moved symbols?


To be frank, I look at the problems D is facing right now and really the 
(re)organization of std.algorithm is nowhere near the top of the list. 
If we were a perfectly efficient forum, we wouldn't be discussing it now 
at all.


Andrei
Dec 23 2012
prev sibling parent Jonathan M Davis <jmdavisProg gmx.com> writes:
On Sunday, December 23, 2012 18:54:15 Peter Alexander wrote:

 Would it be possible to split the library up and add public
 imports to std.algorithm of the moved symbols?


DIPs 15 and 16 relate to the ability to split up a module into separate 
modules within a package with the same name without breaking code. If 
something along those lines were implemented, it would potentially make some 
sense to reorganize std.algorithm as a package. I'd definitely break up 
std.datetime if something like that were implemented, but someone has to do 
it. I started looking into it at one point, but I have far higher priorities 
right now, so I didn't get very far and don't have time to tackle it right 
now.

- Jonathan M Davis
Dec 23 2012
prev sibling next sibling parent Dmitry Olshansky <dmitry.olsh gmail.com> writes:
12/21/2012 4:24 PM, Sönke Ludwig пишет:

 Am 11.12.2012 22:13, schrieb Andrei Alexandrescu:

 Do whom do we talk about Borging the vibe dox into dlang.org?

 Andrei




[snip]

 Example generated site is here:

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


Like it!



-- 
Dmitry Olshansky
Dec 21 2012
prev sibling next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/21/12 7:24 AM, Sönke Ludwig wrote:

 Example generated site is here:

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


 Is any further work on this desired?


Thanks for this work! Let me provide a little feedback. I'm looking 
mainly at std.array and std.algorithm.

* There's lots of wasted real estate at the top of the page: the source, 
license, and authors sections are way spaced. They should compactly fill 
the top of the page.

* Differentiating "Functions" and "Templates" is unnecessary and 
tenuous. Generic functions are functions. Everything should go in one place.

* The paragraph heading "Functions:" followed immediately by "Function 
name" is redundant.

* The individual pages repeat the text on the page. We should have a way 
to differentiate the blurb from the full description. For example:

// inside array.d
/**
$(BLURB Replace occurrences of from with to in subject.) Returns a new 
array without changing the contents of subject, or the original array if 
no match is found.
*/
E[] replace((E,R1,R2) if (isDynamicArray!(E[]) && isForwardRange!(R1) && 
isForwardRange!(R2) && (hasLength!(R2) || isSomeString!(R2))))(   E[] 
subject,   R1 from,   R2 to ) { ... }

The blurb would be present in the short doc, and the blurb followed by 
the rest of the text and the signature would appear in the full page.

* "Module" in the title is redundant I guess.

* The styling on the "+" signs in the left column should be different 
when the tree branch is open or closed.

* I yearned for a long time for a per-symbol page, and I'd be really 
happy to migrate toward that. One important consequence here is that we 
can improve each function's (struct's, class' etc) documentation without 
bloating the general documentation, which remains terse. In that vein, 
I'm looking at the PHP docs (which have opted for a similar structure) 
and that are of excellent quality. See e.g. 
http://us1.php.net/manual/en/function.fopen.php that inspires a few 
bullets below.

* There's a "Changelog" section which we can add to help with any 
backward compatibility issue.

* "See also" is awesome.

* But by very, very far the community-contributed stuff is just perfect. 
I really really really hope we can get something like that integrated. 
There are many ways to approach this:

- By integrating a wiki page via e.g. an IFRAME.
- By integrating with github
- Through a separate custom layer (a la forum.dlang.org)
- Whatever it is, we'd need some crowdsourcing (voting system etc) such 
that good community notes go up and bad notes go down or get ultimately 
deleted.

* Would be awesome to have the implementation at entity level in an 
expandable IFRAME instead of linking to the entire github implementation 
of the file.


Thanks,

Andrei
Dec 21 2012
next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/21/12 6:46 PM, Andrei Alexandrescu wrote:
[snip]

Forgot to emphasize what I already mentioned: alphabetic order is okay, 
but I wonder how we can integrate that with grouping per functionality 
area (the way std.algorithm does).

Andrei
Dec 21 2012
prev sibling next sibling parent "bearophile" <bearophileHUGS lycos.com> writes:
Andrei Alexandrescu:


 Thanks for this work! Let me provide a little feedback. I'm 
 looking mainly at std.array and std.algorithm.


Compare a page like this:
http://dlang.org/phobos/std_array.html

With the docs of the Prelude module of Haskell:
http://www.haskell.org/ghc/docs/latest/html/libraries/base/Prelude.html

Similarly in the pages of D Phobos docs I'd like each function to 
have a link to its source, and not just have a single link to the 
whole module. This allows to find faster the source code of that 
function.

Bye,
bearophile
Dec 21 2012
prev sibling next sibling parent reply Brad Roberts <braddr slice-2.puremagic.com> writes:
On Fri, 21 Dec 2012, Andrei Alexandrescu wrote:


 * But by very, very far the community-contributed stuff is just perfect. I
 really really really hope we can get something like that integrated. There are
 many ways to approach this:
 
 - By integrating a wiki page via e.g. an IFRAME.
 - By integrating with github
 - Through a separate custom layer (a la forum.dlang.org)
 - Whatever it is, we'd need some crowdsourcing (voting system etc) such that
 good community notes go up and bad notes go down or get ultimately deleted.
 
 * Would be awesome to have the implementation at entity level in an expandable
 IFRAME instead of linking to the entire github implementation of the file.


I love community / croudsourcing.  But where it falls down in most of the 
examples I've seen is that the majority of the feedback / comments really 
belong as edits to the actual content, not additional notes.  We need to 
aim for making both happen, imho.  Allow ad-hoc extra feedback, but also 
get it cycled into the core page contents.

The current separate wiki pages that mirror the dlang site are the worse 
of both worlds in that the content exists, is hardly ever folded in, and 
isn't even visible along side the page but hidden off behind a link that I 
bet most people never even see.

Thoughts?

Later,
Brad
Dec 21 2012
next sibling parent reply "Rob T" <rob ucora.com> writes:
On Saturday, 22 December 2012 at 00:00:43 UTC, Brad Roberts wrote:

 The current separate wiki pages that mirror the dlang site are 
 the worse
 of both worlds in that the content exists, is hardly ever 
 folded in, and
 isn't even visible along side the page but hidden off behind a 
 link that I
 bet most people never even see.

 Thoughts?

 Later,
 Brad


I think the reason for the disconnection is due to the docs not 
being stored with the wiki and I don't see what can be done to 
merge the two since they are  two completely separate and 
different sources of documentation.

BTW, it turns out I didn't notice the wiki link until after 
reading your post! The link should be a button or something else 
that's much more noticeable and friendly for users to explore.

One grip do I have is that the "improve this page" system is 
rather unfriendly, and because of this I've not yet taken the 
time to research what I have to do to get to the point where I 
can contribute improvements. I suspect it turns away most people 
who otherwise would try and contribute.

In any event, what I see with the new document format is a very 
very large improvement and the sooner it is implemented (even 
with some of the minor flaws not yet fixed) the better.

--rt
Dec 21 2012
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/21/12 7:52 PM, Rob T wrote:

 On Saturday, 22 December 2012 at 00:00:43 UTC, Brad Roberts wrote:

 The current separate wiki pages that mirror the dlang site are the worse
 of both worlds in that the content exists, is hardly ever folded in, and
 isn't even visible along side the page but hidden off behind a link
 that I
 bet most people never even see.

 Thoughts?

 Later,
 Brad


 I think the reason for the disconnection is due to the docs not being
 stored with the wiki and I don't see what can be done to merge the two
 since they are two completely separate and different sources of
 documentation.


Behold: http://us3.php.net/manual/en/function.exp.php


 BTW, it turns out I didn't notice the wiki link until after reading your
 post! The link should be a button or something else that's much more
 noticeable and friendly for users to explore.


Even better, I think the content should be inlined!!!


 One grip do I have is that the "improve this page" system is rather
 unfriendly, and because of this I've not yet taken the time to research
 what I have to do to get to the point where I can contribute
 improvements. I suspect it turns away most people who otherwise would
 try and contribute.


Making it too easy may escalate moderation needs.


 In any event, what I see with the new document format is a very very
 large improvement and the sooner it is implemented (even with some of
 the minor flaws not yet fixed) the better.


Agreed.


Andrei
Dec 21 2012
parent reply "Rob T" <rob ucora.com> writes:
On Saturday, 22 December 2012 at 02:36:44 UTC, Andrei 
Alexandrescu wrote:


 I was referring only to the actual word.


Ah I see, but it's still debatable to remove, although not a big 
deal either way.


 Behold: http://us3.php.net/manual/en/function.exp.php


I understand what you mean now, just didn't at first. What I see 
looks very good in the php page.


 Even better, I think the content should be inlined!!!


Yes, that would be much better.


 Making it too easy may escalate moderation needs.


I see the point there. Improved wiki integration as suggested 
should be a good compromise.

--rt
Dec 21 2012
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/21/12 10:27 PM, Rob T wrote:

 Behold: http://us3.php.net/manual/en/function.exp.php


 I understand what you mean now, just didn't at first. What I see looks
 very good in the php page.


I think there's a lot to be said about the contribution of PHP's 
excellent documentation to the success of an otherwise unremarkable 
language.

Andrei
Dec 21 2012
parent "Rob T" <rob ucora.com> writes:
On Saturday, 22 December 2012 at 03:34:55 UTC, Andrei 
Alexandrescu wrote:

 On 12/21/12 10:27 PM, Rob T wrote:

 Behold: http://us3.php.net/manual/en/function.exp.php


 I understand what you mean now, just didn't at first. What I 
 see looks
 very good in the php page.


 I think there's a lot to be said about the contribution of 
 PHP's excellent documentation to the success of an otherwise 
 unremarkable language.

 Andrei


Ease of adoption is very important, and good documentation is 
certainly a big part of that. Another thing that helps is having 
a very good tool set for the programmers to use.

--rt
Dec 21 2012
prev sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/21/12 7:16 PM, Brad Roberts wrote:

 I love community / croudsourcing.  But where it falls down in most of the
 examples I've seen is that the majority of the feedback / comments really
 belong as edits to the actual content, not additional notes.  We need to
 aim for making both happen, imho.  Allow ad-hoc extra feedback, but also
 get it cycled into the core page contents.


The way I see it, changes to the core page contents go via github. The 
community-provided notes are crowdsourced and occasionally moderated.


 The current separate wiki pages that mirror the dlang site are the worse
 of both worlds in that the content exists, is hardly ever folded in, and
 isn't even visible along side the page but hidden off behind a link that I
 bet most people never even see.

 Thoughts?


That's why I'm saying the wiki pages should be accessible immediately 
alongside the abstractions they document.


Andrei
Dec 21 2012
prev sibling next sibling parent reply "Rob T" <rob ucora.com> writes:
On Friday, 21 December 2012 at 23:46:05 UTC, Andrei Alexandrescu 
wrote:

 * "Module" in the title is redundant I guess.


I don't think it is redundant because when you are looking at a 
page, the module as the title instantly tells you (or reminds 
you) what module you are looking at, otherwise you'll have to do 
a little bit more digging than should be necessary.

--rt
Dec 21 2012
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/21/12 7:29 PM, Rob T wrote:

 On Friday, 21 December 2012 at 23:46:05 UTC, Andrei Alexandrescu wrote:

 * "Module" in the title is redundant I guess.


 I don't think it is redundant because when you are looking at a page,
 the module as the title instantly tells you (or reminds you) what module
 you are looking at, otherwise you'll have to do a little bit more
 digging than should be necessary.

 --rt


I was referring only to the actual word.

Andrei
Dec 21 2012
prev sibling next sibling parent reply =?UTF-8?B?U8O2bmtlIEx1ZHdpZw==?= <sludwig outerproduct.org> writes:
Am 22.12.2012 00:46, schrieb Andrei Alexandrescu:

 On 12/21/12 7:24 AM, Sönke Ludwig wrote:

 Example generated site is here:

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


 Is any further work on this desired?


 
 Thanks for this work! Let me provide a little feedback. I'm looking mainly at
std.array and
 std.algorithm.


Thanks for the feedback. I'll continue to improve things along the way.


 
 * There's lots of wasted real estate at the top of the page: the source,
license, and authors
 sections are way spaced. They should compactly fill the top of the page.


I'll try to get closer to the original there. There are some differences
because the current pages
use a lot of non-semantic formatting (<b>, <br> etc) and the result of this
needs to be simulated
using CSS now.


 
 * Differentiating "Functions" and "Templates" is unnecessary and tenuous.
Generic functions are
 functions. Everything should go in one place.


This is actually a bug of the JSON output. Sometimes it will just output a
simple "template" node
instead of "function" nested in a "template". In that case there is not much I
can do,
unfortunately. But I hope that this will be addressed by the big DDOC pull
request.


 
 * The paragraph heading "Functions:" followed immediately by "Function name"
is redundant.


Right. Any preference? I would go for header + only "Name" in the table to keep
it visually
structured (I actually could have sworn I already did that some time ago, but
the commit is probably
lying locally on another machine).


 
 * The individual pages repeat the text on the page. We should have a way to
differentiate the blurb
 from the full description. For example:
 
 // inside array.d
 /**
 $(BLURB Replace occurrences of from with to in subject.) Returns a new array
without changing the
 contents of subject, or the original array if no match is found.
 */
 E[] replace((E,R1,R2) if (isDynamicArray!(E[]) && isForwardRange!(R1) &&
isForwardRange!(R2) &&
 (hasLength!(R2) || isSomeString!(R2))))(   E[] subject,   R1 from,   R2 to ) {
... }
 
 The blurb would be present in the short doc, and the blurb followed by the
rest of the text and the
 signature would appear in the full page.


The DDOC spec says that the first paragraph is the short summary (BLURB),
followed by the long
summary, which goes until the first section header. Some modules are not using
this correctly and
have a very long paragraph at the beginning.

(See http://dlang.org/ddoc.html under "Sections")

So currently the short description is repeated on the individual page, because
there often is
distinct content in it. That would also be an interesting documentation style
decision, if the long
summary must be able to stand alone (which would probably be nicer).


 
 * "Module" in the title is redundant I guess.


Due to the naming convention (module/package names lowercase) it somehow is.
But for the individual
pages, the distinction of class, struct, enum, function etc. is important.
Putting "Module" in front
of the module name is consistent with the other pages in this regard. But I
have no strong feeling
about this either.


 
 * The styling on the "+" signs in the left column should be different when the
tree branch is open
 or closed.


Agreed. The current icon is just a place holder. Any style precedence or
preference? (e.g. old
windows style with +/- or the new triangle thing)


 
 * I yearned for a long time for a per-symbol page, and I'd be really happy to
migrate toward that.
 One important consequence here is that we can improve each function's
(struct's, class' etc)
 documentation without bloating the general documentation, which remains terse.
In that vein, I'm
 looking at the PHP docs (which have opted for a similar structure) and that
are of excellent
 quality. See e.g. http://us1.php.net/manual/en/function.fopen.php that
inspires a few bullets below.


Yeah, that's the really nice aspect of it. You can actually feel the urge to
write more detailed
documentation because of this (at least I can ;) ).


 
 * There's a "Changelog" section which we can add to help with any backward
compatibility issue.
 
 * "See also" is awesome.
 
 * But by very, very far the community-contributed stuff is just perfect. I
really really really hope
 we can get something like that integrated. There are many ways to approach
this:
 
 - By integrating a wiki page via e.g. an IFRAME.
 - By integrating with github
 - Through a separate custom layer (a la forum.dlang.org)
 - Whatever it is, we'd need some crowdsourcing (voting system etc) such that
good community notes go
 up and bad notes go down or get ultimately deleted.


An easy option would be http://disqus.com/ - I've seen this used quite often
recently.

Btw., regarding sections, if, at some point, we want to visually separate
individual sections (or
make them collapsible), a careful pass through Phobos will be necessary,
because sections are often
introduced accidentally (e.g. a line "Example:" before a code block or
"Copyright: ... on a single
line), resulting in an illogical structure.


 
 * Would be awesome to have the implementation at entity level in an expandable
IFRAME instead of
 linking to the entire github implementation of the file.
 


A simple improvement would be to at least use a line anchor and automatically
scroll to the right
line. Displaying only the entity would require a new JSON field for the ending
line of an entity
(and some more work, of course).
Dec 22 2012
parent reply =?UTF-8?B?U8O2bmtlIEx1ZHdpZw==?= <sludwig outerproduct.org> writes:
 * There's lots of wasted real estate at the top of the page: the source,
license, and authors
 sections are way spaced. They should compactly fill the top of the page.


 
 I'll try to get closer to the original there. There are some differences
because the current pages
 use a lot of non-semantic formatting (<b>, <br> etc) and the result of this
needs to be simulated
 using CSS now.
 


Continuing the thought of screen real estate - shouldn't these sections better
be at the _bottom_ of
the page? After all they are just noise for the typical reader and since the
pages are not as long
anymore, they still won't get drowned by the rest of the page.
Dec 22 2012
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/22/12 11:49 AM, Sönke Ludwig wrote:

 * There's lots of wasted real estate at the top of the page: the source,
license, and authors
 sections are way spaced. They should compactly fill the top of the page.


 I'll try to get closer to the original there. There are some differences
because the current pages
 use a lot of non-semantic formatting (<b>,<br>  etc) and the result of this
needs to be simulated
 using CSS now.


 Continuing the thought of screen real estate - shouldn't these sections better
be at the _bottom_ of
 the page? After all they are just noise for the typical reader and since the
pages are not as long
 anymore, they still won't get drowned by the rest of the page.


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.

Andrei
Dec 22 2012
parent Walter Bright <newshound2 digitalmars.com> writes:
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.
Dec 23 2012
prev sibling parent reply =?UTF-8?B?U8O2bmtlIEx1ZHdpZw==?= <sludwig outerproduct.org> writes:
Am 22.12.2012 17:49, schrieb Sönke Ludwig:

 
 Continuing the thought of screen real estate - shouldn't these sections better
be at the _bottom_ of
 the page? After all they are just noise for the typical reader and since the
pages are not as long
 anymore, they still won't get drowned by the rest of the page.
 


In the latest upload a number of items is addressed:
 - vertical margins at the top
 - redundant column headers
 - +/- signs for the package tree
 - jumps to line numbers on github (which are off because of changes after the
release)
 - some macro processing fixes (e.g. std.array.popBack contained some bad HTML
because of this)
 - also moved the authors/license sections to the bottom to see how it looks

Needs F5 reloading because of caching.
Dec 22 2012
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/22/12 12:53 PM, Sönke Ludwig wrote:

 Am 22.12.2012 17:49, schrieb Sönke Ludwig:

 Continuing the thought of screen real estate - shouldn't these sections better
be at the _bottom_ of
 the page? After all they are just noise for the typical reader and since the
pages are not as long
 anymore, they still won't get drowned by the rest of the page.


 In the latest upload a number of items is addressed:
   - vertical margins at the top
   - redundant column headers
   - +/- signs for the package tree
   - jumps to line numbers on github (which are off because of changes after
the release)
   - some macro processing fixes (e.g. std.array.popBack contained some bad
HTML because of this)
   - also moved the authors/license sections to the bottom to see how it looks


For the lazy: 
http://vibed.org/temp/d-programming-language.org/phobos/index.html


 Needs F5 reloading because of caching.


Or Command-R :o).


Andrei
Dec 22 2012
parent =?UTF-8?B?U8O2bmtlIEx1ZHdpZw==?= <sludwig outerproduct.org> writes:
Am 22.12.2012 19:13, schrieb Andrei Alexandrescu:

 On 12/22/12 12:53 PM, Sönke Ludwig wrote:

 Am 22.12.2012 17:49, schrieb Sönke Ludwig:

 Continuing the thought of screen real estate - shouldn't these sections better
be at the _bottom_ of
 the page? After all they are just noise for the typical reader and since the
pages are not as long
 anymore, they still won't get drowned by the rest of the page.


 In the latest upload a number of items is addressed:
   - vertical margins at the top
   - redundant column headers
   - +/- signs for the package tree
   - jumps to line numbers on github (which are off because of changes after
the release)
   - some macro processing fixes (e.g. std.array.popBack contained some bad
HTML because of this)
   - also moved the authors/license sections to the bottom to see how it looks


 
 For the lazy: http://vibed.org/temp/d-programming-language.org/phobos/index.html
 

 Needs F5 reloading because of caching.


 
 Or Command-R :o).
 
 
 Andrei


Right... I remember there was this certain system with strange mice and strange
keyboards, where I
ripped my hair off numerous times after trying to type an   ;)
Dec 22 2012
prev sibling next sibling parent reply "Jacob Carlborg" <doob me.com> writes:
On Saturday, 22 December 2012 at 17:54:29 UTC, Sönke Ludwig wrote:


 In the latest upload a number of items is addressed:
  - vertical margins at the top
  - redundant column headers
  - +/- signs for the package tree
  - jumps to line numbers on github (which are off because of 
 changes after the release)
  - some macro processing fixes (e.g. std.array.popBack 
 contained some bad HTML because of this)
  - also moved the authors/license sections to the bottom to see 
 how it looks

 Needs F5 reloading because of caching.


Clicking std.array.appender results in a 404 page.

--
/Jacob Carlborg
Dec 22 2012
parent =?UTF-8?B?U8O2bmtlIEx1ZHdpZw==?= <sludwig outerproduct.org> writes:
Am 22.12.2012 19:20, schrieb Jacob Carlborg:

 On Saturday, 22 December 2012 at 17:54:29 UTC, Sönke Ludwig wrote:
 

 In the latest upload a number of items is addressed:
  - vertical margins at the top
  - redundant column headers
  - +/- signs for the package tree
  - jumps to line numbers on github (which are off because of changes after the
release)
  - some macro processing fixes (e.g. std.array.popBack contained some bad HTML
because of this)
  - also moved the authors/license sections to the bottom to see how it looks

 Needs F5 reloading because of caching.


 
 Clicking std.array.appender results in a 404 page.
 
 -- 
 /Jacob Carlborg


Looks like a Windows file system problem. Appender.html was overwritten by
appender.html before
upload (or vice versa) and only Appender.html with appender.html's contents
ended up on the server.

Some escaping of capital letters is probably in order - just a bit sad that the
URLs get a bit
uglier then. Any other ideas?
Dec 22 2012
prev sibling next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/22/12 12:53 PM, Sönke Ludwig wrote:

 Am 22.12.2012 17:49, schrieb Sönke Ludwig:

 Continuing the thought of screen real estate - shouldn't these sections better
be at the _bottom_ of
 the page? After all they are just noise for the typical reader and since the
pages are not as long
 anymore, they still won't get drowned by the rest of the page.


 In the latest upload a number of items is addressed:


Much better. A few more comments.

First on the module-level pages.

* Styling at the top is still too sparse. How about adding a "Source" 
Button in line with (and to the left of) "Improve this page" and "Page 
wiki"?

* Clicking on "source" actually doesn't work (mind the underscore)

* Spacing of cell text in tables is larger at the bottom. I think 
spacing should be equally distributed (while staying equal in total).

* Spacing of lines inside a paragraph in the table should be a tad 
smaller. But only in the module-level table, not all paragraphs.

Now onto the item-level pages, using 
http://vibed.org/temp/d-programming-language.org/phobos/std/
ile/attrIsFile.html 
as an example.

* I'm thinking the authors and license should not be present on each 
item-level page.

* Function name in the heading should be in code font.

* The module of the function (std.file) should be obvious and easy to 
navigate to through one click. One idea is to say "Function 
std.file.attrIsFile" and make the "std.file" portion a link to the module.

* The left column should scroll to show the selected module. For 
attrIsFile that's not the case on some screens (the selection std/file 
is invisible unless user scrolls down).

* For the "Parameters" section, either keep the "Parameters:" heading 
and replace "Parameter name" with "Name", or (preferably) just delete 
"Parameters:" entirely.


Thanks,

Andrei
Dec 22 2012
parent reply =?UTF-8?B?U8O2bmtlIEx1ZHdpZw==?= <sludwig outerproduct.org> writes:
Am 22.12.2012 19:56, schrieb Andrei Alexandrescu:

 On 12/22/12 12:53 PM, Sönke Ludwig wrote:

 Am 22.12.2012 17:49, schrieb Sönke Ludwig:

 Continuing the thought of screen real estate - shouldn't these sections better
be at the _bottom_ of
 the page? After all they are just noise for the typical reader and since the
pages are not as long
 anymore, they still won't get drowned by the rest of the page.


 In the latest upload a number of items is addressed:


 
 Much better. A few more comments.
 
 First on the module-level pages.
 
 * Styling at the top is still too sparse. How about adding a "Source" Button
in line with (and to
 the left of) "Improve this page" and "Page wiki"?
 
 * Clicking on "source" actually doesn't work (mind the underscore)
 
 * Spacing of cell text in tables is larger at the bottom. I think spacing
should be equally
 distributed (while staying equal in total).
 
 * Spacing of lines inside a paragraph in the table should be a tad smaller.
But only in the
 module-level table, not all paragraphs.
 
 Now onto the item-level pages, using
 http://vibed.org/temp/d-programming-language.org/phobos/std/
ile/attrIsFile.html as an example.
 
 * I'm thinking the authors and license should not be present on each
item-level page.
 


Everything above has been incorporated. (uploading may still take a few minutes)


 * Function name in the heading should be in code font.
 
 * The module of the function (std.file) should be obvious and easy to navigate
to through one click.
 One idea is to say "Function std.file.attrIsFile" and make the "std.file"
portion a link to the module.
 


I've hacked that in, but I think different fonts inside headings look too
messy. Pity that there is
not already a place for a navigation bar in the page layout. That would be a
good fit.

But, regarding the header topic, now that the mini-sections from the top are
all gone, I've changed
the section headers back to a normal header style to get a little more cleaned
up look. They also
fight a lot less with the table headers like this.

Btw. - I didn't really want to get into styling issues, but anyway - the left
margin of examples vs.
no margin for tables is a bit disturbing IMO. Objections for removing it?


 * The left column should scroll to show the selected module. For attrIsFile
that's not the case on
 some screens (the selection std/file is invisible unless user scrolls down).
 


This would require a larger rework of the page layout. I would be very happy if
someone could
volunteer for such a thing, as I'm already stretching my time budget a lot.


PS: Firefox displays the code sections with a smaller font than it should. I'll
debug that later.
Dec 22 2012
parent reply "Rob T" <rob ucora.com> writes:
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
Dec 22 2012
parent reply =?UTF-8?B?U8O2bmtlIEx1ZHdpZw==?= <sludwig outerproduct.org> writes:
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.
Dec 22 2012
parent reply "Rob T" <rob ucora.com> writes:
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
Dec 23 2012
parent reply =?UTF-8?B?U8O2bmtlIEx1ZHdpZw==?= <sludwig outerproduct.org> writes:
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.
Dec 23 2012
parent reply Philippe Sigaud <philippe.sigaud gmail.com> writes:
Very nice-looking docs S=C3=B6nke!

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.htm=
l

Where std.parallelism appears as `std._parallelism` in the intro text.
Dec 23 2012
parent =?UTF-8?B?U8O2bmtlIEx1ZHdpZw==?= <sludwig outerproduct.org> writes:
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.
Dec 23 2012
prev sibling next sibling parent reply Jacob Carlborg <doob me.com> writes:
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
Dec 23 2012
parent =?UTF-8?B?U8O2bmtlIEx1ZHdpZw==?= <sludwig outerproduct.org> writes:
Am 23.12.2012 14:52, schrieb Jacob Carlborg:

 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?
 


I've locked it to the v2.060 tag now, but as far as I can see github also
allows to brows arbitrary
hashes, so this shouldn't be a problem.
Dec 23 2012
prev sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2012-12-22 18:53, Sönke Ludwig wrote:


 In the latest upload a number of items is addressed:
   - vertical margins at the top
   - redundant column headers
   - +/- signs for the package tree
   - jumps to line numbers on github (which are off because of changes after
the release)
   - some macro processing fixes (e.g. std.array.popBack contained some bad
HTML because of this)
   - also moved the authors/license sections to the bottom to see how it looks


I'm looking at this page:

http://vibed.org/temp/d-programming-language.org/phobos/std/net/isemail/EmailStatusCode.html

I think it would be better if there was more space for the Name column 
and let the Description column automatically wrap. It's better that the 
description uses multiple rows than the symbol names.

-- 
/Jacob Carlborg
Dec 23 2012
parent reply =?UTF-8?B?U8O2bmtlIEx1ZHdpZw==?= <sludwig outerproduct.org> writes:
Am 23.12.2012 14:58, schrieb Jacob Carlborg:

 I think it would be better if there was more space for the Name column and let
the Description
 column automatically wrap. It's better that the description uses multiple rows
than the symbol names.
 


I changed the first column from "width: 150pt;" to "min-width: 170pt". It can
still wrap, but the
two columns can now freely fight for the space if they need to.
Dec 23 2012
parent Jacob Carlborg <doob me.com> writes:
On 2012-12-23 20:55, Sönke Ludwig wrote:


 I changed the first column from "width: 150pt;" to "min-width: 170pt". It can
still wrap, but the
 two columns can now freely fight for the space if they need to.


Looks much better, thanks.

-- 
/Jacob Carlborg
Dec 24 2012
prev sibling parent reply =?UTF-8?B?U8O2bmtlIEx1ZHdpZw==?= <sludwig outerproduct.org> writes:
Am 22.12.2012 00:46, schrieb Andrei Alexandrescu:

 * But by very, very far the community-contributed stuff is just perfect. I
really really really hope
 we can get something like that integrated. There are many ways to approach
this:
 
 - By integrating a wiki page via e.g. an IFRAME.
 - By integrating with github
 - Through a separate custom layer (a la forum.dlang.org)
 - Whatever it is, we'd need some crowdsourcing (voting system etc) such that
good community notes go
 up and bad notes go down or get ultimately deleted.
 


I've integrated Disqus comments in the latest version.

e.g. http://vibed.org/temp/d-programming-language.org/phobos/std/algorithm/balancedParens.html
Dec 25 2012
parent r_m_r <r_m_r mailinator.com> writes:
On 12/25/2012 08:17 PM, Sönke Ludwig wrote:

 e.g. http://vibed.org/temp/d-programming-language.org/phobos/std/algorithm/balancedParens.html


Looks good!

BTW the link 
http://vibed.org/temp/d-programming-language.org/phobos/std/algorithm/b
yerMooreFinder.html 
gives a 404 error (linked from 
http://vibed.org/temp/d-programming-language.org/phobos/std/algorithm.html 
for the boyerMooreFinder Function). Interestingly, the std.algorithm 
page also links to 
http://vibed.org/temp/d-programming-language.org/phobos/std/algorithm/B
yerMooreFinder.html 
(BoyerMooreFinder Template) which works.

regards,
r_m_r
Dec 25 2012
prev sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2012-12-21 13:24, Sönke Ludwig wrote:


 Is any further work on this desired? If so, what would be the next steps to
integrate it into the
 general dlang.org workflow? (or rather, how is that workflow in terms of
folder structure, build
 scripts etc.?)

 It would also need a phase of bug fixing regarding some macros used in the
Phobos ddoc comments.


I think it would be really nice to have a list of all symbols with a 
filter, just like the Ruby docs have:

http://www.ruby-doc.org/core-1.9.3/

-- 
/Jacob Carlborg
Dec 22 2012
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/22/12 10:16 AM, Jacob Carlborg wrote:

 On 2012-12-21 13:24, Sönke Ludwig wrote:


 Is any further work on this desired? If so, what would be the next
 steps to integrate it into the
 general dlang.org workflow? (or rather, how is that workflow in terms
 of folder structure, build
 scripts etc.?)

 It would also need a phase of bug fixing regarding some macros used in
 the Phobos ddoc comments.


 I think it would be really nice to have a list of all symbols with a
 filter, just like the Ruby docs have:

 http://www.ruby-doc.org/core-1.9.3/


Looks great! I think that belongs in an index page (which doesn't exist 
yet, though we do define a sitemap http://dlang.org/sitemap.html).

Andrei
Dec 22 2012
parent Jacob Carlborg <doob me.com> writes:
On 2012-12-22 17:15, Andrei Alexandrescu wrote:


 Looks great! I think that belongs in an index page (which doesn't exist
 yet, though we do define a sitemap http://dlang.org/sitemap.html).


The sitemap is a bit different. The list of symbols could be the index 
page or a part of the index page for the reference documentation, that 
is, this page:

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

-- 
/Jacob Carlborg
Dec 23 2012
prev sibling parent reply Nick Sabalausky <SeeWebsiteToContactMe semitwist.com> writes:
On Sun, 09 Dec 2012 18:10:42 -0800
Ellery Newcomer <ellery-newcomer utulsa.edu> wrote:


 Is anyone else noticing e.g. std.datetime taking upwards of 30
 seconds to render the blob of links at the top? It's freakin freezing
 my entire browser.


It only takes about a second or two for me in FF2. I'm not seeing
any blob of links at the top though.
Dec 10 2012
parent reply "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Mon, Dec 10, 2012 at 12:34:13PM -0500, Nick Sabalausky wrote:

 On Sun, 09 Dec 2012 18:10:42 -0800
 Ellery Newcomer <ellery-newcomer utulsa.edu> wrote:
 

 Is anyone else noticing e.g. std.datetime taking upwards of 30
 seconds to render the blob of links at the top? It's freakin freezing
 my entire browser.


 
 It only takes about a second or two for me in FF2. I'm not seeing
 any blob of links at the top though.


'cos you're running with JS turned off. :-)

Also, I think the actual results depends on your system. If you have a
high-powered system you probably wouldn't notice too much lag. It "only"
takes about 3-4 seconds for me on a dual-core 3.4GHz Intel machine. But
older machines will probably see a bigger lag.

But anyway, I think all of this is kinda missing the point. The point is
that the blob of links at the top of the page is plain unhelpful. It is
only useful if you already know what you're looking for, in which case
you could just use your browser's search function to find the matching
text instead. Much more useful is a broken-down categorization (with
proper nesting, etc.) of the functions, classes, structs, etc., of the
module. Something like what std.algorithm does.


T

-- 
Perhaps the most widespread illusion is that if we were in power we
would behave very differently from those who now hold it---when, in
truth, in order to get power we would have to become very much like
them. -- Unknown
Dec 10 2012
parent reply Nick Sabalausky <SeeWebsiteToContactMe semitwist.com> writes:
On Mon, 10 Dec 2012 09:45:06 -0800
"H. S. Teoh" <hsteoh quickfur.ath.cx> wrote:


 On Mon, Dec 10, 2012 at 12:34:13PM -0500, Nick Sabalausky wrote:

 On Sun, 09 Dec 2012 18:10:42 -0800
 Ellery Newcomer <ellery-newcomer utulsa.edu> wrote:
 

 Is anyone else noticing e.g. std.datetime taking upwards of 30
 seconds to render the blob of links at the top? It's freakin
 freezing my entire browser.


 
 It only takes about a second or two for me in FF2. I'm not seeing
 any blob of links at the top though.


 
 'cos you're running with JS turned off. :-)
 


<g>

It makes the web 10x faster, 10x more practical and 10x less
obnoxious - it's the "Make the web instantly better" checkbox ;) It's
almost magical!


 Also, I think the actual results depends on your system. If you have a
 high-powered system you probably wouldn't notice too much lag. It
 "only" takes about 3-4 seconds for me on a dual-core 3.4GHz Intel
 machine. But older machines will probably see a bigger lag.
 


Yea, at the same time though, if it takes a dual-core 3.4GHz (with
two levels of cache, out-of-order execution, pipelineing, branch
prediction, SIMD, external GPU, etc) 3-4 seconds to render a few pages
of formatted text, then something in computing has gone very, very
wrong.


 But anyway, I think all of this is kinda missing the point. The point
 is that the blob of links at the top of the page is plain unhelpful.
 It is only useful if you already know what you're looking for, in
 which case you could just use your browser's search function to find
 the matching text instead. Much more useful is a broken-down
 categorization (with proper nesting, etc.) of the functions, classes,
 structs, etc., of the module. Something like what std.algorithm does.
 


Looking at it with JS on, yea, I see what you mean now. Not so nice,
not so helpful, and definitely not worth the rendering lag. The
new-style baked-in summaries on pages like std.algorithm are much, much
better.
Dec 10 2012
parent reply "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Mon, Dec 10, 2012 at 01:58:30PM -0500, Nick Sabalausky wrote:

 On Mon, 10 Dec 2012 09:45:06 -0800
 "H. S. Teoh" <hsteoh quickfur.ath.cx> wrote:
 

 On Mon, Dec 10, 2012 at 12:34:13PM -0500, Nick Sabalausky wrote:

 On Sun, 09 Dec 2012 18:10:42 -0800
 Ellery Newcomer <ellery-newcomer utulsa.edu> wrote:
 

 Is anyone else noticing e.g. std.datetime taking upwards of 30
 seconds to render the blob of links at the top? It's freakin
 freezing my entire browser.


 
 It only takes about a second or two for me in FF2. I'm not seeing
 any blob of links at the top though.


 
 'cos you're running with JS turned off. :-)
 


 
 <g>
 
 It makes the web 10x faster, 10x more practical and 10x less
 obnoxious - it's the "Make the web instantly better" checkbox ;) It's
 almost magical!


Heh. I used to browse with no JS. But due to the annoying bandwagon
jumping trend that is a common pathology in people involved with
computers, more and more websites are starting to depend on JS and are
mostly (or completely) dysfunctional without JS. So I grudgingly turned
it back on.

Mind you, though, what with browser bloat and JS memory hogging plaguing
my browsing experience recently, I've tentatively switched back to no JS
by default, and enable only on a per-site basis (Opera is good for that
kinda thing). There have been websites that outright crash my browser or
soak up all available RAM and then some (causing the browser to be 99%
I/O bound and the pig which is X11 to essentially grind to a halt), and
then I ban JS for that site, and boom, it's instantly better. Just like
you said. :-P



 Also, I think the actual results depends on your system. If you have
 a high-powered system you probably wouldn't notice too much lag. It
 "only" takes about 3-4 seconds for me on a dual-core 3.4GHz Intel
 machine. But older machines will probably see a bigger lag.
 


 
 Yea, at the same time though, if it takes a dual-core 3.4GHz (with
 two levels of cache, out-of-order execution, pipelineing, branch
 prediction, SIMD, external GPU, etc) 3-4 seconds to render a few pages
 of formatted text, then something in computing has gone very, very
 wrong.


I said the same thing when Java first came out, and the earlier JVMs
used to gobble up 2GB of RAM and 99% CPU upon startup, all just to
display a "hello world" message. :-)



 But anyway, I think all of this is kinda missing the point. The
 point is that the blob of links at the top of the page is plain
 unhelpful.  It is only useful if you already know what you're
 looking for, in which case you could just use your browser's search
 function to find the matching text instead. Much more useful is a
 broken-down categorization (with proper nesting, etc.) of the
 functions, classes, structs, etc., of the module. Something like
 what std.algorithm does.


 
 Looking at it with JS on, yea, I see what you mean now. Not so nice,
 not so helpful, and definitely not worth the rendering lag. The
 new-style baked-in summaries on pages like std.algorithm are much,
 much better.


I would go so far as to propose that we get rid of those unhelpful link
blobs completely. They make the page slow to load, and for no real
benefit. Sounds like a lose-lose proposition to me. But I'd probably get
lynched for saying that. :-P


T

-- 
English has the lovely word "defenestrate", meaning "to execute by
throwing someone out a window", or more recently "to remove Windows from
a computer and replace it with something useful". :-) -- John Cowan
Dec 10 2012
parent reply Nick Sabalausky <SeeWebsiteToContactMe semitwist.com> writes:
On Mon, 10 Dec 2012 12:57:43 -0800
"H. S. Teoh" <hsteoh quickfur.ath.cx> wrote:


 On Mon, Dec 10, 2012 at 01:58:30PM -0500, Nick Sabalausky wrote:

 On Mon, 10 Dec 2012 09:45:06 -0800
 "H. S. Teoh" <hsteoh quickfur.ath.cx> wrote:

 
 'cos you're running with JS turned off. :-)
 


 
 <g>
 
 It makes the web 10x faster, 10x more practical and 10x less
 obnoxious - it's the "Make the web instantly better" checkbox ;)
 It's almost magical!


 
 Heh. I used to browse with no JS. But due to the annoying bandwagon
 jumping trend that is a common pathology in people involved with
 computers,


Very well-put :) I've long been convinced that most people in computers
should be exiled from the industry and sent to the fashion industry
instead, because clearly that's where they truly belong. Too damn many
fashion-folk in computing these days.


 more and more websites are starting to depend on JS and are
 mostly (or completely) dysfunctional without JS. So I grudgingly
 turned it back on.
 


Usually if something doesn't work without JS, or on FF2, then I decide
that it isn't worth my attention anyway (and it usually isn't) and I
leave. In the rare cases when I do unfortunately need to use the site
(ex: BitBucket and GitHub), then I suffer through Opera 10 (the last
version of Opera, and indeed the last major web browser period, to
support a vaguely-native skin).

On a related note, Chrome will never touch my computer.


 Mind you, though, what with browser bloat and JS memory hogging
 plaguing my browsing experience recently, I've tentatively switched
 back to no JS by default, and enable only on a per-site basis (Opera
 is good for that kinda thing).


FF's NoScript plug-in is fantastic for that.


 Looking at it with JS on, yea, I see what you mean now. Not so nice,
 not so helpful, and definitely not worth the rendering lag. The
 new-style baked-in summaries on pages like std.algorithm are much,
 much better.


 
 I would go so far as to propose that we get rid of those unhelpful
 link blobs completely. They make the page slow to load, and for no
 real benefit. Sounds like a lose-lose proposition to me.


vote++
Dec 10 2012
parent "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Mon, Dec 10, 2012 at 04:54:43PM -0500, Nick Sabalausky wrote:

 On Mon, 10 Dec 2012 12:57:43 -0800
 "H. S. Teoh" <hsteoh quickfur.ath.cx> wrote:


[...]

 Heh. I used to browse with no JS. But due to the annoying bandwagon
 jumping trend that is a common pathology in people involved with
 computers,


 
 Very well-put :) I've long been convinced that most people in
 computers should be exiled from the industry and sent to the fashion
 industry instead, because clearly that's where they truly belong. Too
 damn many fashion-folk in computing these days.
 

 more and more websites are starting to depend on JS and are mostly
 (or completely) dysfunctional without JS. So I grudgingly turned it
 back on.
 


 
 Usually if something doesn't work without JS, or on FF2, then I decide
 that it isn't worth my attention anyway (and it usually isn't) and I
 leave. In the rare cases when I do unfortunately need to use the site
 (ex: BitBucket and GitHub), then I suffer through Opera 10 (the last
 version of Opera, and indeed the last major web browser period, to
 support a vaguely-native skin).


[...]

I don't have a problem with websites that use JS *when it's needed*, and
*to the extent it's needed*. The problem is, many sites use JS
needlessly.  And sites that do need JS use it *relentlessly*, beyond
necessity. Just because they need JS for *some* particular feature, they
decide to go all-out and use JS for *everything*, making things that
don't technically need JS, not work without it. Worse, some use JS
maliciously, like to repeatedly load an ad-related link in the
background to spam their click through count (or whatever it is these
days that people are obsessed with). Or soak up memory like water for no
apparent purpose, just because they can.


T

-- 
Debugging is twice as hard as writing the code in the first place.
Therefore, if you write the code as cleverly as possible, you are, by
definition, not smart enough to debug it. -- Brian W. Kernighan
Dec 11 2012