www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - ddox-generated Phobos documentation is available for review

reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
Consider it alpha quality. Please don't announce yet before we put it in 
good shape.

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

http://dlang.org/library

http://dlang.org/library-prerelease

I needed to change quite a bit about the makefile. It was building 
everything over and over again, and it's _slow_.

Some functions are not ready, compare e.g.

http://dlang.org/library/std/algorithm/balancedParens.html

with

http://dlang.org/library/std/algorithm/any.html


Andrei
Mar 09 2014
next sibling parent "Rikki Cattermole" <alphaglosined gmail.com> writes:
I have to say its looking good.
Although it does show just how much we need to break things up 
and make it a little bit more organised. Great example is the 
digest modules.
Mar 09 2014
prev sibling next sibling parent "Suliman" <evermind live.ru> writes:
I very like how Tango docs organized 
http://www.dsource.org/projects/tango/docs/stable/
Also good example how docs organized http://devdocs.io
Mar 09 2014
prev sibling next sibling parent "Brad Anderson" <eco gnuk.net> writes:
On Monday, 10 March 2014 at 03:44:54 UTC, Andrei Alexandrescu
wrote:
 Consider it alpha quality. Please don't announce yet before we 
 put it in good shape.

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

 http://dlang.org/library

 http://dlang.org/library-prerelease

 I needed to change quite a bit about the makefile. It was 
 building everything over and over again, and it's _slow_.

 Some functions are not ready, compare e.g.

 http://dlang.org/library/std/algorithm/balancedParens.html

 with

 http://dlang.org/library/std/algorithm/any.html


 Andrei

Huge improvement in a lot of ways. Thanks Sönke and Andrei.
Mar 09 2014
prev sibling next sibling parent "Philpax" <phillip philliplarkson.com> writes:
Fantastic! The organization makes it easy to find the right tool 
for the job.

This is probably nitpicking, but in std.algorithm and other 
modules ( http://dlang.org/library/std/algorithm.html ) there are 
multiple overloads of the same function (splitter, reverse, etc); 
it'd be nice if these could be organized into their own 
sub-categories, so there's no unnecessary visual redundancy.

There's also the library list which displays all modules; do the 
internal modules (druntime, etc) need to be exposed? It might be 
nicer for the end-user for these to be hidden, or kept in their 
own category.

Otherwise, very nice! :)
Mar 10 2014
prev sibling next sibling parent "Peter Alexander" <peter.alexander.au gmail.com> writes:
On Monday, 10 March 2014 at 03:44:54 UTC, Andrei Alexandrescu 
wrote:
 http://dlang.org/library

Looking good! The module list current shows deeply nested modules (e.g. std.c.stdio) before less nested ones (std.stdio). I think it should be the other way round, otherwise you have all the std.c.* modules listed first.
Mar 10 2014
prev sibling next sibling parent Dmitry Olshansky <dmitry.olsh gmail.com> writes:
10-Mar-2014 07:44, Andrei Alexandrescu пишет:
 Consider it alpha quality. Please don't announce yet before we put it in
 good shape.

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

 http://dlang.org/library

 http://dlang.org/library-prerelease

 I needed to change quite a bit about the makefile. It was building
 everything over and over again, and it's _slow_.

 Some functions are not ready, compare e.g.

 http://dlang.org/library/std/algorithm/balancedParens.html

 with

 http://dlang.org/library/std/algorithm/any.html


 Andrei

The front page shouldn't contain std.internal.* stuff and we probably need to adjust DDocs so that all modules have proper blurb text. -- Dmitry Olshansky
Mar 10 2014
prev sibling next sibling parent reply "Nicolas Sicard" <dransic gmail.com> writes:
On Monday, 10 March 2014 at 03:44:54 UTC, Andrei Alexandrescu 
wrote:
 Consider it alpha quality. Please don't announce yet before we 
 put it in good shape.

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

 http://dlang.org/library

 http://dlang.org/library-prerelease

 I needed to change quite a bit about the makefile. It was 
 building everything over and over again, and it's _slow_.

 Some functions are not ready, compare e.g.

 http://dlang.org/library/std/algorithm/balancedParens.html

 with

 http://dlang.org/library/std/algorithm/any.html


 Andrei

For me it's a real improvement! One thing: symbol names (modules, functions, etc.) shouldn't be hyphenated, specially in tables. Nicolas
Mar 10 2014
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 3/10/14, 1:35 AM, Nicolas Sicard wrote:
 For me it's a real improvement! One thing: symbol names (modules,
 functions, etc.) shouldn't be hyphenated, specially in tables.

