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. 

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; ?"

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 2017
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 2017
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 

 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 2017
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 

 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 2017