Re: Example within documentations of D seriously need some improvement.
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: on...@yahoo.com
Re: Example within documentations of D seriously need some improvement.
> 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.
Re: Example within documentations of D seriously need some improvement.
On Sat, 28 May 2011 09:16:37 -0400, Andrej Mitrovic 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
Re: Example within documentations of D seriously need some improvement.
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.
Re: Example within documentations of D seriously need some improvement.
> 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.
Re: Example within documentations of D seriously need some improvement.
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: on...@yahoo.com
Re: Example within documentations of D seriously need some improvement.
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: on...@yahoo.com
Re: Example within documentations of D seriously need some improvement.
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
Re: Example within documentations of D seriously need some improvement.
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 wrote: On 5/27/11, Matthew Ong wrote: http://www.digitalmars.com/d/2.0/operatoroverloading.html # people done 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
Re: Example within documentations of D seriously need some improvement.
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
Re: Example within documentations of D seriously need some improvement.
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
Re: Example within documentations of D seriously need some improvement.
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
Re: Example within documentations of D seriously need some improvement.
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: on...@yahoo.com
Re: Example within documentations of D seriously need some improvement.
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. :)
Re: Example within documentations of D seriously need some improvement.
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: on...@yahoo.com
Re: Example within documentations of D seriously need some improvement.
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.
Re: Example within documentations of D seriously need some improvement.
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: on...@yahoo.com
Re: Example within documentations of D seriously need some improvement.
On 2011-05-27 06:31, Steven Schveighoffer wrote: > On Fri, 27 May 2011 09:22:01 -0400, Andrej Mitrovic > > wrote: > > On 5/27/11, Matthew Ong wrote: > >> http://www.digitalmars.com/d/2.0/operatoroverloading.html # people done > >> 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
Re: Example within documentations of D seriously need some improvement.
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: on...@yahoo.com
Re: Example within documentations of D seriously need some improvement.
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: on...@yahoo.com
Re: Example within documentations of D seriously need some improvement.
> 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.
Re: Example within documentations of D seriously need some improvement.
On 5/27/11, Andrei Alexandrescu 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).
Re: Example within documentations of D seriously need some improvement.
> 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 :)
Re: Example within documentations of D seriously need some improvement.
> 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".
Re: Example within documentations of D seriously need some improvement.
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: on...@yahoo.com
Re: Example within documentations of D seriously need some improvement.
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
Re: Example within documentations of D seriously need some improvement.
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.
Re: Example within documentations of D seriously need some improvement.
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.
Re: Example within documentations of D seriously need some improvement.
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: on...@yahoo.com
Re: Example within documentations of D seriously need some improvement.
On Fri, 27 May 2011 09:22:01 -0400, Andrej Mitrovic wrote: On 5/27/11, Matthew Ong wrote: http://www.digitalmars.com/d/2.0/operatoroverloading.html # people done 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
Re: Example within documentations of D seriously need some improvement.
On 5/27/11, Matthew Ong wrote: > http://www.digitalmars.com/d/2.0/operatoroverloading.html # people done > 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.
Re: Example within documentations of D seriously need some improvement.
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 Google Go, Java, and C# Language reference. 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. C# 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... I am not asking D to be as heavy pages as Java or C#(use their) organization but use the naming example similar to Go or something better? But at least see in the TOC of Java and C# to see what is 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? it is not - compared to the java,c# world - but your totaly free to help 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
Re: Example within documentations of D seriously need some improvement.
"Matthew Ong" 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 > Go, Java, and C# Language reference. > > 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. > > C# > 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... > > I am not asking D to be as heavy pages as Java or C#(use their) > organization but use the naming example similar to Go or something better? > But at least see in the TOC of Java and C# to see what is 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: on...@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=-
Re: Example within documentations of D seriously need some improvement.
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: http://www.digitalmars.com/d/2.0/operatoroverloading.html # people done 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: on...@yahoo.com
Re: Example within documentations of D seriously need some improvement.
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.
Re: Example within documentations of D seriously need some improvement.
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 Go, Java, and C# Language reference. 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. C# 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... I am not asking D to be as heavy pages as Java or C#(use their) organization but use the naming example similar to Go or something better? But at least see in the TOC of Java and C# to see what is 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: on...@yahoo.com
Re: Example within documentations of D seriously need some improvement.
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: on...@yahoo.com
Re: Example within documentations of D seriously need some improvement.
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
Re: Example within documentations of D seriously need some improvement.
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.