All: how does one turn off css hyphenation? Andrei
Mar 10 2014
parent reply Martin Nowak <code+news.digitalmars dawg.eu> writes:
On 03/10/2014 03:56 PM, Andrei Alexandrescu wrote:
 All: how does one turn off css hyphenation?

 Andrei

You're again using that crappy JS hyphenation? Last time we had a performance problem with it, I wrote this super efficient D library http://code.dlang.org/packages/hyphenate. It could easily be hooked up with ddox or if someone has time for that wire it up with gumbo to postprocess HTML files (https://github.com/MartinNowak/hyphenate/issues/1).
Dec 11 2014
parent Martin Nowak <code+news.digitalmars dawg.eu> writes:
On 12/12/2014 02:05 AM, Martin Nowak wrote:

You're again using that crappy JS hyphenation?

No, you don't it's css hyphenation. Sorry for the tone.
Dec 11 2014
prev sibling next sibling parent "John Colvin" <john.loughran.colvin gmail.com> writes:
On Monday, 10 March 2014 at 03:44:54 UTC, Andrei Alexandrescu 
wrote:
 Consider it alpha quality. Please don't announce yet before we 
 put it in good shape.

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

 http://dlang.org/library

 http://dlang.org/library-prerelease

 I needed to change quite a bit about the makefile. It was 
 building everything over and over again, and it's _slow_.

 Some functions are not ready, compare e.g.

 http://dlang.org/library/std/algorithm/balancedParens.html

 with

 http://dlang.org/library/std/algorithm/any.html


 Andrei

Nice, but those duplicates have got to go!
Mar 10 2014
prev sibling next sibling parent "Jonas Drewsen" <nospam4321 hotmail.com > writes:
Very nice!

std.algorithm, std.net.curl etc. have their functions/classes 
split in categories.

I haven't used ddox myself but would it be possible to modify it 
to read a "category" variable in the documentation for a function 
and then use that to group things in the resulting html file?

Or would that need modifications to dmd itself.

/Jonas
Mar 10 2014
prev sibling next sibling parent "Steven Schveighoffer" <schveiguy yahoo.com> writes:
On Sun, 09 Mar 2014 23:44:43 -0400, Andrei Alexandrescu  
<SeeWebsiteForEmail erdani.org> wrote:

 Consider it alpha quality. Please don't announce yet before we put it in  
 good shape.

I LOVE this. Been waiting for it for a long time. The cross-links themselves are worth the wait. Just look at how organized std.datetime has become! Now, one nitpick -- I would like to see leaf links expand locally instead of opening a new page. Perhaps you can click on the link, and it opens a new page, but have a + button to expand in-line if desired. Essentially, the disruption of going to a new page when looking at the details of a function, I feel is too much. And look at that, disqus comments! -Steve
Mar 10 2014
prev sibling next sibling parent reply "Dicebot" <public dicebot.lv> writes:
On Monday, 10 March 2014 at 03:44:54 UTC, Andrei Alexandrescu 
wrote:
 Consider it alpha quality. Please don't announce yet before we 
 put it in good shape.

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

 http://dlang.org/library

 http://dlang.org/library-prerelease

 I needed to change quite a bit about the makefile. It was 
 building everything over and over again, and it's _slow_.

 Some functions are not ready, compare e.g.

 http://dlang.org/library/std/algorithm/balancedParens.html

 with

 http://dlang.org/library/std/algorithm/any.html


 Andrei

I still don't like disqus :) Documentation in general may probably benefit from some styling tweaks - for example, std.alogrithm looks funny when manually crafted tables turn into usual generated function list. But overall look solid.
Mar 10 2014
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 3/10/14, 7:00 AM, Dicebot wrote:
 I still don't like disqus :)

Are there better such systems available?
 Documentation in general may probably benefit from some styling tweaks -
 for example, std.alogrithm looks funny when manually crafted tables turn
 into usual generated function list. But overall look solid.

Yah, we need a solid community effort on this all. Please file issues appropriately, and hopefully fix others directly. Folks, this is the long tail. Please help us improve our documentation. Andrei
Mar 10 2014
parent reply Nick Sabalausky <SeeWebsiteToContactMe semitwist.com> writes:
On 3/10/2014 11:08 AM, Andrei Alexandrescu wrote:
 On 3/10/14, 7:00 AM, Dicebot wrote:
 I still don't like disqus :)

Are there better such systems available?

Yea, forum.dlang.org ;) And anything else that doesn't completely and totally break without JS.
Mar 10 2014
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 3/10/14, 3:28 PM, Nick Sabalausky wrote:
 On 3/10/2014 11:08 AM, Andrei Alexandrescu wrote:
 On 3/10/14, 7:00 AM, Dicebot wrote:
 I still don't like disqus :)

Are there better such systems available?

Yea, forum.dlang.org ;) And anything else that doesn't completely and totally break without JS.

