site examples

[Seb via Digitalmars-d-learn]

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