• Scott S. McCoy (45/45) Mar 30 2008 So while D 2.0 is trying to solidify, I'm curious as to whether any
• Walter Bright (4/22) Mar 30 2008 I originally thought that would be a very useful idea. It turns out not

"Scott S. McCoy" <tag cpan.org> writes:

So while D 2.0 is trying to solidify, I'm curious as to whether any
thought has been given to removing features which are infrequently used,
or adding features to help enable adoption for business programming.  In
the area of documentation, I'm not thoroughly convinced the compile html
feature is very useful.

I understand the concept of being able to prove expressions included in
papers, and so on, as correct by compiling and executing them directly.
I can't help but notice, however; that very few articles and papers
actually include complete and coherent programs as the culmination of
their examples.  A lot of the time, papers include many small fragments
of code.  And all too often, these small fragments do not collate to
provide a single functioning program.  I should mention I don't find
this as a short coming of the authors work, in any way.  Many times,
including a "main" is relatively useless...likewise, including the
import statements to show where "writefln" comes from, for instance, is
just line noise and doesn't equate to much for the reader of the
document.

This being the case, I can't imagine that many people have found the
ability to compile HTML extracting the D source code from it is very
useful.  So can we just forget that happened and remove it from D
2.0?  :-)

Further, I think a more elaborate documentation mechanism is thoroughly
appropriate.  I do like D's attempt to provide a documentation syntax
that does not make too many assumptions about the output format, doing
things like not including HTML markup as a part of the standard.  This
is fine and dandy, but some intermediate formatting would be a useful
feature, and D's incredibly light weight documentation comments do not
enable this.  Similarly cross-referencing is critical for documentation
as far as I'm concerned, but D's documentation syntax doesn't allow this
as well.  Since you can link to a normal URL from just about anywhere, I
don't think URLs should be omitted (I cross reference PDFs via HTTP
quite regularly).  When I write documentation in Java, it's chock-full
of { link} statements which refer the reader to the location of the
information I do not wish to repeat.  Some formatting and cross
referencing features to enable richer documentation would be very useful
features, in my opinion, and I'd like to see them added.

Not to steer everyone off of the const topic...because that needs to be
resolved once and for all...  But just to point out a few of the short
comings of D where it could put itself in a position to feel a lot more
professional, and thus improve its ability to be adopted.  And I wish
nothing but for D to be adoptable, so maybe I can find a day job working
with it some day and steer myself clear of all of these goddamn java
weenies in business software.

Cheers,
    Scott S. McCoy

Walter Bright <newshound1 digitalmars.com> writes:

Scott S. McCoy wrote:
 This being the case, I can't imagine that many people have found the 
 ability to compile HTML extracting the D source code from it is very 
 useful.  So can we just forget that happened and remove it from D 2.0?  :-)

I originally thought that would be a very useful idea. It turns out not 
to generate any interest, so it could probably be removed.

 Further, I think a more elaborate documentation mechanism is thoroughly 
 appropriate.  I do like D's attempt to provide a documentation syntax 
 that does not make too many assumptions about the output format, doing 
 things like not including HTML markup as a part of the standard.  This 
 is fine and dandy, but some intermediate formatting would be a useful 
 feature, and D's incredibly light weight documentation comments do not 
 enable this.  Similarly cross-referencing is critical for documentation 
 as far as I'm concerned, but D's documentation syntax doesn't allow this 
 as well.  Since you can link to a normal URL from just about anywhere, I 
 don't think URLs should be omitted (I cross reference PDFs via HTTP 
 quite regularly).  When I write documentation in Java, it's chock-full 
 of { link} statements which refer the reader to the location of the 
 information I do not wish to repeat.  Some formatting and cross 
 referencing features to enable richer documentation would be very useful 
 features, in my opinion, and I'd like to see them added.

You can use $(LINK2 url, comment) to link things in Ddoc.