Re: New (page-per-artifact) standard library doc examples are now editable and runnable
On Monday, 27 February 2017 at 15:41:18 UTC, Seb wrote: Is it redditable? Yes, finally :) 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?
Re: New (page-per-artifact) standard library doc examples are now editable and runnable
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#.among Sure, linking only that would definitely work. — David
Re: New (page-per-artifact) standard library doc examples are now editable and runnable
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.)
Re: New (page-per-artifact) standard library doc examples are now editable and runnable
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: Is it redditable? Yes, finally :) 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. 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/issues 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
Re: New (page-per-artifact) standard library doc examples are now editable and runnable
On Monday, 27 February 2017 at 15:41:18 UTC, Seb wrote: Is it redditable? Yes, finally :) 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. - David
Re: New (page-per-artifact) standard library doc examples are now editable and runnable
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: 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 So is everything working as advertised? 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]. 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
Re: New (page-per-artifact) standard library doc examples are now editable and runnable
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/1582 So is everything working as advertised? Is it redditable?
Re: New (page-per-artifact) standard library doc examples are now editable and runnable
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).
Re: New (page-per-artifact) standard library doc examples are now editable and runnable
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
Re: New (page-per-artifact) standard library doc examples are now editable and runnable
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: 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. 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)
Re: New (page-per-artifact) standard library doc examples are now editable and runnable
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.
Re: New (page-per-artifact) standard library doc examples are now editable and runnable
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;
color: #333;
}
--
K, just tested it, works for me:
https://github.com/dlang/dlang.org/pull/1576
Re: New (page-per-artifact) standard library doc examples are now editable and runnable
On 02/18/2017 11:48 AM, Seb wrote:
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?
Dark system color scheme, nothing mucking with website CSSes or
anything. Somewhat bizarrely/irritatingly, there are certain cases
( and 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? ;)
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
I'm working out building the site locally right now so I can test
(building it seems to be taking awhile), but:
Looks like the site is mostly using #333 for text color. You could just
toss in "color: #333;" right next to "background: white;" for the
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;
color: #333;
}
--
Re: New (page-per-artifact) standard library doc examples are now editable and runnable
On Friday, 17 February 2017 at 13:50:48 UTC, John Colvin wrote: Might I suggest you change the output s to 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 : 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?
Re: New (page-per-artifact) standard library doc examples are now editable and runnable
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
Re: New (page-per-artifact) standard library doc examples are now editable and runnable
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: 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! 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)
Re: New (page-per-artifact) standard library doc examples are now editable and runnable
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: Am 17.02.2017 um 22:07 schrieb Dmitry Olshansky: On 2/17/17 6:06 AM, Seb wrote: 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. Broken on the first example I tried :( http://dlang.org/library-prerelease/std/algorithm/searching/find.html --- Dmitry Olshansky 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. Hm, okay, false alert. The characters are there in the page sources and get cut off by the JS that transforms the HTML. 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)
Re: New (page-per-artifact) standard library doc examples are now editable and runnable
Am 18.02.2017 um 14:43 schrieb Sönke Ludwig: Am 17.02.2017 um 22:07 schrieb Dmitry Olshansky: On 2/17/17 6:06 AM, Seb wrote: 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. Broken on the first example I tried :( http://dlang.org/library-prerelease/std/algorithm/searching/find.html --- Dmitry Olshansky 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. Hm, okay, false alert. The characters are there in the page sources and get cut off by the JS that transforms the HTML.
Re: New (page-per-artifact) standard library doc examples are now editable and runnable
Am 17.02.2017 um 22:07 schrieb Dmitry Olshansky: On 2/17/17 6:06 AM, Seb wrote: 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. Broken on the first example I tried :( http://dlang.org/library-prerelease/std/algorithm/searching/find.html --- Dmitry Olshansky 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.
Re: New (page-per-artifact) standard library doc examples are now editable and runnable
On 2/17/17 6:06 AM, Seb wrote: 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. Broken on the first example I tried :( http://dlang.org/library-prerelease/std/algorithm/searching/find.html --- Dmitry Olshansky
Re: New (page-per-artifact) standard library doc examples are now editable and runnable
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: 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? 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` 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...
Re: New (page-per-artifact) standard library doc examples are now editable and runnable
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! Andrei 1. 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.
Re: New (page-per-artifact) standard library doc examples are now editable and runnable
On Friday, 17 February 2017 at 13:50:48 UTC, John Colvin wrote: Might I suggest you change the output s to 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
Re: New (page-per-artifact) standard library doc examples are now editable and runnable
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: 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 Short 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 Might I suggest you change the output s to 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.
Re: New (page-per-artifact) standard library doc examples are now editable and runnable
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!
Re: New (page-per-artifact) standard library doc examples are now editable and runnable
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! Andrei Short 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
Re: New (page-per-artifact) standard library doc examples are now editable and runnable
On Saturday, 7 January 2017 at 20:14:56 UTC, Martin Nowak wrote: 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? 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 ;-)
Re: New (page-per-artifact) standard library doc examples are now editable and runnable
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?
New (page-per-artifact) standard library doc examples are now editable and runnable
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
