www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Example within documentations of D seriously need some improvement.

reply Matthew Ong <ongbp yahoo.com> writes:
Hi,

 From what I can see,...

The documentation seems to be making something simple harder to 
understand with lots of noises added. It is scattered all over the 
places. Many information Seem like a lot of dark/unwritten known by only 
a few persons.

1) There is No clear organizations. Associated to the syntax being 
describe. Like: what is the default encapsulation access modifier for 
class/struct/interface/enum/template/mixin/... where are they 
documented? There might be more similar broken/implied.

2) When describing a concept with syntax there most if not all example 
uses foo/bar and not work/payment? (If you get the sideline grin)
Doing some sort of Neural Linguistic Programming to 'suggest' dumping 
someone down? If documentation trying to make a fool out of readers so 
that they 'appear' to be experts? Or documentation are there to help
developer code better. Forum is available, I am grateful for the people 
that has kindly shown me around with sample code.

3) Is not making a new language purpose to make ease the developer mind 
so that they can be free to think about how to model business logic 
rather than be busy trying to figure out what is that strange thing for?

4) Not much working example in the html documentaions and not 
centralise. Only code fragments, with lots of foo & bar again...

Yes. I have seen:
http://www.dsource.org/projects/tutorials/wiki/ArraysCategory
http://www.dprogramming.com/tutorial.php

Plenty more I would expect...

True mastery is to make the complex model easy to understand not not
simple one to be complex to understand.

The best type of tutorial and documentation format I have seen so far
and yet simple to understand are shown here.

http://www.w3schools.com/php/php_operators.asp

They designed it in a way that those poor junior developer can copy and 
paste and still have a working program.

D might consider seriously and carefully how to rework the

Yes. That URL is better than Java tutorial documentation.

Yes, I am ranting. With good reasons. Hopefully for the best of D.

-- 
Matthew Ong
email: ongbp yahoo.com
May 27 2011
next sibling parent reply Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
The docs show the syntax and code fragments, not entire compilable
examples. Although if you provide a main() and copy the code, with
some slight adjustments it should work. In cases where it's obvious
that a code sample would not compile due to some typo or mistake, you
can file a bug report.

If there's missing documentation, file a bug report.

Otherwise the docs are not a tutorial for the language. If there ever
will be a tutorial that's hosted on the D website it will probably be
in a section of its own.

Foo/Bar are typical ways of naming symbols in example code. See
http://en.wikipedia.org/wiki/Foobar .

I'm not sure what you mean by lack of organization. Although maybe
adding a "Jump to" section on the top of each page could help figure
out what is listed on each page.
May 27 2011
parent reply Matthew Ong <ongbp yahoo.com> writes:
On 5/27/2011 7:13 PM, Andrej Mitrovic wrote:


 If there's missing documentation, file a bug report.


Will do that soon.


 Otherwise the docs are not a tutorial for the language. If there ever
 will be a tutorial that's hosted on the D website it will probably be
 in a section of its own.

 Foo/Bar are typical ways of naming symbols in example code. See
 http://en.wikipedia.org/wiki/Foobar .


1960s and early 1970s // Please note. It works for simple concept.
My first language was 1994/5. Perhaps generation gap.

Using one abstract(metavariable) idea to describe another abstract 
syntax concept. abstract + abstrac = abstract (not clear)
Perhaps Banking Account example or Vehicles or anything seen by user 
daily can communicate better. Hopefully that gives some idea.

If you notice, all my posting about problem unless is too simple, I do 
uses some thing solid/less abstract to communicate that.
This should help reader reading it and does not need to guess and guess.


 I'm not sure what you mean by lack of organization. Although maybe
 adding a "Jump to" section on the top of each page could help figure
 out what is listed on each page.


adding a "Jump to" section on the top of each page
Perhaps on the right hand side and each section is formatted with a 
table column like manner.



-- 
Matthew Ong
email: ongbp yahoo.com
May 27 2011
parent reply Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
I'm not sure how Vehicles or Bank Account is going to help describe
access modifiers. There's no connection, and will end up confusing the
reader. Foo and Bar are used when the focus is not on the semantics
but on the syntax of the language.

On the other hand, if you're going to explain concurrency you might
use Bank Account as a name, it could help explain things a little
better if there's an obvious connection (e.g. transactions between
bank accounts needs synchronization, etc..). But for simple examples
that just show the syntax of the language, I think foobar is ok.

If you know of any concrete examples that are confusing because they
use the foobar notation, feel free to list them in a bug report and
suggest any improvements you could think of.

Here's the link to bugzilla:
http://d.puremagic.com/issues/enter_bug.cgi?product=D , select
"websites" if it's a language documentation bug or "Phobos" if it's a
bug in the library documentation.

I care about documentation as much as you do, so I'll definitely look
at any bug reports for the docs.
May 27 2011
parent reply Matthew Ong <ongbp yahoo.com> writes:
On 5/27/2011 8:13 PM, Andrej Mitrovic wrote:


 that just show the syntax of the language, I think foobar is ok.


I totally agree, I wrote that I think. However, the problem are clearly
seen here at least:


C++ can understand others may not.
http://www.digitalmars.com/d/2.0/template.html
http://www.digitalmars.com/d/2.0/template-mixin.html
http://www.digitalmars.com/d/2.0/traits.html
http://www.digitalmars.com/d/2.0/statement.html#ScopeGuardStatement
What is that??

There are more such places, please ask someone new around you to feed back.


 I'm not sure how Vehicles or Bank Account is going to help describe
 access modifiers. There's no connection, and will end up confusing the
 reader. Foo and Bar are used when the focus is not on the semantics
 but on the syntax of the language.



end up confusing


Please use nonconfusing common example code that most people would have 
read about in most OOP concept book. Code should speak for itself to 
reflect the purpose of the syntax along with some commonly used 
semantics with the library or day to day coding.


