The english from dlang-tour

copy download page for "Install locally"

From @wilzbach on May 23, 2016 17:53

http://dlang.org/download.html

looks a lot nicer than

http://tour.dlang.io/tour/welcome/2

Imho we should copy most of it - at least having images is nice :)

Copied from original issue: dlang-tour/core#148

More newbie-oriented tour

From @wilzbach on June 13, 2016 10:49

While having a look at #193, I realized that the tour isn't well suited for someone with no or little programming background as we don't explain any basics like variables or pointers.

As our main target are experienced programmers, that's ok - however imho we could try to target beginners too. I am not sure yet what is the best way to do this, but an idea would be to have a "freshup section" to which we point in the beginning - like e.g. "New to pointers? Read this".

Copied from original issue: dlang-tour/core#258

on basics/slices T[]

From @wilzbach on June 24, 2016 16:47

maybe is to early for templates :) If slice and dynamic arrays are the same. what I should use?

(reported by @claudiug)

Copied from original issue: dlang-tour/core#355

add gem about variadiac functions

From @wilzbach on May 17, 2016 20:30

http://dlang.org/variadic-function-templates.html

Copied from original issue: dlang-tour/core#126

In-depth links to "Programming in D"

From @wilzbach on May 25, 2016 18:43

There are many great section in @acehreli's book
http://ddili.org/ders/d.en/index.html

They would be great to have as in-depth links for the reader if they want to "dive deeper".
It's also a good sanity check for the tour, to see whether there is missing content.

Copied from original issue: dlang-tour/core#193

Mention std.format's great features somewhere

From @wilzbach on May 18, 2016 7:49

@CyberShadow shows a lot of hidden secrets in D at #dconf

one is them being the powerful D-specific features of std.format.

writef("%(* %s\n%)",  ["#dlang",  "rocks"])

* dlang
* rocks

Copied from original issue: dlang-tour/core#131

use wordcount example with lowerCase words

From @wilzbach on May 25, 2016 17:57

As said it was a bit frustrating to see only 1 matches - an alternative would be rewrite the dummy text so that at least one word occurs twice.

Word counts: ["which":1, "systems":1, "of":1, "machine":1, "and":1, "":2, "code":1, "*native*":1, "you":1, "expressive":1, "powerful":1, "language":1, "tour":1, "compiles":1, "directly":1, "give":1, "will":1, "this":2, "an":1, "overview":1, "programming":1, "to":1, "efficient":1]

Copied from original issue: dlang-tour/core/pull/192

on basics/structs

From @wilzbach on June 24, 2016 16:47

maybe example from here are more clear (https://developer.apple.com/library/ios/documentation/Swift/Conceptual/Swift_Programming_Language/ClassesAndStructures.html)

(reported by @claudiug)

Copied from original issue: dlang-tour/core#354

explain `ref` parameter

From @wilzbach on May 23, 2016 19:4

Probably somewhere in basics - ideas?

Copied from original issue: dlang-tour/core#166

explain delegate pattern basics/delegates

From @wilzbach on June 24, 2016 16:47

is about delegate pattern here, maybe example from swift delegate pattern documentation :)

(reported by @claudiug)

Copied from original issue: dlang-tour/core#362

confusing end of welcome chapter

From @wilzbach on May 25, 2016 13:37

Could you point out why it is confusing to you.

I had the same experience. The page number is 5/5 and the arrows are grayed out. That looks like "the end" to me.

Currently the text says:

"Either use the navigation panel at the bottom or press the right arrow
key."

But before that, it says "Congratulations for finishing the first chapter. You're now ready to dive into the world of D." which may (and did to me) mean "this is the end, go out there and try out D now." It's easy to miss "first chapter" in there.

What could we add to avoid the confusion?

Arrows should not be gray (how about green?)
5/5 doesn't carry much meaning for me and potentially confusing as it did

Copied from original issue: dlang-tour/core#187

Introduce "subchapters" or "tours"

