Newbie to D initial suggestion

[Edward Diener]

Walter Bright wrote:
> Edward Diener wrote:
>> I have a basic initial suggestion, as I am persuing the D pdf dcument 
>> I downloaded in order to understand of what the language consisted. 
>> The basic suggestion regards documentation for D itself. I believe the 
>> most important thing for getting others to be interested in a new 
>> programming language is the unglamorous chore of presenting the 
>> documentation for that language to others. While the pdf documentation 
>> I am reading is adequately thorough, I have a few suggestions:
> 
> I agree with you, but the current problem is that the pdf files need to 
> be manually created, and they fall further and further out of date. What 
> needs to be done is to be able to automatically generate a pdf from the 
> web site source material.

Perhaps some intermediate format like Docbook will allow both HTML and 
PDF to be generated from the same basic source. Boost uses a BoostBook 
or better even a QuickBook, although I have encountered endless problems 
as an end-user building Boost documentation form the SVN latest source 
tree, but I think this has much more to do with their impenetrable bjam 
Boost build system than the failings of the Docbook inherited document 
style.

Just a suggestion to make it easier to generate pdf files for 
downloading and offline reading.

> 
>> 1) A link to the downloaded documentation for D should be almost the 
>> first thing a viewer should see when they click on the D portion of 
>> the Digital Mars web site. It should be front and center. I realize 
>> there is a separate Language link on the left hand side which takes me 
>> to an online set of pages which explain D and I realize that somewhere 
>> down on the initial page there is a line which reads "This document is 
>> available as a pdf" with a link on that final word, but I think this 
>> is still too indirect. The normal reaction to any new language is to 
>> download the documentation detailing that language so that it can be 
>> read and/or printed at the end-user's leisure.
> 
> I agree, the front page needs to be revamped.
> 
>> 2) Since D is highly related to C++ there should be a document for C++ 
>> programmers detailing the differences between D and C++, which again 
>> is downloadable almost immediately from the main web page of D. I did 
>> not find any such document although there is occasional mention of 
>> these diferences in the pdf document I downloaded.
> 
> http://www.digitalmars.com/d/2.0/cpptod.html
> http://www.digitalmars.com/d/2.0/ctod.html
> http://www.digitalmars.com/d/2.0/pretod.html

Thanks, others have pointed out to me these links.

I know it is extra work for you but if the main documentation just had 
an appendix which linked back to places in each section where C++ and D 
differed ( and in some places I realize it would just say the entire 
section ) that would be a great boon for C++ programmers interested in 
D. In your links just above you are not really covering all of the 
differences and an experienced C++ programmer coming to D would 
naturally like to skip all of the same areas of the two languages and 
just learn the differences from the main documentation source.

> 
>> 3) There is evidently a version 2.0 and above of D. Perhaps it is not 
>> meant for anybody to become interested in this version who is just 
>> attempting to learn what D is about, but the complete lack of any 
>> documentation which I could find about this version and/or its 
>> difference from the 1.0 version is not a good thing.
> 
> I agree, but for now, http://www.digitalmars.com/d/2.0/changelog.html 
> has the information.

OK, I see it. Hopefully you can piece together something better once 2.0 
is ready for prime time.

> 
> 
>> Now I will continue to read on about D at my leisure, and see if I am 
>> interested in pursuing my initial interest in it. If I have any 
>> general suggestions about the language I hope they will be taken in 
>> the spirit of things intended to improve things rather than as an 
>> antagonism to the ideas presented there.
> 
> No problem. It's good feedback.

There is some more to come, based on specific items, but D is 
interesting and I sympathize with your goals in creating it.