Foo and Bar are used when the focus is not on the semantics but on the 
syntax of the language.


Yes, I can see what you are trying to do. Syntax without practical 
semantics are meaning less and some practical example does not give
a solid and clear understanding of what that syntax is for.

At a single glance and read, please tell me someone new will understand 
what template mixin, traits and scrope explained?

It should show what is that for, how is that better, do and do not, 
warning, conventions and others.Fundamental of linguistic design.

Hope that clear the doubt that D documentation approach is Not 
self-explaining to the reader even with very few statement outside the 
sample or on the sample code itself.

It is NOT JUST those pages listed here.

-- 
Matthew Ong
email: ongbp yahoo.com
May 27 2011
parent reply Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
On 5/27/11, Matthew Ong <ongbp yahoo.com> wrote:


 C++ can understand others may not.


Well, explaining the concept of operator overloading should be a
separate topic. People who know what operator overloading is will look
in the language docs to figure out the syntax and use it right away.

Doesn't Java have operator overloading? A lot of popular languages
except maybe C have it, I think.


 http://www.digitalmars.com/d/2.0/template-mixin.html


This could definitely be improved. There's too much foo's and bar's
intertwined with mixins.


 http://www.digitalmars.com/d/2.0/traits.html


Not sure what's wrong here.


 http://www.digitalmars.com/d/2.0/statement.html#ScopeGuardStatement


I think the point of those numbers was to make it easy to figure out
which statements were  executed in sequence. It doesn't demonstrate
where you would need a scope guard, so maybe another example could be
added or these ones rewritten a little bit.
May 27 2011
parent reply "Steven Schveighoffer" <schveiguy yahoo.com> writes:
On Fri, 27 May 2011 09:22:01 -0400, Andrej Mitrovic  
<andrej.mitrovich gmail.com> wrote:


 On 5/27/11, Matthew Ong <ongbp yahoo.com> wrote:


 C++ can understand others may not.


 Well, explaining the concept of operator overloading should be a
 separate topic. People who know what operator overloading is will look
 in the language docs to figure out the syntax and use it right away.

 Doesn't Java have operator overloading? A lot of popular languages
 except maybe C have it, I think.


Last I checked they do not.  It's why the String class has charAt instead  
of an equivalent opIndex.

-Steve
May 27 2011
parent reply "Jonathan M Davis" <jmdavisProg gmx.com> writes:
On 2011-05-27 06:31, Steven Schveighoffer wrote:

 On Fri, 27 May 2011 09:22:01 -0400, Andrej Mitrovic
 
 <andrej.mitrovich gmail.com> wrote:

 On 5/27/11, Matthew Ong <ongbp yahoo.com> wrote:


 C++ can understand others may not.


 
 Well, explaining the concept of operator overloading should be a
 separate topic. People who know what operator overloading is will look
 in the language docs to figure out the syntax and use it right away.
 
 Doesn't Java have operator overloading? A lot of popular languages
 except maybe C have it, I think.


 
 Last I checked they do not. It's why the String class has charAt instead
 of an equivalent opIndex.


LOL. Yeah. Java will never have operator overloading. That would be on the 
list of features that were considered unsafe. And I know plenty of folks who 
are against operator overloading for similar reasons. Java has a lot of great 
stuff going for it, but it's overly stripped down in terms of features in the 
name of simplicity and safety, and operator overloading is definitely one of 
those that didn't make it in and never will. IIRC, they can't even get 
closures yet, even though it's the feature that's being pushed for the most 
and the Java folks were at least planning on implementing it. They'll never 
get operator overloading.

- Jonathan M Davis
May 27 2011
next sibling parent reply Matthew Ong <ongbp yahoo.com> writes:
On 5/28/2011 1:24 AM, Jonathan M Davis wrote:

 On 2011-05-27 06:31, Steven Schveighoffer wrote:



 LOL. Yeah. Java will never have operator overloading. That would be on the
 list of features that were considered unsafe. And I know plenty of folks who
 are against operator overloading for similar reasons. Java has a lot of great
 stuff going for it, but it's overly stripped down in terms of features in the
 name of simplicity and safety, and operator overloading is definitely one of
 those that didn't make it in and never will. IIRC, they can't even get
 closures yet, even though it's the feature that's being pushed for the most
 and the Java folks were at least planning on implementing it. They'll never
 get operator overloading.

 - Jonathan M Davis


I remember if I am not wrong, C++ can do operator overloading and also 
overriding operator that also at child class. Sounded cool, but the more...
you heard that before haven't you... :)


closures yet


Semi-correct, Not within the standard syntax. But available also.
http://www.codeproject.com/KB/java/lambdajclosure.aspx

Does D have? Perhaps someone may give some URL

http://en.wikipedia.org/wiki/Inversion_of_control
Along side with spring framework?? That allow classes to be late binded 
via configuration in xml file.

Implementation techniques
    1. using a factory pattern
    2. using a service locator pattern
    3. using a constructor injection
    4. using a setter injection
    5. using an interface injection
    6. using a contextualized lookup

http://en.wikipedia.org/wiki/Aspect-oriented_programming
using http://en.wikipedia.org/wiki/AspectJ

There are many many extension because I think the bytecode allow such 
manipulations and not limited to the standard syntax of Java.

Perhaps something similar can be done with the Object file in D. :)

Yes... I am still a coffee(Java) addict. Sorry cannot stop that. Addict.
May need to take some 12 steps program... :)

-- 
Matthew Ong
email: ongbp yahoo.com
May 27 2011
parent Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
D has lambdas and closures and plenty of other things.