Well forum.dlang.org has quite a different charter doesn't it? Also it lacks a very basic feature that I asked for in vain: a flat list of messages sorted by date posted, most recent. It would be the one thing that would make it comparable to the NNTP I use. Andrei
Mar 10 2014
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 3/10/14, 4:04 PM, Vladimir Panteleev wrote:
 It's still on my list... sorry it's taking this long. You're the only
 one who requested this feature, though. I can think of several
 improvements (some of which are in the pipeline) which I think would be
 more useful to the community overall, but if you think this is important
 I can bump it higher :)

Karma eh :o). Andrei
Mar 10 2014
prev sibling next sibling parent reply "Mike" <none none.com> writes:
Thank you, to everone who worked on this.  It's quite an 
improvement.

Problem:
http://dlang.org/library/std/compiler/vendor.html is a 404

Recommendation:
I really liked the immediate link to the source file on github in 
the old layout.  If possible please add it to the new layout.

Mike
Mar 10 2014
parent =?UTF-8?B?U8O2bmtlIEx1ZHdpZw==?= <sludwig+dforum outerproduct.org> writes:
Am 10.03.2014 15:11, schrieb Vladimir Panteleev:
 On Monday, 10 March 2014 at 14:08:07 UTC, Mike wrote:
 Thank you, to everone who worked on this.  It's quite an improvement.

 Problem:
 http://dlang.org/library/std/compiler/vendor.html is a 404

 Recommendation:
 I really liked the immediate link to the source file on github in the
 old layout.  If possible please add it to the new layout.

Since (IIRC) DDox parses JSON layout, I think it is capable of generating exact links to the file:line of each symbol. That would be neat, as it allows quickly seeing the implementation if the documentation is not sufficient.

It's actually already there - at the top of each page, there is a "View source code" button that goes to the proper file/line and to the proper branch/tag. I've used the same style as the already existing buttons, but those are indeed not very noticeable on the right side of the page. Any suggestions for a better place/style without visually cluttering up the actual documentation?
Mar 10 2014
prev sibling next sibling parent "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Monday, 10 March 2014 at 14:08:07 UTC, Mike wrote:
 Thank you, to everone who worked on this.  It's quite an 
 improvement.

 Problem:
 http://dlang.org/library/std/compiler/vendor.html is a 404

 Recommendation:
 I really liked the immediate link to the source file on github 
 in the old layout.  If possible please add it to the new layout.

Since (IIRC) DDox parses JSON layout, I think it is capable of generating exact links to the file:line of each symbol. That would be neat, as it allows quickly seeing the implementation if the documentation is not sufficient.
Mar 10 2014
prev sibling next sibling parent "ralex" <krckoorascic gmail.com> writes:
On Monday, 10 March 2014 at 14:56:13 UTC, Andrei Alexandrescu 
wrote:
 On 3/10/14, 1:35 AM, Nicolas Sicard wrote:
 For me it's a real improvement! One thing: symbol names 
 (modules,
 functions, etc.) shouldn't be hyphenated, specially in tables.

All: how does one turn off css hyphenation? Andrei

word-wrap: break-word; -webkit-hypens: none; -moz-hypens: none; -ms-hypens: none; hypens: none; should do the trick..
Mar 10 2014
prev sibling next sibling parent "Brad Anderson" <eco gnuk.net> writes:
On Monday, 10 March 2014 at 14:56:13 UTC, Andrei Alexandrescu 
wrote:
 On 3/10/14, 1:35 AM, Nicolas Sicard wrote:
 For me it's a real improvement! One thing: symbol names 
 (modules,
 functions, etc.) shouldn't be hyphenated, specially in tables.

All: how does one turn off css hyphenation? Andrei

class="donthyphenate"
Mar 10 2014
prev sibling next sibling parent "Brad Anderson" <eco gnuk.net> writes:
On Monday, 10 March 2014 at 14:11:06 UTC, Vladimir Panteleev 
wrote:
 On Monday, 10 March 2014 at 14:08:07 UTC, Mike wrote:
 Thank you, to everone who worked on this.  It's quite an 
 improvement.

 Problem:
 http://dlang.org/library/std/compiler/vendor.html is a 404

 Recommendation:
 I really liked the immediate link to the source file on github 
 in the old layout.  If possible please add it to the new 
 layout.

Since (IIRC) DDox parses JSON layout, I think it is capable of generating exact links to the file:line of each symbol. That would be neat, as it allows quickly seeing the implementation if the documentation is not sufficient.