From @wilzbach on June 14, 2016 15:19

As said in #265, I am concerned since the GA Analytics results that those our categories are:

too wide (common rule is to have at most 7 items)
put the "best parts" at the end

My best ideas currently are

introduce subchapters and thus have grouping in the section like (Object oriented programming, control flow, ...
introduce "tours" and reuse the existing hiearchy (e.g. "Basics" would be an entire tour)
instead of "Basics" and "Gems" split into more chapters

Related to this idea is #52 (menu at the left side).

Copied from original issue: dlang-tour/core#269

explain char & numeric literals

From @wilzbach on June 26, 2016 0:20

- for integers
different types (postfix)
hex-floats

https://dlang.org/spec/lex.html#integerliteral

Copied from original issue: dlang-tour/core#377

new gem: alias, tuples & static foreach

From @wilzbach on June 26, 2016 0:6

I feel that neither alias, static foreach and tuples are well represented in the tour. They are already needed in other sections (e.g. #264), so we should probably try to enhance basics/alias-strings and maybe even create a new gem. The meta programming gem also doesn't cover any of these topics.

btw if static foreach is unfamilar:

import std.meta : AliasSeq;
foreach (c, AliasSeq!(int, float))
   ...

Copied from original issue: dlang-tour/core#375

Scroll up to page start on run for mobile views

From @wilzbach on June 17, 2016 18:46

Currently the page scrolls down to the bottom, quite annoying for users.

Copied from original issue: dlang-tour/core#296

add gem about interfacing to C/C++

From @wilzbach on May 17, 2016 20:31

https://dlang.org/spec/interfaceToC.html

https://dlang.org/spec/cpp_interface.html

https://dlang.org/spec/objc_interface.html

https://dlang.org/spec/abi.html

Copied from original issue: dlang-tour/core#127

Better instructions for Windows

From @wilzbach on June 11, 2016 3:37

Windows users have a huge majority among the visitors. In most cases users don't know what a CLI is, so probably either the page 2 (manual installation) or page 3 (CLI instructions) kills them.

So imho: no CLI instructions for Windows users, but maybe VisualD (and others (?)

Copied from original issue: dlang-tour/core#245

gem: @nogc allocation

From @wilzbach on May 23, 2016 18:51

Probably showing off the features/API in std.experimental.allocator

Copied from original issue: dlang-tour/core#159

on basics/imports-and-modules

From @wilzbach on June 24, 2016 16:47

will great adagio if you will add comparasion with python module system OR d programming book chapter

(reported by @claudiug)

Copied from original issue: dlang-tour/core#349

explain is operator (identity expression)

From @wilzbach on May 23, 2016 17:26

Quite useful

foo is null
float.nan == float.nan // false
float.nan is float.nan // true

See at spec https://dlang.org/spec/expression.html

Copied from original issue: dlang-tour/core#142

Convert comments on function examples to /** */ style

From @stonemaster on May 13, 2016 7:1

As phobos does it all comments should have the /** and */ syntax for comments.

Copied from original issue: dlang-tour/core#43

explain difference between classes and structs - basics/classes

From @wilzbach on June 24, 2016 16:47

why and when we should pick classes over struct

(reported by @claudiug)

Copied from original issue: dlang-tour/core#360

[exit-pages] We loose the most users in the first ten pages

From @wilzbach on June 10, 2016 17:53

Q: how can we mesmerize them, so that they stick on the tour?

Copied from original issue: dlang-tour/core#239

explain postfix strings literals

From @wilzbach on June 26, 2016 0:18

We don't explain postfix string literals in our tour. Probably basics/alias-strings?

https://dlang.org/spec/lex.html#string_literals

Copied from original issue: dlang-tour/core#376

check feasibility of examples in the tour

From @wilzbach on June 10, 2016 14:5

we should go through all examples and how feasible their example is and the used code in general is - related to #226.

Copied from original issue: dlang-tour/core#228

[new gem]: std.meta & std.typecons

From @wilzbach on June 14, 2016 1:26

With std.meta one can do cool stuff like static foreach:

foreach(Type, AliasSeq!(int, double)
 ...

and well std.typecons is D's library version of tuples.

I am not sure yet whether they can combined into a single gem, but imho they are definitely worth explaining.

Copied from original issue: dlang-tour/core#263

New gem: Lazy function attribute evaluation

From @wilzbach on June 23, 2016 16:10

Not well known, but often useful.

https://dlang.org/lazy-evaluation.html

Copied from original issue: dlang-tour/core#330

gem: tools in the D ecosystem

From @wilzbach on May 26, 2016 14:27

I am not sure about this, but I think somewhere we should have pointers to have to create a good project in D. There is already a lot of built-in stuff

Code coverage: http://dlang.org/code_coverage.html
DDoc: https://dlang.org/spec/ddoc.html

or well maintained

dfmt
Dscanner
DCD
...

Maybe this can be cominded with #150?

Copied from original issue: dlang-tour/core#195

gem: unicode in D

From @wilzbach on June 14, 2016 9:55

How about a new gem that teaches newcomers how Unicode & auto-decoding is handled in D?

@JackStouffer - maybe you can reuse parts of your nice blog post?

Copied from original issue: dlang-tour/core#267

more detailed gems/contract-programming

From @wilzbach on June 24, 2016 16:48

found this chapter quite nice. but will be nice to have more details

(reported by @claudiug)

Copied from original issue: dlang-tour/core#365

too complicated gems/template-meta-programming

From @wilzbach on June 24, 2016 16:48

for a ruby/java guy this looks complicated :

(reported by @claudiug)

Copied from original issue: dlang-tour/core#366

add gem about inline assembler

From @wilzbach on May 17, 2016 20:32

https://dlang.org/spec/iasm.html

Copied from original issue: dlang-tour/core#128

Term "object" is used liberally

From @wilzbach on August 14, 2016 10:15

For example an immutable object
const objects

There are quite a few instances, so I put this here as a reminder.

Copied from original issue: dlang-tour/core#424

mention assignment operators

From @wilzbach on May 23, 2016 18:56

We never mention +=, *=, ... anywhere

Copied from original issue: dlang-tour/core#162

null comparisons with `is`

From @wilzbach on June 26, 2016 10:57

I guess that is a common gotcha for newcomers from other languages.
Maybe in basics/memory?

Copied from original issue: dlang-tour/core#379

gem: Using Fibers with ranges

From @wilzbach on May 18, 2016 13:12

This is one of my favorite features in D, but it took me a while to discover this.
This allows one to write pretty sophisticated lazy algorithms by just saving keeping a reference to the stack.
Ali had a great talk about this year -> http://dconf.org/2016/talks/cehreli.html

import std.concurrency: Generator,yield;
auto r = new Generator!int(
{
    foreach (i; 1 .. 10)
        yield(i);
});

import std.range: iota;
import std.algorithm.comparison: equal;
assert(r.equal(iota(1, 10)));

https://dlang.org/library/std/concurrency/generator.html

Copied from original issue: dlang-tour/core#133

basics/alias-strings - more information about alias

From @wilzbach on June 24, 2016 16:47

more information about alias and maybe more from string reference library

(reported by @claudiug)

Copied from original issue: dlang-tour/core#356

Add images to the Tour

From @wilzbach on June 10, 2016 23:7

I personally love images & I think there are many studies that show that this is a general fact (visual learning is a lot easier for us humans).

Anyway there are a couple of ideas how we could add images to the DLang Tour

Add brand images like the DMan

Source: https://github.com/dlang/dlang.org/blob/master/images/d3.png

There are more those lovely D mascot drawing, like this one for Assembler:

https://github.com/dlang/dlang.org/blob/master/images/d5.gif

Add more icons (e.g. FontAwesome)

I am not sure yet how we could do that, but it's worthwhile to think about it

Add related images (most important)

E.g. for Caesor encryption we could show an image like this:

Your ideas

...

Copied from original issue: dlang-tour/core#244

on basics/storage-classes

From @wilzbach on June 24, 2016 16:47

what is a storage class? When I should use it and why?.

(reported by @claudiug)

Copied from original issue: dlang-tour/core#352

explain inout

From @wilzbach on May 23, 2016 17:39

inout is a pretty confusing feature, so we should definitely explain it somewhere.

https://dlang.org/spec/const3.html
http://forum.dlang.org/post/[email protected]

Ping @schveiguy

Copied from original issue: dlang-tour/core#146

Note unary expressions

From @wilzbach on May 23, 2016 17:23

^, &, | are never mentioned, can maybe combined with #130

Copied from original issue: dlang-tour/core#141

pragmas in D

From @wilzbach on June 10, 2016 14:15

There are many awesome pragmas out there, my favorite one being:

rdmd --force --eval='pragma(msg, __TIMESTAMP__);'

another important one is

pragma(inline, true)

(it verifies that the function can be inlined, see more)

but of course there's is and compiles too.
Maybe we can combine this with #129 (traits)

See more: https://dlang.org/spec/pragma.html

Copied from original issue: dlang-tour/core#229

on basics/memory

From @wilzbach on June 24, 2016 16:47

more information, when we should use pointers and when not.

(reported by @claudiug)

Copied from original issue: dlang-tour/core#351

Find a better word for "security levels" in basics/memory.md

Design by introspection gem

From @wilzbach on August 15, 2016 15:28

We already have the Traits's gem, but it could probably be split feature the term "design by introspection" a bit more.

For me design by introspection are two things

pick the best & fastest implementation (e.g. std.algorithm)
only expose methods/capabilities if they are possible with the current type (e.g. std.range)

Copied from original issue: dlang-tour/core#446

Review usage of "you"

From @ZombineDev on August 14, 2016 9:35

cd public/content/ && grep -Hnr "you" yields:

Copied from original issue: dlang-tour/core#423

Gem: dub

From @wilzbach on May 23, 2016 17:58

Idea: Give a short intro to dub, examples for different use-cases and ideally how to integrate with one's favorite build system.

Ping @s-ludwig.

Copied from original issue: dlang-tour/core#150

[exit-pages] eliminate confusing pages within in the tour

From @wilzbach on June 10, 2016 17:56

This list is more interesting, because #239 shows us that the beginning sucks for many users, whereas the second half shows us pages that are confusing to the users.

TODO: have a closer look at those pages

Copied from original issue: dlang-tour/core#240

Expand bit manipulation gem

From @wilzbach on August 13, 2016 11:34

A couple of nice ideas from @ZombineDev that shouldn't sink into the forgotten world ;-)

BTW there several other interesting applications of bit manipulation that I didn't see mentioned:

using built-in integers for generating all possible subsets of a random access range of fixed size (e.g. 32 or 64)
using http://dlang.org/phobos/std_bitmanip#.BitArray to store a general set (of any size)
using http://dlang.org/phobos/std_bitmanip#.bitsSet to get a range of the indexes of the bits that were set, which useful when these indexes are used to index another array and you need to find the first element in it that passes a certain condition: allowed.bitsSet.countUntil!(idx => arr[idx].isOK)
using std.bitmanip : peak, read to parse any binary format (e.g. network packets, image formats, etc), especially useful when you have described the format with structs (i.e. your not reading it an int at a time).

In my experience bitFields is a more rarely used, but it's still a nice showcase of D's CT power.

(from dlang-tour/core#266 (comment))

Copied from original issue: dlang-tour/core#399

dlang-tour / english Goto Github PK

english's Introduction

English base language version of the DLang Tour

Run locally

english's People

Contributors

Stargazers

Watchers

Forkers

english's Issues

Recommend Projects

Recommend Topics

Recommend Org

Jobs