It doesn't have a lot of runtime-introspection though, it doesn't run
on a VM I'm affraid. :)
May 27 2011
prev sibling parent Jacob Carlborg <doob me.com> writes:
On 2011-05-27 19:24, Jonathan M Davis wrote:

 On 2011-05-27 06:31, Steven Schveighoffer wrote:

 On Fri, 27 May 2011 09:22:01 -0400, Andrej Mitrovic

 <andrej.mitrovich gmail.com>  wrote:

 On 5/27/11, Matthew Ong<ongbp yahoo.com>  wrote:


 C++ can understand others may not.


 Well, explaining the concept of operator overloading should be a
 separate topic. People who know what operator overloading is will look
 in the language docs to figure out the syntax and use it right away.

 Doesn't Java have operator overloading? A lot of popular languages
 except maybe C have it, I think.


 Last I checked they do not. It's why the String class has charAt instead
 of an equivalent opIndex.


 LOL. Yeah. Java will never have operator overloading. That would be on the
 list of features that were considered unsafe. And I know plenty of folks who
 are against operator overloading for similar reasons. Java has a lot of great
 stuff going for it, but it's overly stripped down in terms of features in the
 name of simplicity and safety, and operator overloading is definitely one of
 those that didn't make it in and never will. IIRC, they can't even get
 closures yet, even though it's the feature that's being pushed for the most
 and the Java folks were at least planning on implementing it. They'll never
 get operator overloading.

 - Jonathan M Davis


Actually Java has two operators overloaded that is + and += for strings, 
but that's nothing a user can take advantage of in his/her own 
implementations, it's basically part of the language. If one what's to 
use the JVM platform there's other alternatives available, like Scala or 
JRuby.

-- 
/Jacob Carlborg
May 27 2011
prev sibling next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2011-05-27 09:35, Matthew Ong wrote:

 Hi,

  From what I can see,...

 The documentation seems to be making something simple harder to
 understand with lots of noises added. It is scattered all over the
 places. Many information Seem like a lot of dark/unwritten known by only
 a few persons.

 1) There is No clear organizations. Associated to the syntax being
 describe. Like: what is the default encapsulation access modifier for
 class/struct/interface/enum/template/mixin/... where are they
 documented? There might be more similar broken/implied.

 2) When describing a concept with syntax there most if not all example
 uses foo/bar and not work/payment? (If you get the sideline grin)
 Doing some sort of Neural Linguistic Programming to 'suggest' dumping
 someone down? If documentation trying to make a fool out of readers so
 that they 'appear' to be experts? Or documentation are there to help
 developer code better. Forum is available, I am grateful for the people
 that has kindly shown me around with sample code.

 3) Is not making a new language purpose to make ease the developer mind
 so that they can be free to think about how to model business logic
 rather than be busy trying to figure out what is that strange thing for?

 4) Not much working example in the html documentaions and not
 centralise. Only code fragments, with lots of foo & bar again...

 Yes. I have seen:
 http://www.dsource.org/projects/tutorials/wiki/ArraysCategory
 http://www.dprogramming.com/tutorial.php

 Plenty more I would expect...

 True mastery is to make the complex model easy to understand not not
 simple one to be complex to understand.

 The best type of tutorial and documentation format I have seen so far
 and yet simple to understand are shown here.

 http://www.w3schools.com/php/php_operators.asp

 They designed it in a way that those poor junior developer can copy and
 paste and still have a working program.

 D might consider seriously and carefully how to rework the

 Yes. That URL is better than Java tutorial documentation.

 Yes, I am ranting. With good reasons. Hopefully for the best of D.


The documentation on the DigitalMars site is more of a language 
reference than a tutorial. It's probably not the best place to start but 
when you know the language is good to be able to look some odd syntax 
you rarely use.


-- 
/Jacob Carlborg
May 27 2011
parent reply Matthew Ong <ongbp yahoo.com> writes:
On 5/27/2011 7:27 PM, Jacob Carlborg wrote:

 On 2011-05-27 09:35, Matthew Ong wrote:
 The documentation on the DigitalMars site is more of a language
 reference than a tutorial. It's probably not the best place to start but
 when you know the language is good to be able to look some odd syntax
 you rarely use.


yes. I am aware, it is not a tutorial site. Lets compare that with 


Java
http://java.sun.com/docs/books/jls/third_edition/html/j3TOC.html
Well Organized and has detail interference. They even have implicit and 
explicit promotion documented.


http://www.willydev.net/descargas/CLICsharp.pdf
490 pages and well documented.

Go
http://golang.org/doc/go_spec.html
Short. But some organisation also.
No foo and no bar. Point, Split, Join, String...


organization but use the naming example similar to Go or something 

missing from D documentation. D has a larger than Java syntax set.

About tutorial.

Even the tutorial site is not as organized as the one shown there? 
Please have a click on the URL:
http://www.dsource.org/projects/tutorials/wiki/ArraysCategory
http://www.dprogramming.com/tutorial.php

Compare that to the Php,
http://www.w3schools.com/php/php_operators.asp

Please let me know which is easy to navigate and easy to read?

-- 
Matthew Ong
email: ongbp yahoo.com
May 27 2011
next sibling parent "Mike James" <foo bar.com> writes:
"Matthew Ong" <ongbp yahoo.com> wrote in message 
news:iro4gg$1763$1 digitalmars.com...

 On 5/27/2011 7:27 PM, Jacob Carlborg wrote:

 On 2011-05-27 09:35, Matthew Ong wrote:
 The documentation on the DigitalMars site is more of a language
 reference than a tutorial. It's probably not the best place to start but
 when you know the language is good to be able to look some odd syntax
 you rarely use.


 yes. I am aware, it is not a tutorial site. Lets compare that with Google 


 Java
 http://java.sun.com/docs/books/jls/third_edition/html/j3TOC.html
 Well Organized and has detail interference. They even have implicit and 
 explicit promotion documented.


 http://www.willydev.net/descargas/CLICsharp.pdf
 490 pages and well documented.

 Go
 http://golang.org/doc/go_spec.html
 Short. But some organisation also.
 No foo and no bar. Point, Split, Join, String...


 organization but use the naming example similar to Go or something better? 

 documentation. D has a larger than Java syntax set.

 About tutorial.

 Even the tutorial site is not as organized as the one shown there? Please 
 have a click on the URL:
 http://www.dsource.org/projects/tutorials/wiki/ArraysCategory
 http://www.dprogramming.com/tutorial.php

 Compare that to the Php,
 http://www.w3schools.com/php/php_operators.asp

 Please let me know which is easy to navigate and easy to read?

 -- 
 Matthew Ong
 email: ongbp yahoo.com