I wanted to do just this so I considered adding a predefined macro to ddoc to get line numbers like I did to get filenames (I needed SRCFILENAME to add the Improve This Page button) but the line numbers would pretty quickly lose sync between master and the documentation so that would also require integrating the release tag into the documentation somehow so I gave up on that idea.
Mar 10 2014
prev sibling next sibling parent "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Monday, 10 March 2014 at 16:54:37 UTC, Brad Anderson wrote:
 On Monday, 10 March 2014 at 14:11:06 UTC, Vladimir Panteleev 
 wrote:
 On Monday, 10 March 2014 at 14:08:07 UTC, Mike wrote:
 Thank you, to everone who worked on this.  It's quite an 
 improvement.

 Problem:
 http://dlang.org/library/std/compiler/vendor.html is a 404

 Recommendation:
 I really liked the immediate link to the source file on 
 github in the old layout.  If possible please add it to the 
 new layout.

Since (IIRC) DDox parses JSON layout, I think it is capable of generating exact links to the file:line of each symbol. That would be neat, as it allows quickly seeing the implementation if the documentation is not sufficient.

I wanted to do just this so I considered adding a predefined macro to ddoc to get line numbers like I did to get filenames (I needed SRCFILENAME to add the Improve This Page button) but the line numbers would pretty quickly lose sync between master and the documentation so that would also require integrating the release tag into the documentation somehow so I gave up on that idea.

So... don't link to master? The dmd repo has a VERSION file. Can that be used to link to the respective tag instead?
Mar 10 2014
prev sibling next sibling parent "Brad Anderson" <eco gnuk.net> writes:
On Monday, 10 March 2014 at 16:58:45 UTC, Vladimir Panteleev 
wrote:
 On Monday, 10 March 2014 at 16:54:37 UTC, Brad Anderson wrote:
 I wanted to do just this so I considered adding a predefined 
 macro to ddoc to get line numbers like I did to get filenames 
 (I needed SRCFILENAME to add the Improve This Page button) but 
 the line numbers would pretty quickly lose sync between master 
 and the documentation so that would also require integrating 
 the release tag into the documentation somehow so I gave up on 
 that idea.

So... don't link to master? The dmd repo has a VERSION file. Can that be used to link to the respective tag instead?

I'm not sure how ddox works but I suspect that wouldn't be terrible difficult to integrate. Doing it with ddoc would require something like copying the value from VERSION into a macro within std.ddoc using the html make target. Not terribly difficult but now that we are switching to ddox we might as well do it using ddox where line information is already easily accessible.
Mar 10 2014
prev sibling next sibling parent "w0rp" <devw0rp gmail.com> writes:
The documentation is looking very good, good work to all 
involved. There are a few bugs here and there. Appender's docs 
were missing, some runtime modules are in there which should 
maybe be hidden. Still, this is a massive improvement, and I love 
it.
Mar 10 2014
prev sibling next sibling parent "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Monday, 10 March 2014 at 18:56:41 UTC, Sönke Ludwig wrote:
 Am 10.03.2014 15:11, schrieb Vladimir Panteleev:
 On Monday, 10 March 2014 at 14:08:07 UTC, Mike wrote:
 Thank you, to everone who worked on this.  It's quite an 
 improvement.

 Problem:
 http://dlang.org/library/std/compiler/vendor.html is a 404

 Recommendation:
 I really liked the immediate link to the source file on 
 github in the
 old layout.  If possible please add it to the new layout.

Since (IIRC) DDox parses JSON layout, I think it is capable of generating exact links to the file:line of each symbol. That would be neat, as it allows quickly seeing the implementation if the documentation is not sufficient.

It's actually already there - at the top of each page, there is a "View source code" button that goes to the proper file/line and to the proper branch/tag.

Ah, that's great. I think it's fine as it is, we just didn't expect it to be there already.
Mar 10 2014
prev sibling next sibling parent "Mike" <none none.com> writes:
On Monday, 10 March 2014 at 18:56:41 UTC, Sönke Ludwig wrote:
 It's actually already there - at the top of each page, there is 
 a "View source code" button that goes to the proper file/line 
 and to the proper branch/tag. I've used the same style as the 
 already existing buttons, but those are indeed not very 
 noticeable on the right side of the page.

Oops. My mistake. I'm happy with it the way it is.
Mar 10 2014
prev sibling next sibling parent "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Monday, 10 March 2014 at 22:28:11 UTC, Nick Sabalausky wrote:
 On 3/10/2014 11:08 AM, Andrei Alexandrescu wrote:
 On 3/10/14, 7:00 AM, Dicebot wrote:
 I still don't like disqus :)

Are there better such systems available?

Yea, forum.dlang.org ;) And anything else that doesn't completely and totally break without JS.

