digitalmars.D.announce - New (page-per-artifact) standard library doc examples are now
- Andrei Alexandrescu (5/5) Jan 07 2017 Following https://github.com/dlang/dlang.org/pull/1532, the new-style
- Martin Nowak (5/10) Jan 07 2017 Thanks, this is quite an amazing step towards more interactive
- Seb (10/21) Jan 07 2017 There's already some simple support for this in the ddoc pages,
- Yuxuan Shui (4/20) Feb 17 2017 Looks like the result is not always valid, see:
- Seb (18/24) Feb 16 2017 Short follow-up: this is now live for the released documentation
- Jack Stouffer (4/6) Feb 17 2017 Please make a post on Reddit!
- Seb (9/15) Feb 18 2017 Excellent idea!
- Mike Parker (4/12) Feb 18 2017 I'll do it. But before I do, I'll want to know that everything is
- Seb (13/28) Feb 21 2017 Thanks a lot!
- Seb (5/15) Feb 22 2017 Okay I just couldn't let this sit on myself. So I went ahead and
- Mike Parker (2/6) Feb 27 2017 So is everything working as advertised? Is it redditable?
- Seb (16/26) Feb 27 2017 Yes, thanks to a lot of support from CyberShadow [1] and
- David Nadlinger (5/7) Feb 27 2017 Can we fix the fact that the docs are duplicated for template
- Seb (11/20) Feb 27 2017 That's one of the disadvantages of running two documentation
- David Nadlinger (2/5) Feb 27 2017 Sure, linking only that would definitely work. — David
- Adam D. Ruppe (18/20) Feb 27 2017 What's up with the bullet point list at the top of the page? I'd
- Mike Parker (5/7) Feb 27 2017 I'm thinking it might be better to do a blog post about it and
- John Colvin (8/37) Feb 17 2017 Might I suggest you change the output
- bachmeier (2/9) Feb 17 2017 +1
- Seb (10/17) Feb 18 2017 Excellent idea! As the same js is used for the runnable boxes on
- bachmeier (2/7) Feb 23 2017 I like the first version in the screenshot (with a border).
- Dmitry Olshansky (5/10) Feb 17 2017 Broken on the first example I tried :(
- =?UTF-8?Q?S=c3=b6nke_Ludwig?= (4/14) Feb 18 2017 The example got cut off two or three characters too early, compared with...
- =?UTF-8?Q?S=c3=b6nke_Ludwig?= (3/20) Feb 18 2017 Hm, okay, false alert. The characters are there in the page sources and
- Seb (5/31) Feb 18 2017 Yeah the regex trick doesn't seem to work that well:
- Nick Sabalausky (Abscissa) (5/10) Feb 17 2017 1. This is pretty awesome.
- Seb (9/14) Feb 18 2017 Thanks a lot :)
- Nick Sabalausky (Abscissa) (36/48) Feb 18 2017 Dark system color scheme, nothing mucking with website CSSes or
- Nick Sabalausky (Abscissa) (3/10) Feb 18 2017 K, just tested it, works for me:
Following https://github.com/dlang/dlang.org/pull/1532, the new-style docs now also allow editing and running examples. Start at http://dlang.org/library-prerelease/ and go anywhere to check it out. Thanks are due to Sönke Ludwig and Sebastian Wilzbach! Andrei
Jan 07 2017
On 01/07/2017 05:12 PM, Andrei Alexandrescu wrote:Following https://github.com/dlang/dlang.org/pull/1532, the new-style docs now also allow editing and running examples. Start at http://dlang.org/library-prerelease/ and go anywhere to check it out. Thanks are due to Sönke Ludwig and Sebastian Wilzbach!Thanks, this is quite an amazing step towards more interactive documentation. Should we start to produce output as well, e.g. with some magic `writeln` that's silent in actual tests?
Jan 07 2017
On Saturday, 7 January 2017 at 20:14:56 UTC, Martin Nowak wrote:On 01/07/2017 05:12 PM, Andrei Alexandrescu wrote:There's already some simple support for this in the ddoc pages, e.g. the pattern `assert(a == b);` is automatically rewritten to `writeln(a); // b` https://dlang.org/phobos-prerelease/std_algorithm_searching.html#.minElement However as ddox produces a different output, it doesn't work at the moment with the ddox build. I made a PR: https://github.com/dlang/dlang.org/pull/1551 Of course help to make this smarter is welcome ;-)Following https://github.com/dlang/dlang.org/pull/1532, the new-style docs now also allow editing and running examples. Start at http://dlang.org/library-prerelease/ and go anywhere to check it out. Thanks are due to Sönke Ludwig and Sebastian Wilzbach!Thanks, this is quite an amazing step towards more interactive documentation. Should we start to produce output as well, e.g. with some magic `writeln` that's silent in actual tests?
Jan 07 2017
On Saturday, 7 January 2017 at 21:19:42 UTC, Seb wrote:On Saturday, 7 January 2017 at 20:14:56 UTC, Martin Nowak wrote:Looks like the result is not always valid, see: https://dlang.org/library/std/algorithm/searching/find.html Probably shouldn't use regex to parse context free grammar...On 01/07/2017 05:12 PM, Andrei Alexandrescu wrote:There's already some simple support for this in the ddoc pages, e.g. the pattern `assert(a == b);` is automatically rewritten to `writeln(a); // b`Following https://github.com/dlang/dlang.org/pull/1532, the new-style docs now also allow editing and running examples. Start at http://dlang.org/library-prerelease/ and go anywhere to check it out. Thanks are due to Sönke Ludwig and Sebastian Wilzbach!Thanks, this is quite an amazing step towards more interactive documentation. Should we start to produce output as well, e.g. with some magic `writeln` that's silent in actual tests?
Feb 17 2017
On Saturday, 7 January 2017 at 16:12:49 UTC, Andrei Alexandrescu wrote:Following https://github.com/dlang/dlang.org/pull/1532, the new-style docs now also allow editing and running examples. Start at http://dlang.org/library-prerelease/ and go anywhere to check it out. Thanks are due to Sönke Ludwig and Sebastian Wilzbach! AndreiShort follow-up: this is now live for the released documentation pages. Enjoy! Ddoc: https://dlang.org/phobos/std_algorithm_comparison.html#among Ddox: https://dlang.org/library/std/algorithm/comparison/among.html Your feedback is of course welcome. A couple of modules are still blacklisted, but it's WIP to remove the blacklist [1]. Also as mentioned DPaste [2] is used as Backend. If you want to hack with it directly, you may have a look at [3]. Cheers, Seb [1] https://github.com/dlang/phobos/pull/5142 [2] https://dlang.org/blog/2017/01/30/project-highlight-dpaste/ [3] https://github.com/dlang/dlang.org/blob/master/js/run_examples.js
Feb 16 2017
On Friday, 17 February 2017 at 05:06:20 UTC, Seb wrote:Short follow-up: this is now live for the released documentation pages. Enjoy!Please make a post on Reddit! I firmly believe that this puts D at the top of programming language docs. We should advertise!
Feb 17 2017
On Friday, 17 February 2017 at 08:00:29 UTC, Jack Stouffer wrote:On Friday, 17 February 2017 at 05:06:20 UTC, Seb wrote:Excellent idea! AFAIK reddit doesn't like self posts that much. Would someone be so kind to post this once the improvements are in? https://github.com/dlang/dlang.org/pull/1575 (this PR disables the `assert` transformation for now and also changes the output to pre. It will automatically be deployed once merged)Short follow-up: this is now live for the released documentation pages. Enjoy!Please make a post on Reddit! I firmly believe that this puts D at the top of programming language docs. We should advertise!
Feb 18 2017
On Saturday, 18 February 2017 at 16:43:43 UTC, Seb wrote:Excellent idea! AFAIK reddit doesn't like self posts that much. Would someone be so kind to post this once the improvements are in? https://github.com/dlang/dlang.org/pull/1575 (this PR disables the `assert` transformation for now and also changes the output to pre. It will automatically be deployed once merged)I'll do it. But before I do, I'll want to know that everything is working as intended. Post here with a green light and I'll post it during one of the peak periods.
Feb 18 2017
On Sunday, 19 February 2017 at 02:27:41 UTC, Mike Parker wrote:On Saturday, 18 February 2017 at 16:43:43 UTC, Seb wrote:Thanks a lot! FYI the PR fix has been merged. Unfortunately it reverts the writeln magic as the false positive rate was too high - at some point we really should come up with something better :/ However the fact that ddoc and ddox emit different, fully built synax-highlighted HTML doesn't make it easier. Maybe the compiler can help out here (?) or we can run a libdparse-based formatter before running ddoc/ddox? (at least for ddox there is also the intermediate json output of DMD, but for now it seems that the switch to ddox doesn't happen as soon as anticipated)Excellent idea! AFAIK reddit doesn't like self posts that much. Would someone be so kind to post this once the improvements are in? https://github.com/dlang/dlang.org/pull/1575 (this PR disables the `assert` transformation for now and also changes the output to pre. It will automatically be deployed once merged)I'll do it. But before I do, I'll want to know that everything is working as intended. Post here with a green light and I'll post it during one of the peak periods.
Feb 21 2017
On Tuesday, 21 February 2017 at 22:58:57 UTC, Seb wrote:Unfortunately it reverts the writeln magic as the false positive rate was too high - at some point we really should come up with something better :/ However the fact that ddoc and ddox emit different, fully built synax-highlighted HTML doesn't make it easier. Maybe the compiler can help out here (?) or we can run a libdparse-based formatter before running ddoc/ddox? (at least for ddox there is also the intermediate json output of DMD, but for now it seems that the switch to ddox doesn't happen as soon as anticipated)Okay I just couldn't let this sit on myself. So I went ahead and proposed a more "sophisticated" assert -> writeln rewrite tool that is based on Hackerpilot's excellent libdparse: https://github.com/dlang/dlang.org/pull/1582
Feb 22 2017
On Wednesday, 22 February 2017 at 19:14:14 UTC, Seb wrote:Okay I just couldn't let this sit on myself. So I went ahead and proposed a more "sophisticated" assert -> writeln rewrite tool that is based on Hackerpilot's excellent libdparse: https://github.com/dlang/dlang.org/pull/1582So is everything working as advertised? Is it redditable?
Feb 27 2017
On Monday, 27 February 2017 at 14:12:30 UTC, Mike Parker wrote:On Wednesday, 22 February 2017 at 19:14:14 UTC, Seb wrote:Yes, thanks to a lot of support from CyberShadow [1] and Hackerpilot's immediate review of my libdparse fixes [2, 3], the new assert -> writeln logic is now live, e.g. Ddox: https://dlang.org/library-prerelease/std/algorithm/comparison/among.html Ddoc: https://dlang.org/phobos/std_algorithm_searching.html#.minElement It's based on a AST transformation of the AssertExpressions. For more details one can have a look at [4].Okay I just couldn't let this sit on myself. So I went ahead and proposed a more "sophisticated" assert -> writeln rewrite tool that is based on Hackerpilot's excellent libdparse: https://github.com/dlang/dlang.org/pull/1582So is everything working as advertised?Is it redditable?Yes, finally :) [1] https://github.com/dlang/dlang.org/pull/1582 [2] https://github.com/Hackerpilot/libdparse/pull/128 [3] https://github.com/Hackerpilot/libdparse/pull/130 [4] https://github.com/dlang/dlang.org/blob/master/assert_writeln_magic.d
Feb 27 2017
On Monday, 27 February 2017 at 15:41:18 UTC, Seb wrote:Can we fix the fact that the docs are duplicated for template functions before any big announcements? See e.g. https://dlang.org/library-prerelease/std/algorithm/comparison/among.html from above. This leaves quite the bad impression, as it makes the page look like an unstructured mess at first glance. - DavidIs it redditable?Yes, finally :)
Feb 27 2017
On Monday, 27 February 2017 at 16:49:13 UTC, David Nadlinger wrote:On Monday, 27 February 2017 at 15:41:18 UTC, Seb wrote:That's one of the disadvantages of running two documentation engines. Related pointers: https://github.com/dlang/dlang.org/pull/1526 (making ddox the default) https://github.com/rejectedsoftware/ddox/issuesCan we fix the fact that the docs are duplicated for template functions before any big announcements? See e.g. https://dlang.org/library-prerelease/std/algorithm/comparison/among.html from above.Is it redditable?Yes, finally :)This leaves quite the bad impression, as it makes the page look like an unstructured mess at first glance.A solution for the moment is to point people at the ddoc version, e.g. https://dlang.org/phobos/std_algorithm_comparison.html#.among
Feb 27 2017
On Monday, 27 February 2017 at 17:13:24 UTC, Seb wrote:A solution for the moment is to point people at the ddoc version, e.g. https://dlang.org/phobos/std_algorithm_comparison.html#.amongSure, linking only that would definitely work. — David
Feb 27 2017
On Monday, 27 February 2017 at 16:49:13 UTC, David Nadlinger wrote:See e.g. https://dlang.org/library-prerelease/std/algorithm/comparison/among.html from above. This leaves quite the bad impression, as it makes the page look like an unstructured mess at first glance.What's up with the bullet point list at the top of the page? I'd understand it if they were links to the specific overloads, but just being text it seems silly to have it there. Even repeating the ditto wouldn't bother me if it was linked or something... And ddoc fails to display that sanely too, it shows the outer template, but not the inner function you'd actually use. Thankfully, the examples cover it, but IMO neither ddoc nor ddox actually do a good job on this. BTW, this is how my doc site renders that: http://dpldocs.info/experimental-docs/std.algorithm.comparison.among.1.html I also do a list of overloads, but present them as an accordian-style list of links with an argument summary so you can see at a glance what one might be which. (I'm not 100% in love with my doc here either, but I do like it better than either option on dlang.org. Y'all should start stealing my ideas.)
Feb 27 2017
On Monday, 27 February 2017 at 15:41:18 UTC, Seb wrote:I'm thinking it might be better to do a blog post about it and reddit that instead of posting a link to the docs or this announcement directly. Something describing the implementation and the "writeln transformation magic". Up for it?Is it redditable?Yes, finally :)
Feb 27 2017
On Friday, 17 February 2017 at 05:06:20 UTC, Seb wrote:On Saturday, 7 January 2017 at 16:12:49 UTC, Andrei Alexandrescu wrote:Might I suggest you change the output <textarea>s to <pre>s with border: none; and max-height: 30em; This would make them auto-grow to the right height to fit the content (with max-height for sanity). It does mean you lose manual resizability (unless you mess around in js to sort out the clash with max-height)), but that doesn't seem so important if it auto-resizes.Following https://github.com/dlang/dlang.org/pull/1532, the new-style docs now also allow editing and running examples. Start at http://dlang.org/library-prerelease/ and go anywhere to check it out. Thanks are due to Sönke Ludwig and Sebastian Wilzbach! AndreiShort follow-up: this is now live for the released documentation pages. Enjoy! Ddoc: https://dlang.org/phobos/std_algorithm_comparison.html#among Ddox: https://dlang.org/library/std/algorithm/comparison/among.html Your feedback is of course welcome. A couple of modules are still blacklisted, but it's WIP to remove the blacklist [1]. Also as mentioned DPaste [2] is used as Backend. If you want to hack with it directly, you may have a look at [3]. Cheers, Seb [1] https://github.com/dlang/phobos/pull/5142 [2] https://dlang.org/blog/2017/01/30/project-highlight-dpaste/ [3] https://github.com/dlang/dlang.org/blob/master/js/run_examples.js
Feb 17 2017
On Friday, 17 February 2017 at 13:50:48 UTC, John Colvin wrote:Might I suggest you change the output <textarea>s to <pre>s with border: none; and max-height: 30em; This would make them auto-grow to the right height to fit the content (with max-height for sanity). It does mean you lose manual resizability (unless you mess around in js to sort out the clash with max-height)), but that doesn't seem so important if it auto-resizes.+1
Feb 17 2017
On Friday, 17 February 2017 at 13:50:48 UTC, John Colvin wrote:Might I suggest you change the output <textarea>s to <pre>s with border: none; and max-height: 30em; This would make them auto-grow to the right height to fit the content (with max-height for sanity). It does mean you lose manual resizability (unless you mess around in js to sort out the clash with max-height)), but that doesn't seem so important if it auto-resizes.Excellent idea! As the same js is used for the runnable boxes on the dlang.org main page, I didn't want to touch the editor that much (initially). Anyway I submitted a PR that changes the output element to <pre>: https://github.com/dlang/dlang.org/pull/1575 As imho the border doesn't look that bad and for the same reason as above I didn't remove the border. See a visual comparison here: http://imgur.com/a/pElAu Are you or others still in favor of removing the border?
Feb 18 2017
On Saturday, 18 February 2017 at 16:57:33 UTC, Seb wrote:As imho the border doesn't look that bad and for the same reason as above I didn't remove the border. See a visual comparison here: http://imgur.com/a/pElAu Are you or others still in favor of removing the border?I like the first version in the screenshot (with a border).
Feb 23 2017
On 2/17/17 6:06 AM, Seb wrote:On Saturday, 7 January 2017 at 16:12:49 UTC, Andrei Alexandrescu wrote:Broken on the first example I tried :( http://dlang.org/library-prerelease/std/algorithm/searching/find.html --- Dmitry OlshanskyFollowing https://github.com/dlang/dlang.org/pull/1532, the new-style docs now also allow editing and running examples. Start at http://dlang.org/library-prerelease/ and go anywhere to check it out.
Feb 17 2017
Am 17.02.2017 um 22:07 schrieb Dmitry Olshansky:On 2/17/17 6:06 AM, Seb wrote:The example got cut off two or three characters too early, compared with the source unit test. I'll have to check if this is an issue with DDOX, or with the JSON output.On Saturday, 7 January 2017 at 16:12:49 UTC, Andrei Alexandrescu wrote:Broken on the first example I tried :( http://dlang.org/library-prerelease/std/algorithm/searching/find.html --- Dmitry OlshanskyFollowing https://github.com/dlang/dlang.org/pull/1532, the new-style docs now also allow editing and running examples. Start at http://dlang.org/library-prerelease/ and go anywhere to check it out.
Feb 18 2017
Am 18.02.2017 um 14:43 schrieb Sönke Ludwig:Am 17.02.2017 um 22:07 schrieb Dmitry Olshansky:Hm, okay, false alert. The characters are there in the page sources and get cut off by the JS that transforms the HTML.On 2/17/17 6:06 AM, Seb wrote:The example got cut off two or three characters too early, compared with the source unit test. I'll have to check if this is an issue with DDOX, or with the JSON output.On Saturday, 7 January 2017 at 16:12:49 UTC, Andrei Alexandrescu wrote:Broken on the first example I tried :( http://dlang.org/library-prerelease/std/algorithm/searching/find.html --- Dmitry OlshanskyFollowing https://github.com/dlang/dlang.org/pull/1532, the new-style docs now also allow editing and running examples. Start at http://dlang.org/library-prerelease/ and go anywhere to check it out.
Feb 18 2017
On Saturday, 18 February 2017 at 13:46:10 UTC, Sönke Ludwig wrote:Am 18.02.2017 um 14:43 schrieb Sönke Ludwig:Yeah the regex trick doesn't seem to work that well: -> https://github.com/dlang/dlang.org/pull/1575 (disables the `assert` transformation for now and also changes the output to pre)Am 17.02.2017 um 22:07 schrieb Dmitry Olshansky:Hm, okay, false alert. The characters are there in the page sources and get cut off by the JS that transforms the HTML.On 2/17/17 6:06 AM, Seb wrote:The example got cut off two or three characters too early, compared with the source unit test. I'll have to check if this is an issue with DDOX, or with the JSON output.On Saturday, 7 January 2017 at 16:12:49 UTC, Andrei Alexandrescu wrote:Broken on the first example I tried :( http://dlang.org/library-prerelease/std/algorithm/searching/find.html --- Dmitry OlshanskyFollowing https://github.com/dlang/dlang.org/pull/1532, the new-style docs now also allow editing and running examples. Start at http://dlang.org/library-prerelease/ and go anywhere to check it out.
Feb 18 2017
On 01/07/2017 11:12 AM, Andrei Alexandrescu wrote:Following https://github.com/dlang/dlang.org/pull/1532, the new-style docs now also allow editing and running examples. Start at http://dlang.org/library-prerelease/ and go anywhere to check it out. Thanks are due to Sönke Ludwig and Sebastian Wilzbach! Andrei1. This is pretty awesome. 2. Looks like someone forgot to set a foreground text color for the output even though the background is set to white. This makes the output text invisible for those using eye-friendly light-on-dark systems.
Feb 17 2017
On Friday, 17 February 2017 at 16:07:37 UTC, Nick Sabalausky (Abscissa) wrote:1. This is pretty awesome.Thanks a lot :)2. Looks like someone forgot to set a foreground text color for the output even though the background is set to white. This makes the output text invisible for those using eye-friendly light-on-dark systems.I am not sure I follow. Do you use a custom color scheme or plugin that sets the body background color to black? What exactly would be the best way for you to resolve your problem? Maybe you can even submit a PR yourself? - the CSS is here: https://github.com/dlang/dlang.org/blob/master/css/style.css#L1611
Feb 18 2017
On 02/18/2017 11:48 AM, Seb wrote:On Friday, 17 February 2017 at 16:07:37 UTC, Nick Sabalausky (Abscissa) wrote:Dark system color scheme, nothing mucking with website CSSes or anything. Somewhat bizarrely/irritatingly, there are certain cases (<input> and <textarea> to my knowledge, maybe others) where browsers inherit default color settings from the OS[1] instead of from a built-in browser-default CSS. Since my OS is set up to default to (near-)white text on a (near-)black background, the browser decides "Oh, ok, I'll use white text on a black background for inputs and textareas." But then the site's CSS tells it to use a white background. And says nothing about text color. Browser says: "Ok! So, white text (system textbox default) on a white background (website CSS)!!" [1] Browsers taking theme defaults from the OS was appropriate behavior back in HTML1 when the whole web was actually designed from the ground-up to automatically adapt to the machine being used. But not so much now that every site/page in the world uses its own theme and formatting system[2], and even the browser's own default css *mostly* (with, of course, these broken exceptions) separates itself from the OS, leaving occasionally broken readability. [2] The site-chosen formatting system occasionally being one that attempts to partially adapt to the local machine, to varying degrees of success. Thanks, legacy of HTML2/4! Did I mention I hate web browsers? ;)1. This is pretty awesome.Thanks a lot :)2. Looks like someone forgot to set a foreground text color for the output even though the background is set to white. This makes the output text invisible for those using eye-friendly light-on-dark systems.I am not sure I follow. Do you use a custom color scheme or plugin that sets the body background color to black?What exactly would be the best way for you to resolve your problem? Maybe you can even submit a PR yourself? - the CSS is here: https://github.com/dlang/dlang.org/blob/master/css/style.css#L1611I'm working out building the site locally right now so I can test (building it seems to be taking awhile), but: d_code_output sections (might not matter for the div version, but wouldn't hurt either.) That should work. Or it might be better to just toss this in around the top of the CSS: -------------------------- input, textarea { background-color: white; } --------------------------
Feb 18 2017
On 02/18/2017 08:42 PM, Nick Sabalausky (Abscissa) wrote:Or it might be better to just toss this in around the top of the CSS: -------------------------- input, textarea { background-color: white; } --------------------------K, just tested it, works for me: https://github.com/dlang/dlang.org/pull/1576
Feb 18 2017