For a tutorial you would be better getting Andreis book

http://my.safaribooksonline.com/book/programming/d/9780321659538

This gives you a good grounding, and more, of the D 2.0 language.

A book about Phobos won't be forthcoming for a while yet until the library 
is fully realized (I fell into that trap with Tango + D1 :-) ).

-=mike=-
May 27 2011
prev sibling parent reply dennis luehring <dl.soluz gmx.net> writes:
Am 27.05.2011 14:08, schrieb Matthew Ong:

 On 5/27/2011 7:27 PM, Jacob Carlborg wrote:

  On 2011-05-27 09:35, Matthew Ong wrote:
  The documentation on the DigitalMars site is more of a language
  reference than a tutorial. It's probably not the best place to start but
  when you know the language is good to be able to look some odd syntax
  you rarely use.


 yes. I am aware, it is not a tutorial site. Lets compare that with


 Java
 http://java.sun.com/docs/books/jls/third_edition/html/j3TOC.html
 Well Organized and has detail interference. They even have implicit and
 explicit promotion documented.


 http://www.willydev.net/descargas/CLICsharp.pdf
 490 pages and well documented.

 Go
 http://golang.org/doc/go_spec.html
 Short. But some organisation also.
 No foo and no bar. Point, Split, Join, String...


 organization but use the naming example similar to Go or something

 missing from D documentation. D has a larger than Java syntax set.

 About tutorial.

 Even the tutorial site is not as organized as the one shown there?
 Please have a click on the URL:
 http://www.dsource.org/projects/tutorials/wiki/ArraysCategory
 http://www.dprogramming.com/tutorial.php

 Compare that to the Php,
 http://www.w3schools.com/php/php_operators.asp

 Please let me know which is easy to navigate and easy to read?



here, there is no big organisation behind, just a bunch of poeple, 
nearly all not paid for doing it - investing their sparetime to get D 
better and better --> YES - your talking mostly to sparetime developers here

all you can do - show us the problems, get to the point that everything 
is still growing, and that YOU can start imeditately by bringing in 
new/changed content - would be great
May 27 2011
parent reply Matthew Ong <ongbp yahoo.com> writes:
On 5/27/2011 9:16 PM, dennis luehring wrote:


 better and better --> YES - your talking mostly to sparetime developers
 here


I have some sense that is the case here because of different email 
domain from so many different coder. No wonder there does not seem to be 
properly organized. There is limited coherent among the document.


 all you can do - show us the problems, get to the point that everything
 is still growing,


That is not intentional document improvment. It sounded like ad-hoc 
mutations to me.
Please review how others has done the organization using the 3 links I 
posted. Get the some solid points on how those 3 are better at the top 
level. Before the next change took place within D.

Format of the documentation needs to be defined properly to make 
navigation and expectations easy.


that YOU can start imeditately by bringing in new/changed content - 


would be great
It is too early for me to do that as I am just 3 week in D.

Perhaps after I have ported over some of my own existing library written 
in Java. I have a better understanding, yes, I will try to contribute 
some sample code tutorial into the pool.

Perhaps a new newsgroup can be created for this purpose instead of
just bugzilla as a bug report. See this site from Puppy Linux.

http://murga-linux.com/puppy/
Powered by phpBB © 2001, 2005 phpBB Group
They documented the OS level help and documentation rather well and can 
be search online via web.


-- 
Matthew Ong
email: ongbp yahoo.com
May 27 2011
parent reply Jacob Carlborg <doob me.com> writes:
On 2011-05-27 16:18, Matthew Ong wrote:

 On 5/27/2011 9:16 PM, dennis luehring wrote:


 better and better --> YES - your talking mostly to sparetime developers
 here


 I have some sense that is the case here because of different email
 domain from so many different coder. No wonder there does not seem to be
 properly organized. There is limited coherent among the document.


 all you can do - show us the problems, get to the point that everything
 is still growing,


 That is not intentional document improvment. It sounded like ad-hoc
 mutations to me.
 Please review how others has done the organization using the 3 links I
 posted. Get the some solid points on how those 3 are better at the top
 level. Before the next change took place within D.

 Format of the documentation needs to be defined properly to make
 navigation and expectations easy.

  >that YOU can start imeditately by bringing in new/changed content -
 would be great
 It is too early for me to do that as I am just 3 week in D.


Maybe that's what just we need. Someone with almost no experience in D 
can look at the documentation with fresh eyes and better see what needs 
to be change to make it easier for people new to D.

-- 
/Jacob Carlborg
May 27 2011
parent David Nadlinger <see klickverbot.at> writes:
On 5/27/11 9:09 PM, Jacob Carlborg wrote:

 On 2011-05-27 16:18, Matthew Ong wrote:

 On 5/27/2011 9:16 PM, dennis luehring wrote:

[…]
that YOU can start imeditately by bringing in new/changed content -


 would be great
 It is too early for me to do that as I am just 3 week in D.


 Maybe that's what just we need. Someone with almost no experience in D
 can look at the documentation with fresh eyes and better see what needs
 to be change to make it easier for people new to D.


