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 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 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 =?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 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 =?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
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 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 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 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 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 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 next sibling 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 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


 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 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 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 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 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
prev sibling next sibling 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 =?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 =?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 =?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 =?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 next 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
next sibling parent "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
prev sibling 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
prev sibling next sibling parent "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
prev sibling next sibling parent 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
prev sibling next sibling parent 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
prev sibling next sibling parent 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
prev sibling next sibling parent "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
prev sibling next sibling parent "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
prev sibling next sibling 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 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
prev sibling next sibling parent "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
prev sibling next sibling parent "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
prev sibling next sibling 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 "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 "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
prev sibling next sibling parent "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
prev sibling next sibling parent "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
prev sibling next sibling 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 next sibling parent "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
prev sibling next sibling parent "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
prev sibling next 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 next sibling parent "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
prev sibling next sibling parent "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
prev sibling next sibling parent Philippe Sigaud <philippe.sigaud gmail.com> writes:
--0016e6d285b46de86604d18213a1
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

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.

--0016e6d285b46de86604d18213a1
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

Very nice-looking docs S=C3=B6nke!<div><br></div><div>A minor nitpick: in s=
ome modules, the _-prefixed version appears as such (I mean, with an unders=
core before the name). See for example:</div><div><div><br></div><div>=C2=
=A0<a href=3D"http://vibed.org/temp/d-programming-language.org/phobos/std/p=
arallelism.html">http://vibed.org/temp/d-programming-language.org/phobos/st=
d/parallelism.html</a></div>
<div><br></div><div>Where std.parallelism appears as `std._parallelism` in =
the intro text.</div><div><br></div><div><br></div></div>

--0016e6d285b46de86604d18213a1--
Dec 23 2012
prev sibling next sibling parent "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
prev sibling next sibling parent "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
prev sibling next sibling parent "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
prev sibling next sibling parent "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
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