A possible plan for forum.dlang.org integration: 1. Walter and Brad create a new newsgroup and mailing list specifically for doc comments. 2. We have one thread per documentation page. 3. The relevant thread is displayed on each page via an iframe or a JS snippet (with a noscript iframe fallback). Downsides: - Requires implementation effort, whereas Disqus is already there. - Limited moderation support (although I don't imagine the problem to be worse than now, and there is still room for improvement with the current one). - No formatting. - No voting. - (More Disqus advantages I forgot? I think the previous thread had a few more.) Benefits: - We hold all data ourselves. If disaster strikes, the code is open-source, I have backups, and Walter and Andrei have SSH access. - No JavaScript required. - Forum, newsgroup and mailing list integration allows volunteers to easily subscribe to new comments, and answer questions as they are posted. As DFeed is also an IRC client, IRC notifications are also possible. - As the code is open-source, we can implement features that are present in Disqus, or even features that Disqus doesn't have. - Subjective, but hopefully we can come up with a less cluttered interface. There's lots of elements which I think are undesirable: "Share", "Favorite", the "vibe.d" link (what's that for?), "Subscribe", "Add Disqus to your site", the "Disqus" logo, "comments powered by Disqus".
Mar 10 2014
prev sibling next sibling parent "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Monday, 10 March 2014 at 22:56:04 UTC, Andrei Alexandrescu 
wrote:
 On 3/10/14, 3:28 PM, Nick Sabalausky wrote:
 On 3/10/2014 11:08 AM, Andrei Alexandrescu wrote:
 On 3/10/14, 7:00 AM, Dicebot wrote:
 I still don't like disqus :)

Are there better such systems available?

Yea, forum.dlang.org ;) And anything else that doesn't completely and totally break without JS.

Well forum.dlang.org has quite a different charter doesn't it? Also it lacks a very basic feature that I asked for in vain: a flat list of messages sorted by date posted, most recent. It would be the one thing that would make it comparable to the NNTP I use.

It's still on my list... sorry it's taking this long. You're the only one who requested this feature, though. I can think of several improvements (some of which are in the pipeline) which I think would be more useful to the community overall, but if you think this is important I can bump it higher :)
Mar 10 2014
prev sibling next sibling parent Brad Roberts <braddr puremagic.com> writes:
A key required (imho) feature, the ability to edit after the fact.  The primary
value that I see in 
any sort of embedded user input feature is the the most streamlined way of
adding essentially bug 
reports about the page directly on the page.  Those reports should be acted
upon and the page itself 
updated after which the report dropped.  The same with the essentially
unmaintained wiki page that 
is linked to most of the dlang.org pages.

I'm concerned about it becoming yet another forum for discussion.  Yet another
place that needs to 
be monitored and maintained.  Something else that will grow stale.  Etc. 
There's certainly value, 
and I've seen the value on other sites that support per-page user comments. 
But there's a very real 
and very important cost that comes with it.

My 2 cents,
Brad
Mar 10 2014
prev sibling next sibling parent "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Monday, 10 March 2014 at 23:16:40 UTC, Brad Roberts wrote:
 A key required (imho) feature, the ability to edit after the 
 fact.  The primary value that I see in any sort of embedded 
 user input feature is the the most streamlined way of adding 
 essentially bug reports about the page directly on the page.  
 Those reports should be acted upon and the page itself updated 
 after which the report dropped.  The same with the essentially 
 unmaintained wiki page that is linked to most of the dlang.org 
 pages.

 I'm concerned about it becoming yet another forum for 
 discussion.  Yet another place that needs to be monitored and 
 maintained.  Something else that will grow stale.  Etc.  
 There's certainly value, and I've seen the value on other sites 
 that support per-page user comments.  But there's a very real 
 and very important cost that comes with it.

Any suggestions? Edit-ability precludes NNTP/mailing-list mirroring, unless some shims like sending edits as replies are used. I think that if we were to embed a wiki into the page directly, it would have be much less likely to bitrot due to higher visibility.
Mar 10 2014
prev sibling next sibling parent "Dicebot" <public dicebot.lv> writes:
On Monday, 10 March 2014 at 15:08:07 UTC, Andrei Alexandrescu 
wrote:
 On 3/10/14, 7:00 AM, Dicebot wrote:
 I still don't like disqus :)

Are there better such systems available?

I don't like the very concept of comments integrated with the docs and can't accept PHP example as authority. It just feels very intrusive wiki + stackoverflow + forum.dlang.org generate much more natural user documentation
Mar 11 2014
prev sibling next sibling parent reply "Ivan Kazmenko" <gassa mail.ru> writes:
 http://dlang.org/library

Looks nice! I second the opinion that Disqus might have a better alternative. Its loading after the page was rendered looks clumsy, its style does not match that of dlang.org's... the whole thing is somehow out of place. Ivan Kazmenko.
Mar 11 2014
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 3/11/14, 6:55 AM, Ivan Kazmenko wrote:
 http://dlang.org/library