At least, it would be way more productive than uninformed language 
development suggestions… Don't get my wrong, Matthew, I'm sure nobody 
here minds beginner questions (after all, we have dm.D.learn solely for 
this purpose), but suggesting new constructs for a language one is not 
really familiar with is not likely to be very fruitful, even for 
experienced developers. To reply to your other two recent threads inline:

I don't quite see the point in introducing »runtime special tokens«, as 
you suggested, because the very essence of special tokens is that they 
are handled in a – well – special way by the lexer. What you are 
probably looking for instead are standard library functions (e.g. getpid()).

About your function hijacking question: Be assured that this isn't an 
issue in practice – aliasing in the base class implementations is only 
required to continue using other _overloads_ of an overridden method, 
not for any other methods of the class. The code examples you cited are 
generated, not written by hand, and e.g. in DWT's ByteArrayInputStream, 
not a single of the alias declarations is actually necessary – I suppose 
it was just the path of least resistance to always emit them to emulate 
the Java overriding/overloading rules.

Regards,
David
May 27 2011
prev sibling next sibling parent Alexander Battisti <battisti gmail.com> writes:
Just starting myself with D, I can second that.  This (
http://warpspire.com/talks/documentation/ ) explains much better than
I could, how important documentation is.


 The best type of tutorial and documentation format I have seen so far
 and yet simple to understand are shown here.

 http://www.w3schools.com/php/php_operators.asp


Have you seen CoffeeScript's documentation?
http://jashkenas.github.com/coffee-script/

Alexander Battisti

p.s. Having some extra time in the next few months, I would be glad to
help with improving the state of the documentation.
May 27 2011
prev sibling next sibling parent reply Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
Every other word in that presentation is  "Awesome". It looks like an
Apple advertisement.

Besides, we already have ddoc for generating documentation. And that
really only applies to Phobos, not the language docs.
May 27 2011
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 5/27/11 11:35 AM, Andrej Mitrovic wrote:

 Every other word in that presentation is  "Awesome". It looks like an
 Apple advertisement.


I got curious and clicked on a few referred links - which one are you 
referring to?

Andrei
May 27 2011
parent Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
On 5/27/11, Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> wrote:

 On 5/27/11 11:35 AM, Andrej Mitrovic wrote:

 Every other word in that presentation is  "Awesome". It looks like an
 Apple advertisement.


 I got curious and clicked on a few referred links - which one are you
 referring to?

 Andrei


I mean the presentation here: http://warpspire.com/talks/documentation/

So it's a documentation generator, big deal. Someone has to write that
documentation, and that's what matters the most imo. Not whether we
have fancy rounded borders around our code snippets (although that
doesn't hurt).
May 27 2011
prev sibling parent reply Matthew Ong <ongbp yahoo.com> writes:
On 5/28/2011 12:35 AM, Andrej Mitrovic wrote:

 Every other word in that presentation is  "Awesome". It looks like an
 Apple advertisement.

 Besides, we already have ddoc for generating documentation. And that
 really only applies to Phobos, not the language docs.


Alexander,

You sounded like a young chap, when was your first programming language, 
what year?

http://jashkenas.github.com/coffee-script/
Oh that format with running results popup format is great. That allow
clear understanding of both syntax, semantic and also results expected.

The example also uses
Classes, Inheritance, and Super

Animal, Horse, Snake, sam, tom;
Instead of just plenty of foo and bar??

If that is hard to be done in D, because it is a system application,
print screen in png good resolutions format can also be used.


If D is able to come up with some form of sandbox tutorial environment
http://golang.org/doc/playground.html
It might be possible as DMDscript is available, Not too sure if it is
100% same syntax as D, hopefully, it is.

People on the web can also try out and modify some code.
That will sure help some learning cycle.


-- 
Matthew Ong
email: ongbp yahoo.com
May 27 2011
next sibling parent reply Alexander Battisti <battisti gmail.com> writes:
 You sounded like a young chap, when was your first programming language,
 what year?


Basic and Logo on my Amstrad CPC 64 (around 1996?) ... so I am not
sooo young anymore, but thanks nonetheless :)
May 27 2011
parent Matthew Ong <ongbp yahoo.com> writes:
On 5/28/2011 1:09 AM, Alexander Battisti wrote:


 Basic and Logo on my Amstrad CPC 64 (around 1996?) ... so I am not
 sooo young anymore, but thanks nonetheless :)


My was turbo C++ on MS DOS 6.22 around 1995.
I think we might be in the same age range.

-- 
Matthew Ong
email: ongbp yahoo.com
May 27 2011
prev sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
 If D is able to come up with some form of sandbox tutorial
 environment http://golang.org/doc/playground.html


It's already been done, just with a few bugs. It runs real D
on code examples.

It will hopefully be merged with the next release.
May 27 2011
parent reply Matthew Ong <ongbp yahoo.com> writes:
On 5/28/2011 1:17 AM, Adam D. Ruppe wrote:

 If D is able to come up with some form of sandbox tutorial
 environment http://golang.org/doc/playground.html


 It's already been done, just with a few bugs. It runs real D
 on code examples.

 It will hopefully be merged with the next release.


Wonderful, suggest that to merge among the tutorial example along with
some trail example code like shown here.
http://jashkenas.github.com/coffee-script/
Or
http://www.w3schools.com/php/php_operators.asp

But please be properly formatted for the 1024x768 or 1280x800 or resolution.

That would really help someone new to learn D without much typing and 
trial and error.


