Other libraries - web site link, and other thoughts

[Laeeth Isharc via Digitalmars-d-learn]

At the moment it goes straight go code.dlang.org, which may be a 
bit overwhelming if you have just arrived at dlang.org and want 
to see what it can do.

Is it worth changing to the library wiki write up page on 
libraries?  And making sure link to code.dlang.org is prominent, 
saying "code.dlang.org is a registry of D libraries hosted on 
github.  There are currently XYZ libraries, of which ABC are 
under active development".

At the moment, the list of libraries on the wiki is fairly 
complete, but not oriented towards answering the question of how 
do I do stuff.  It would be nice to have a set of pages on this 
that mines the gold from the forums and makes it easy to find.  
Eg "how do I navigate html or xml?".  Use dom.d or ae, and here 
are some simple programs.

Compare python community doc situation to ours.  (We are leaner, 
but that doesn't mean we can't do a better job),

Also say that if you cannot find the library you need, you should 
know that it is easy to interface to all C libraries (click for 
details), and that it is possible and fairly easy to interface to 
many C++ libraries (click here).

p0nce and others are doing great work on D idioms, but what is 
missing is pointers to examples of larger programs.  I know it is 
common sense if you are experienced to read the source of other 
projects to learn, but is it worth making this easy by having in 
the section on learning D some pointers to some model D code 
bases.

The FUD crowd on slashdot always brings up the Tango / Phobos 
split, but this is not prominently addressed on the web site.  
Should this not be answered in the main FAQ?

The compilation speed of dmd (and somewhat ldc) is a major 
advantage.  It is stunning in outright terms, and almost 
inconceivable if you come from the world of c++.  It really 
matters because it allows you to shift styles to iterative 
development.  So it should be featured on the front page, and 
there should be quantitative benchmarks (because that's what 
modern people like) comparing dmd to other language compilers as 
well as pointing out how quickly phobos compiles. A YouTube video 
may make it more concrete.  And there should be quotes from 
authoritative users of D talking about how useful they find quick 
compilation and iterative development.

People are lazy.  Or more charitably, not wealthy in terms of 
attention and time in the modern world.  The documentation is 
often written from the point of view of the compiler and library 
writer, and this is not the point of view of the user, who wants 
to know what he can do, and how he can do it.

In the "interfacing to C tutorial", how about starting off by 
getting to the point.  Have the following section at the 
beginning, and maybe even make it crisper by saying that D can 
utilise all existing C libraries, and all that needs to be done 
is to translate the header  files to D.

Using Existing C Libraries
Since D can call C code directly, it can also call any C library 
functions, giving D access to the smorgasbord of existing C 
libraries. To do so, however, one needs to write a D interface 
(.di) file, which is a translation of the C .h header file for 
the C library into D.

For popular C libraries, the first place to look for the 
corresponding D interface file is the Deimos Project. If it isn't 
there already, and you write one, please contribute it to the 
Deimos Project.

---

In the spirit of accommodating peoples' attention poverty, why 
not say at the top that there are translation tools for objective 
C and C.  Click here to download dstep binaries (linux / win 
etc), and here to go to the github dstep site.  I confess that I 
struggled for ages unsuccessfully to compile dstep on my platform 
without realising that the binaries were available for download.

Similarly for C++, the web site starts off completely on the 
wrong note." While D is fully capable of interfacing to C, its 
ability to interface to C++ is much more limited. There are three 
ways to do it:"

I hear "much more limited", and think I am not going to bother 
with this (if I have not yet committed to the language).  Whereas 
in actual fact, as Walter pointed out in his talk, nobody else 
can interface with C++ and it is a marvel to be able to do so at 
all, let alone in a way that is much more complete than the docs 
suggest.  And it sounds like this phrasing is in any case 
outdated.

Change to something like: "Interfacing to C++ is a challenging 
endeavour for any language, but it is a challenge that must be 
met in order to take advantage of the large set of existing 
libraries and code bases in C++.  It is therefore a priority for 
2015 to implement an ability to link to a set of C++ that will be 
complete for most use cases.  Walter Bright spoke recently at 
Microsoft on this topic, and the reader may find the following 
forum threads of interest.

As things stand, the following features are complete:..., whilst 
there are limitations with respect to: exceptions, multiple 
inheritance, ...

The aim is to finish C++ interfacing in the reference compiler 
DMD, and it is likely that this support will be extended to the 
other D language compilers: GDC, and LDC.

Parallel to this effort, there is an alpha project called Calypso 
that takes advantage of the clang API to integrate almost 
complete C++ support within the D compiler LDC and takes away the 
need to generate separate headers.  Link here to download 
binaries (they are not yet available, but we should offer 
standard builds even though it is alpha because of the strategic 
importance of the project, and because clang/llvm is not trivial 
to build - I needed to edit my usr/include headers to hack up 
size_align_t just to get it to compiled) and here for github.




Laeeth