Looks nice! I second the opinion that Disqus might have a better alternative. Its loading after the page was rendered looks clumsy, its style does not match that of dlang.org's... the whole thing is somehow out of place.

Unless something better comes about, we'll go with disqus. Sönke, are there styling options available? Andrei
Mar 11 2014
parent =?UTF-8?B?U8O2bmtlIEx1ZHdpZw==?= <sludwig+dforum outerproduct.org> writes:
Am 11.03.2014 16:12, schrieb Andrei Alexandrescu:
 On 3/11/14, 6:55 AM, Ivan Kazmenko wrote:
 http://dlang.org/library

Looks nice! I second the opinion that Disqus might have a better alternative. Its loading after the page was rendered looks clumsy, its style does not match that of dlang.org's... the whole thing is somehow out of place.

Unless something better comes about, we'll go with disqus. Sönke, are there styling options available? Andrei

AFAICT the only options are dark or bright background and serif or sans-serif font. I didn't find anything to control the area around the horizontal bar at the top of the comments section.
Mar 12 2014
prev sibling next sibling parent Matej Nanut <matejnanut gmail.com> writes:
--089e0102e6da2ae2f704f45516e8
Content-Type: text/plain; charset=UTF-8

On 11 March 2014 14:09, Dicebot <public dicebot.lv> wrote:

 On Monday, 10 March 2014 at 15:08:07 UTC, Andrei Alexandrescu wrote:

 On 3/10/14, 7:00 AM, Dicebot wrote:

 I still don't like disqus :)

Are there better such systems available?

I don't like the very concept of comments integrated with the docs and can't accept PHP example as authority. It just feels very intrusive wiki + stackoverflow + forum.dlang.org generate much more natural user documentation

A possible consequence is that people will simply stop improving the docs, because "workarounds" or extra explanations will be available in the comments. Something like this happens in the AngularJS documentation, for example. There, the docs can be incomplete or even out of date, so you have to look at the comments. Of course, if the docs are out of date regardless, this can be considered a good thing. --089e0102e6da2ae2f704f45516e8 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable <div dir=3D"ltr"><div class=3D"gmail_extra"><div class=3D"gmail_quote">On 1= 1 March 2014 14:09, Dicebot <span dir=3D"ltr">&lt;<a href=3D"mailto:public = dicebot.lv" target=3D"_blank">public dicebot.lv</a>&gt;</span> wrote:<br><b= lockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px = #ccc solid;padding-left:1ex"> <div class=3D"">On Monday, 10 March 2014 at 15:08:07 UTC, Andrei Alexandres= cu wrote:<br> <blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p= x #ccc solid;padding-left:1ex"> On 3/10/14, 7:00 AM, Dicebot wrote:<br> <blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p= x #ccc solid;padding-left:1ex"> I still don&#39;t like disqus :)<br> </blockquote> <br> Are there better such systems available?<br> </blockquote> <br></div> I don&#39;t like the very concept of comments integrated with the docs and = can&#39;t accept PHP example as authority. It just feels very intrusive<br> <br> wiki + stackoverflow + <a href=3D"http://forum.dlang.org" target=3D"_blank"=
forum.dlang.org</a> generate much more natural user documentation<br>

</blockquote></div><br></div><div class=3D"gmail_extra">I don&#39;t like do= c-integrated comments either.<br><br></div><div class=3D"gmail_extra">A pos= sible consequence is that people will simply stop improving the docs, becau= se &quot;workarounds&quot; or extra explanations will be available in the c= omments.<br> <br>Something like this happens in the AngularJS documentation, for example= . There, the docs can be incomplete or even out of date, so you have to loo= k at the comments.<br><br></div><div class=3D"gmail_extra">Of course, if th= e docs are out of date regardless, this can be considered a good thing.<br> </div></div> --089e0102e6da2ae2f704f45516e8--
Mar 11 2014
prev sibling next sibling parent Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
On 3/11/14, Dicebot <public dicebot.lv> wrote:
 I don't like the very concept of comments integrated with the
 docs and can't accept PHP example as authority. It just feels
 very intrusive

Yeah, at some point there will be so many comments on a single page that it defeats the purpose. Comments which are stale (e.g. because the docs were fixed since then) should be removed, they're visual noise otherwise. And disqus just like any other free online service is just a ticking time-bomb anyway. Pretty much all of these free online services die at some point.
Mar 11 2014
prev sibling next sibling parent "Steven Schveighoffer" <schveiguy yahoo.com> writes:
On Tue, 11 Mar 2014 11:12:51 -0400, Andrei Alexandrescu  =