-- 
Matthew Ong
email: ongbp yahoo.com
May 27 2011
parent reply KennyTM~ <kennytm gmail.com> writes:
On May 28, 11 01:19, Matthew Ong wrote:

 On 5/28/2011 1:17 AM, Adam D. Ruppe wrote:

 If D is able to come up with some form of sandbox tutorial
 environment http://golang.org/doc/playground.html


 It's already been done, just with a few bugs. It runs real D
 on code examples.

 It will hopefully be merged with the next release.


 Wonderful, suggest that to merge among the tutorial example along with
 some trail example code like shown here.
 http://jashkenas.github.com/coffee-script/
 Or
 http://www.w3schools.com/php/php_operators.asp

 But please be properly formatted for the 1024x768 or 1280x800 or
 resolution.

 That would really help someone new to learn D without much typing and
 trial and error.


You can check a sample in http://arsdnet.net/d-web-site/std_algorithm2.html.

See the thread 
http://www.digitalmars.com/d/archives/digitalmars/D/Try_it_now_134671.html 
for the discussed matter.
May 27 2011
parent Matthew Ong <ongbp yahoo.com> writes:
On 5/28/2011 1:31 AM, KennyTM~ wrote:

 On May 28, 11 01:19, Matthew Ong wrote:

 On 5/28/2011 1:17 AM, Adam D. Ruppe wrote:





 You can check a sample in
 http://arsdnet.net/d-web-site/std_algorithm2.html.


Ah... good idea. Very close to that.

Perhaps format like coffee using more interesting side by side 
comparison and with more writefln/writeln rather than assert.
Assert does not show anything visually.
Please place into the example also:
1)some code comment
2)more meaningful naming to explain the concept. avoid using something 
too generic as name.


 See the thread
 http://www.digitalmars.com/d/archives/digitalmars/D/Try_it_now_134671.html
 for the discussed matter.


Ah... Seem like I was not the person that gave such feed back before. Good.

-- 
Matthew Ong
email: ongbp yahoo.com
May 27 2011
prev sibling next sibling parent reply Alexander Battisti <battisti gmail.com> writes:
 Every other word in that presentation is =C2=A0"Awesome". It looks like a=


n

 Apple advertisement.


Then it obviously must have no value at all :)


 Besides, we already have ddoc for generating documentation.


I was not implying that D was lacking tools. I meant to say, that
documentation is - apart from being intrinsically valuable - an
important marketing tool for to the reasons shown in the "Apple
advertisement".
May 27 2011
parent Matthew Ong <ongbp yahoo.com> writes:
On 5/28/2011 1:01 AM, Alexander Battisti wrote:

 Every other word in that presentation is  "Awesome". It looks like an
 Apple advertisement.


 Then it obviously must have no value at all :)


 Besides, we already have ddoc for generating documentation.


 I was not implying that D was lacking tools. I meant to say, that
 documentation is - apart from being intrinsically valuable - an
 important marketing tool for to the reasons shown in the "Apple
 advertisement".


With some good sense of humor also. :)

-- 
Matthew Ong
email: ongbp yahoo.com
May 27 2011
prev sibling parent reply Jesse Phillips <jessekphillips+D gmail.com> writes:
Matthew Ong Wrote:


 Perhaps format like coffee using more interesting side by side 
 comparison and with more writefln/writeln rather than assert.
 Assert does not show anything visually.


I understand this position and that new programers of D find it odd that
examples don't have any output. However I have taking a liking to using assert
as it documents what is expected and there is no need for a comment. On top of
that it gets people familiar with assert and potentially using it in their own
code and the icing is that unittests are built in the same manner (you should
expect no output when everything is OK).

In fact I have an introduction to programming book which uses just assert for
most of the examples so far.

http://nascent.freeshell.org/programming/D/LearningWithD.pdf
May 27 2011
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 5/27/2011 12:02 PM, Jesse Phillips wrote:

 Matthew Ong Wrote:


 Perhaps format like coffee using more interesting side by side comparison
 and with more writefln/writeln rather than assert. Assert does not show
 anything visually.


 I understand this position and that new programers of D find it odd that
 examples don't have any output. However I have taking a liking to using
 assert as it documents what is expected and there is no need for a comment.
 On top of that it gets people familiar with assert and potentially using it
 in their own code and the icing is that unittests are built in the same
 manner (you should expect no output when everything is OK).



I tend to prefer the unambiguous:

     assert(1+2==3);

as opposed to the wordy and possibly misinterpreted:

     writeln(1+2); // should print 3
May 27 2011
parent reply Matthew Ong <ongbp yahoo.com> writes:
On 5/28/2011 3:27 AM, Walter Bright wrote:

 On 5/27/2011 12:02 PM, Jesse Phillips wrote:

 Matthew Ong Wrote:




Hi Walter,
With all due respect for creating such a advance programming tool.
How ever, there are plenty of rooms for improvement in helping new
person to learn and adapt D.



 I tend to prefer the unambiguous:
 assert(1+2==3);


Yes. That Logically correct. The author understands it, but does the new 
reader?

 as opposed to the wordy and possibly misinterpreted:
 writeln(1+2); // should print 3


No that is not wordy. What is being communicated here?

Proper comment and proper output.
writeln(1+2); // should print 3, numbers are added.

How about string? No comment and No output.
assert("abc"~"13"=="abc13");
People from Awk, C++, Java, ... read that totally different.
Please consider mindfully.

Please see my other post for more detail comment on the Book.
Sucessful book publisher has done the detail research on how to 
communicate and draw attentions from reader.

Do some simple survey with uni CP2 students and Year 1 working person.

Properly done, it will be a good advantage for D Community pick up rate.

-- 
Matthew Ong
email: ongbp yahoo.com
May 28 2011
parent reply Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
 Proper comment and proper output.
 writeln(1+2); // should print 3, numbers are added.


