www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - site examples

reply crimaniak <crimaniak gmail.com> writes:
I tried to run an example from the site. Example from 
https://dlang.org/phobos/std_regex.html#replaceAllInto section. 
And this is problem number 0: I can't give a link to the example, 
only to section. The section can be long, there can be more than 
one example, so it's good to have an anchor for each example. 
Problem #1: "Compilation output (255: Unknown signal 255)
unable to fork: Cannot allocate memory." As I understand it, this 
is a common problem, and it leaves a bad impression. Ok, I copy 
example text and try to compile it. Oh, I need to make main(). 
Ok. "t1.d(6): Error: undefined identifier 'regex'
t1.d(12): Error: undefined identifier 'replaceAllInto'
t1.d(14): Error: 'writeln' is not defined, perhaps you need to 
import std.stdio; ?"
Problem #3: we have imports in the example, but not all imports. 
Ok, I add it. Compile, run. A lot of commas. Is this proof that 
the method worked? Yes. Do these commas illustrate how this 
method works? Absolutely not. This is a replacement method, so I 
expect to see "before" and "after".
It seems to me that examples on the site require additional work 
and in the current form are counterproductive in terms of 
attracting new users.
May 25
next sibling parent Stanislav Blinov <stanislav.blinov gmail.com> writes:
On Thursday, 25 May 2017 at 15:41:47 UTC, crimaniak wrote:

 It seems to me that examples on the site require additional 
 work and in the current form are counterproductive in terms of 
 attracting new users.
https://github.com/dlang/phobos
May 25
prev sibling parent reply bachmeier <no spam.net> writes:
On Thursday, 25 May 2017 at 15:41:47 UTC, crimaniak wrote:
 I tried to run an example from the site. Example from 
 https://dlang.org/phobos/std_regex.html#replaceAllInto section. 
 And this is problem number 0: I can't give a link to the 
 example, only to section. The section can be long, there can be 
 more than one example, so it's good to have an anchor for each 
 example. Problem #1: "Compilation output (255: Unknown signal 
 255)
 unable to fork: Cannot allocate memory." As I understand it, 
 this is a common problem, and it leaves a bad impression.
I can confirm that this is a problem. It does indeed leave a bad impression, and needs to be fixed or removed.
 It seems to me that examples on the site require additional 
 work and in the current form are counterproductive in terms of 
 attracting new users.
I am in agreement. The easiest solution would be to add examples to the wiki and link to them from the documentation.
May 25
parent Seb <seb wilzba.ch> writes:
On Thursday, 25 May 2017 at 16:07:34 UTC, bachmeier wrote:
 On Thursday, 25 May 2017 at 15:41:47 UTC, crimaniak wrote:
 I tried to run an example from the site. Example from 
 https://dlang.org/phobos/std_regex.html#replaceAllInto 
 section. And this is problem number 0: I can't give a link to 
 the example, only to section. The section can be long, there 
 can be more than one example, so it's good to have an anchor 
 for each example. Problem #1: "Compilation output (255: 
 Unknown signal 255)
 unable to fork: Cannot allocate memory." As I understand it, 
 this is a common problem, and it leaves a bad impression.
You do realize that this is due DPaste's poor performance? There's not much we can do except for replacing it with a proper execution backend. I gave it a short try a couple of weeks ago, but unfortunately I stopped as my intended replacement (DLang Tour) didn't support stdin and args: https://github.com/dlang/dlang.org/pull/1647
 I can confirm that this is a problem. It does indeed leave a 
 bad impression, and needs to be fixed or removed.
Just for the record: as part of the Phobos CI system, we _do_ have a script that is run for every PR and automatically extracts all public unittests and tries to run them separately, exactly to avoid there's a bad impression ;-) In case you are interested, the regarding Makefile target is:
 make -f posix.mak publictests
You can also run it individually for a single module, e.g.
 make -f posix.mak std/regex/package.publictests
For reference, the example that we are talking about is: https://github.com/dlang/phobos/blob/master/std/regex/package.d#L1422 I do agree, that this is a horrible example for potential users and should be replaced with a proper example.
 It seems to me that examples on the site require additional 
 work and in the current form are counterproductive in terms of 
 attracting new users.
When I wrote the bits that allowed the examples to be runnable, I also wrote the tooling to ensure that they are _always_ runnable. For more infos: http://dlang.org/blog/2017/03/08/editable-and-runnable-doc-examples-on-dlang-org However, it was deemed too noisy to add "import <currentmodule>, std.stdio;" to the examples. That's why we do this on-the-fly: https://github.com/dlang/dlang.org/blob/master/js/run_examples.js#L29 If you get the approval, it would be pretty trivial (i.e. a two-liner) to add these imports, considering that (1) the test extractor adds the import of the current module: https://github.com/dlang/tools/blob/master/styles/tests_extractor.d And (2) we already have a rewrite pipeline in-place to transform asserts into writelns: https://github.com/dlang/dlang.org/blob/master/assert_writeln_magic.d
 I am in agreement. The easiest solution would be to add 
 examples to the wiki and link to them from the documentation.
Sorry, but I think you will have a _very_ hard time, because - People won't be able to find them - Examples in D get "broken" very quickly due to missing imports, minor changes in Phobos, compiler "features" etc. Why do I believe the latter? - There was a time when CircleCi wasn't enforced at Phobos and people used to break it every one or two weeks... - I am one of the maintainer of the DLang Tour and before there was a CI, people used to make tiny good-looking changes to the examples there, with the result that 50% of all examples weren't compilable - Some of the official examples shipped with dmd don't compile anymore
May 25