<SeeWebsiteForEmail erdani.org> wrote:

 On 3/11/14, 6:55 AM, Ivan Kazmenko wrote:
 http://dlang.org/library

Looks nice! I second the opinion that Disqus might have a better alternative. Its=


 loading after the page was rendered looks clumsy, its style does not
 match that of dlang.org's... the whole thing is somehow out of place.=


 Unless something better comes about, we'll go with disqus. S=C3=B6nke,=

 there styling options available?

I want to stick my neck out and say that I love disqus *ducks*. But I = don't know that it's what we should use in this instance. Disqus is grea= t = when you are having a live debate. New posts get loaded in real-time, = votes are recorded in real-time, so it's very fluid. But in this case, I don't see any fierce debates occurring on doc pages.= = Probably simple notes or "useful tricks" is what will appear there. A = "live update" feature is pretty much overkill for such static discussion= . That being said, I've been on plenty of disqus sites, and they look = different, act different, but have the same general look and feel. An idea -- would it be possible to search links from the D forum, and po= st = underneath the discussions that link to that doc page? Then have some so= rt = of moderation so non-doc-related discussions don't clutter the page? May= be = even just first few sentences of the post, with a link to the D forum...= Then we don't have to have any kind of new interface for D posts, just a= = copy of what's already in discussion. -Steve
Mar 11 2014
prev sibling next sibling parent reply Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
On 3/10/14, Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> wrote:
 Consider it alpha quality. Please don't announce yet before we put it in
 good shape.

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