There's nothing proper about that. I've already fixed a bunch of
examples in the documentation because they had comments explaining the
results instead of using an assert. And the comments were wrong,
because it turns out that some part of the compiler has changed which
makes the output of some call to writeln() different. You can only
catch such cases if they're in an assert.

Every new D programmer should learn about assert. Once they've seen a
couple of examples there will be nothing ambiguous about seeing it in
the documentation again.

And you can't treat readers as if they're going to be newbies forever.
May 28 2011
parent reply "Steven Schveighoffer" <schveiguy yahoo.com> writes:
On Sat, 28 May 2011 09:16:37 -0400, Andrej Mitrovic  
<andrej.mitrovich gmail.com> wrote:


 Proper comment and proper output.
 writeln(1+2); // should print 3, numbers are added.


 There's nothing proper about that. I've already fixed a bunch of
 examples in the documentation because they had comments explaining the
 results instead of using an assert. And the comments were wrong,
 because it turns out that some part of the compiler has changed which
 makes the output of some call to writeln() different. You can only
 catch such cases if they're in an assert.


This is not really a reason -- examples are not compiled, unless you do it  
by hand.  i.e. even if these were asserts, you still have to compile them  
to find the problems.

A good reason, however, is that if you *do* hand-compile all the examples,  
finding the troublesome ones is much easier with assert (the same way unit  
test asserts are better than printing the results and comparing them  
manually).

We can separate this out into two basic cases: examples you compile, and  
examples you read.  In the latter case, either or writeln are just as  
informative.  For example, code in print conveys its meaning just as  
effectively whether you "show" the result or assert the result.  While  
reading, there's little way to prove the text is incorrect.

In compilable cases however, I see advantages to both.  In long examples,  
in which you want to know the thing works right, asserts are good.  They  
are informative, they are robust, and any mistakes made in the code will  
show up very loudly.

Writeln, however, has a distinct advantage over asserts -- it shows that  
something is happening.  If you have a 100 line example, full of asserts,  
and as a new-to-D programmer, you run the code, it's a little  
"not-quite-convincing" when you just get a command prompt back.  "Did I do  
something wrong?  Is this code supposed to do something?  Why don't I get  
any results?"  There's a reason the quintessential example is to print a  
string.

On the other hand, code that is full of asserts, with one printout at the  
end should be more than sufficient to give comfort that the thing is  
actually doing something, while using the advantages that asserts have.

So I'd say every example that is *not* a unittest can have at least one  
writeln in it.  The exception of course is unittest examples (which we may  
get some day).  You don't want any printouts while running unit tests  
unless something goes wrong.

I'd say all examples on D's web site should be treated like they are unit  
tests.  For the very good reason that they *should* be unit tested.  This  
is not a printed book or some beginner's guide, this is the spec, mistakes  
should not be ok.


 Every new D programmer should learn about assert. Once they've seen a
 couple of examples there will be nothing ambiguous about seeing it in
 the documentation again.

 And you can't treat readers as if they're going to be newbies forever.


If I were to write a new-to-D book, I'd use writeln exclusively for the  
first chapter to give them a sense of "OK, it works, I got it right".   
Then I'd introduce assert in a side-panel, and use asserts from then on,  
with printouts if needed.

-Steve
May 31 2011
parent Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
 If you have a 100 line example


There's a few (I think?) of those in the docs. There was one such
example for associative arrays which I've refactored a bit. And it
does use writeln, as it should.

The nice thing about that example is that it's at the end of the page,
showcasing how hashes can be used, so it's kind of a wrap-up of
everything learnt by the user who reads that page. Maybe we should
have more of these types of examples for each topic. In those cases
writeln makes a lot of sense.

Hopefully actual examples will be autotested one day. Otherwise they
can go out-of-date in-between releases.

Btw, TDPL introduces assert as soon as page 10. And the book is quite
assert-heavy overall, although writeln is used as well.
May 31 2011
prev sibling parent reply Matthew Ong <ongbp yahoo.com> writes:
On 5/28/2011 3:02 AM, Jesse Phillips wrote:

 Matthew Ong Wrote:


 Perhaps format like coffee using more interesting side by side
 comparison and with more writefln/writeln rather than assert.
 Assert does not show anything visually.


 I understand this position and that new programers of D find it odd that
examples don't have any output. However I have taking a liking to using assert
as it documents what is expected and there is no need for a comment. On top of
that it gets people familiar with assert and potentially using it in their own
code and the icing is that unittests are built in the same manner (you should
expect no output when everything is OK).

 In fact I have an introduction to programming book which uses just assert for
most of the examples so far.

 http://nascent.freeshell.org/programming/D/LearningWithD.pdf


Hi

The I have seen partial format of your book. If you plan to sell it,
I am not too sure what in publishing direction and format you are heading.


 Assert does not show anything visually.




Perhaps some other asserts that can? I am sure it is not too difficult 
for someone to make assert with writefln functions instead of purely 
sprintf + assert? mixin could solve this easily.


Yes. QA look for unit testing also. But they mostly just run to see if 
the console output, with data in and data shown.

JUnit (Please see this, for D sake)
http://junit.sourceforge.net/javadoc/org/junit/Assert.html
BTW, is there something like JUnit API in D?


Comprehensive
http://www.wrox.com/WileyCDA/WroxTitle/Ivor-Horton-s-Beginning-Java-2-JDK-5-Edition.productCd-0764568744,descCd-tableOfContents.html
Can be used for referencing once, you are middle ranged. Not too good 
for CP1 or CP2. But CP3.

Jump Start Format
http://www.informit.com/store/product.aspx?isbn=0672329433
Easy self-learning with working example.

Example Format
http://oreilly.com/catalog/9781565923713
But other Oreilly, Lots of words, but little code. Yes, it is more 
towards the experts field market.

Well organised Book Publisher
http://www.packtpub.com/sites/default/files/sample_chapters/7726-ajax-and-php-sample-chapter-5-ajax-form-validation.pdf?utm_source=packtpub&utm_medium=free&utm_campaign=pdf
Best, learning by building working project sample.
Personally I like packtpub as their format help the reader to take note 
of important things. Even with a glace, you can pick up good stuff that 
works.

Suggestion is to find out what type of book format people browse more in 
a community library. I suspect it will be very different for asia, eu, 
usa, japan, taiwan, south american.

There is no book to cover it all in software development. Just book and 
good reading that show people how to get stuff on the visual. That is 
what get the client acceptance document signed and payment done for 
project.


I understand that D is trying to be correct 100% of the time. Not to pop 
that bubble, it is proven to be impossible from historical track record 
of mankind. Or else, why do we have unit testing/coding standards?



-- 
Matthew Ong
email: ongbp yahoo.com
May 28 2011
parent reply Jesse Phillips <jessekphillips+D gmail.com> writes:
Matthew Ong Wrote:


 On 5/28/2011 3:02 AM, Jesse Phillips wrote:

 Matthew Ong Wrote:


 Perhaps format like coffee using more interesting side by side
 comparison and with more writefln/writeln rather than assert.
 Assert does not show anything visually.


 I understand this position and that new programers of D find it odd that
examples don't have any output. However I have taking a liking to using assert
as it documents what is expected and there is no need for a comment. On top of
that it gets people familiar with assert and potentially using it in their own
code and the icing is that unittests are built in the same manner (you should
expect no output when everything is OK).

 In fact I have an introduction to programming book which uses just assert for
most of the examples so far.

 http://nascent.freeshell.org/programming/D/LearningWithD.pdf


 
 Hi
 
 The I have seen partial format of your book. If you plan to sell it,
 I am not too sure what in publishing direction and format you are heading.


Well, it is a possibility, but in this small attempt I've discovered that I
suck at writing. I'll be working to make this complete, but it might be a very
short book and it most certainly won't be perfect.

If by format you mean the presentation, they yes I have no clue how to use
LatEx. And if you mean organization, well it is missing a lot but I think my
use of code samples, output, and explanation is pretty standard.

 

  >> Assert does not show anything visually.
 Perhaps some other asserts that can? I am sure it is not too difficult 
 for someone to make assert with writefln functions instead of purely 
 sprintf + assert? mixin could solve this easily.


Right, but I'm not claiming that it should.
 

 Yes. QA look for unit testing also. But they mostly just run to see if 
 the console output, with data in and data shown.


Yes, QA/everyone likes to see a scree full of green boxes, I do not know if
this adds value other than "Hey look we did something!" not saying that isn't
good. One thing I do think is silly is making the Unittest run before the
program, generally you either want to run tests or you want to run the program.
 

 JUnit (Please see this, for D sake)
 http://junit.sourceforge.net/javadoc/org/junit/Assert.html
 BTW, is there something like JUnit API in D?


I think there have been some of these. D's unittests are not meant to replace a
Unit test framework, they are meant to be used. A thing that you can put
anywhere and throw asserts into lowers entry barrier greatly.
 

 Comprehensive
 http://www.wrox.com/WileyCDA/WroxTitle/Ivor-Horton-s-Beginning-Java-2-JDK-5-Edition.productCd-0764568744,descCd-tableOfContents.html
 Can be used for referencing once, you are middle ranged. Not too good 
 for CP1 or CP2. But CP3.
 
 Jump Start Format
 http://www.informit.com/store/product.aspx?isbn=0672329433
 Easy self-learning with working example.
 
 Example Format
 http://oreilly.com/catalog/9781565923713
 But other Oreilly, Lots of words, but little code. Yes, it is more 
 towards the experts field market.
 
 Well organised Book Publisher
 http://www.packtpub.com/sites/default/files/sample_chapters/7726-ajax-and-php-sample-chapter-5-ajax-form-validation.pdf?utm_source=packtpub&utm_medium=free&utm_campaign=pdf
 Best, learning by building working project sample.
 Personally I like packtpub as their format help the reader to take note 
 of important things. Even with a glace, you can pick up good stuff that 
 works.
 
 Suggestion is to find out what type of book format people browse more in 
 a community library. I suspect it will be very different for asia, eu, 
 usa, japan, taiwan, south american.


I think bearophile's observation is pretty accurate. This will be an
experiment. I'm interested to find out if D can be taught in a manner that best
suites D, and if others find my style to be interesting.


 There is no book to cover it all in software development. Just book and 
 good reading that show people how to get stuff on the visual. That is 
 what get the client acceptance document signed and payment done for 
 project.


That would be silly, I can't cover all of software development and I wouldn't
want to.


 I understand that D is trying to be correct 100% of the time. Not to pop 
 that bubble, it is proven to be impossible from historical track record 
 of mankind. Or else, why do we have unit testing/coding standards?


If you aren't going to try for perfection you aren't going to get close.


Thank you for the feedback, I'll have to save your links for later review.
May 28 2011
parent Matthew Ong <ongbp yahoo.com> writes:
On 5/28/2011 10:10 PM, Jesse Phillips wrote:
Hi,


That would be silly, I can't cover all of software development and I 


wouldn't want to.
Great. I have seen publisher done that and those books are still on the
shelf. Too heavy to carry around even with a back pack. :)


 D's unittests are not meant to replace a Unit test framework,


The impression I got from the documentation is that D unittest is the
Unit Test framework. That is the case shown:

http://www.digitalmars.com/d/2.0/unittest.html

I was shocked to find only this. But DMD is just version 2.x so
I gave some space in my assessment.



 Thank you for the feedback, I'll have to save your links for later 


review.
Most welcome, thank you for listening also.

-- 
Matthew Ong
email: ongbp yahoo.com
Jun 03 2011