I think on pages where we provide a cheat-sheet like in std.algorithm it's probably a good idea to remove the auto-generated list of functions, because it's essentially a duplicated list (and the cheat-sheet is better because it's humanly organized): http://dlang.org/library/std/algorithm.html
Mar 11 2014
next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 3/11/14, 8:52 AM, Andrej Mitrovic wrote:
 On 3/10/14, Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> wrote:
 Consider it alpha quality. Please don't announce yet before we put it in
 good shape.

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

I think on pages where we provide a cheat-sheet like in std.algorithm it's probably a good idea to remove the auto-generated list of functions, because it's essentially a duplicated list (and the cheat-sheet is better because it's humanly organized): http://dlang.org/library/std/algorithm.html

Snke, can we make the list generation optional? Andrei
Mar 11 2014
prev sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2014-03-11 16:52, Andrej Mitrovic wrote:

 I think on pages where we provide a cheat-sheet like in std.algorithm
 it's probably a good idea to remove the auto-generated list of
 functions, because it's essentially a duplicated list (and the
 cheat-sheet is better because it's humanly organized):

 http://dlang.org/library/std/algorithm.html

The correct solution is making the automatically generated one as good as the manually. It shouldn't be hard to add a new Ddoc macro that is recognized and indicates which category a symbol belongs to. Something like: /// $(CATEGORY searching) void foo (); -- /Jacob Carlborg
Mar 11 2014
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 3/11/14, 10:38 AM, Jacob Carlborg wrote:
 On 2014-03-11 16:52, Andrej Mitrovic wrote:

 I think on pages where we provide a cheat-sheet like in std.algorithm
 it's probably a good idea to remove the auto-generated list of
 functions, because it's essentially a duplicated list (and the
 cheat-sheet is better because it's humanly organized):

 http://dlang.org/library/std/algorithm.html

The correct solution is making the automatically generated one as good as the manually. It shouldn't be hard to add a new Ddoc macro that is recognized and indicates which category a symbol belongs to. Something like: /// $(CATEGORY searching) void foo ();

Yes to that. I seem to recall we have something similar on the homepage. Could you please get something started to serve as a pattern to follow for all of us? Thanks, Andrei
Mar 11 2014
parent reply Jacob Carlborg <doob me.com> writes:
On 2014-03-11 19:03, Andrei Alexandrescu wrote:

 Yes to that. I seem to recall we have something similar on the homepage.

 Could you please get something started to serve as a pattern to follow
 for all of us?

Do you mean how to write Ddoc comments or implement the $(CATEGORY) macro? -- /Jacob Carlborg
Mar 11 2014
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 3/11/14, 12:08 PM, Jacob Carlborg wrote:
 On 2014-03-11 19:03, Andrei Alexandrescu wrote:

 Yes to that. I seem to recall we have something similar on the homepage.

 Could you please get something started to serve as a pattern to follow
 for all of us?

Do you mean how to write Ddoc comments or implement the $(CATEGORY) macro?

Implement the macro and show how it works in one place. Andrei
Mar 11 2014
prev sibling next sibling parent "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Tuesday, 11 March 2014 at 15:38:21 UTC, Steven Schveighoffer 
wrote:
 On Tue, 11 Mar 2014 11:12:51 -0400, Andrei Alexandrescu 
 <SeeWebsiteForEmail erdani.org> wrote:

 On 3/11/14, 6:55 AM, Ivan Kazmenko wrote:
 http://dlang.org/library

Looks nice! I second the opinion that Disqus might have a better alternative. Its loading after the page was rendered looks clumsy, its style does not match that of dlang.org's... the whole thing is somehow out of place.

Unless something better comes about, we'll go with disqus. Sönke, are there styling options available?

I want to stick my neck out and say that I love disqus *ducks*. But I don't know that it's what we should use in this instance. Disqus is great when you are having a live debate. New posts get loaded in real-time, votes are recorded in real-time, so it's very fluid. But in this case, I don't see any fierce debates occurring on doc pages. Probably simple notes or "useful tricks" is what will appear there. A "live update" feature is pretty much overkill for such static discussion. That being said, I've been on plenty of disqus sites, and they look different, act different, but have the same general look and feel. An idea -- would it be possible to search links from the D forum, and post underneath the discussions that link to that doc page? Then have some sort of moderation so non-doc-related discussions don't clutter the page? Maybe even just first few sentences of the post, with a link to the D forum... Then we don't have to have any kind of new interface for D posts, just a copy of what's already in discussion.

Sure, we could do that. Together with an "Ask a question about std.modulename.symbolname" link that goes to a partially pre-filled form ready to post to d.learn.
Mar 11 2014
prev sibling next sibling parent "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Monday, 10 March 2014 at 22:50:54 UTC, Vladimir Panteleev
wrote:
 On Monday, 10 March 2014 at 22:28:11 UTC, Nick Sabalausky wrote:
 On 3/10/2014 11:08 AM, Andrei Alexandrescu wrote:
 On 3/10/14, 7:00 AM, Dicebot wrote:
 I still don't like disqus :)

Are there better such systems available?

Yea, forum.dlang.org ;) And anything else that doesn't completely and totally break without JS.

A possible plan for forum.dlang.org integration:

BTW, as I understand, we can export data from Disqus any time, so there should be no pressure to decide on this right now.
Mar 11 2014
prev sibling next sibling parent "Steven Schveighoffer" <schveiguy yahoo.com> writes:
On Tue, 11 Mar 2014 13:41:23 -0400, Vladimir Panteleev  
<vladimir thecybershadow.net> wrote:

 On Tuesday, 11 March 2014 at 15:38:21 UTC, Steven Schveighoffer wrote:
 An idea -- would it be possible to search links from the D forum, and  
 post underneath the discussions that link to that doc page? Then have  
 some sort of moderation so non-doc-related discussions don't clutter  
 the page? Maybe even just first few sentences of the post, with a link  
 to the D forum...

 Then we don't have to have any kind of new interface for D posts, just  
 a copy of what's already in discussion.

Sure, we could do that. Together with an "Ask a question about std.modulename.symbolname" link that goes to a partially pre-filled form ready to post to d.learn.

Oh, excellent idea, even if we don't have the discussion cross-linked. -Steve
Mar 11 2014
prev sibling next sibling parent Piotr Szturmaj <bncrbme jadamspam.pl> writes:
W dniu 2014-03-10 04:44, Andrei Alexandrescu pisze:
 Consider it alpha quality. Please don't announce yet before we put it in
 good shape.

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

 http://dlang.org/library

Great! Altough, I would exchange title order to like "std.xxx module" or "someFn() function". Otherwise, identifier names in tabs may be visually cut out if you open many tabs.
Mar 11 2014
prev sibling parent reply "Tobias Pankrath" <tobias pankrath.net> writes:
On Monday, 10 March 2014 at 03:44:54 UTC, Andrei Alexandrescu 
wrote:
 Consider it alpha quality. Please don't announce yet before we 
 put it in good shape.

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

 http://dlang.org/library

 http://dlang.org/library-prerelease

 I needed to change quite a bit about the makefile. It was 
 building everything over and over again, and it's _slow_.

 Some functions are not ready, compare e.g.

 http://dlang.org/library/std/algorithm/balancedParens.html

 with

 http://dlang.org/library/std/algorithm/any.html


 Andrei

std.container.Array is shadowed by std.container.Array!bool. redBlackTree shadows RedBlackTree as well.
Dec 11 2014
parent Martin Nowak <code+news.digitalmars dawg.eu> writes:
On 12/11/2014 03:45 PM, Tobias Pankrath wrote:
 std.container.Array is shadowed by std.container.Array!bool.
 redBlackTree shadows RedBlackTree as well.

We fixed that issue already, please have a look at the preview. https://dlang.dawg.eu/library/index.html https://dlang.dawg.eu/library-prerelease/index.html
Dec 11 2014