D: A language without focus

[Derek Parnell]

On Thu, 27 Apr 2006 06:15:39 +0000 (UTC), gabe wrote:

> First: The Build Mechanism
> I've tried to play around a little with Build, and I think to a certain extent
> it's a fine tool.  

Thanks. You do realize that this tool was not written by, or with the help
(or blessing) of DigitalMars. I wrote it because I was tired of maintaining
makefiles.

> What it lacks, I feel is not so much the ability to compile a
> series of programs but to really bring the end product together for users.

The Build tool has one purpose - to build a target file - either an
executable or library, depending on your needs. It is not designed to
generate documentation or install packages. KISS.

>   To
> clarify: what build doesn't really seem to do is build in user-friendliness into
> the libraries.  To a large extent, I think this more the fault of documentation
> than of Build.

See above. But what do you actually mean by the phrase "build in
user-friendliness into the libraries"? How can a tool like Build improve
the documentation content of the libraries? The formatting of the API
documentation is very flexible and can generate decent docs. 

(However, if Walter does add a method of creating indexes and Table of
Contents inside Ddoc soon, I might just add this to Build.)

>  In my idea of a build tool, 

That depends on what you are trying to build.

> the documentation is far more
> succinct and far more powerful; it leverages the native unicode support of D
> against XML.  Now, I know XML is everyone's favorite language to hate, as it
> quickly becomes quite complicated if not done well, but I feel that by using a
> basic and standardized syntax, D could quickly develop a usable (online)
> documentation system that exists in real-time with the development code itself.
> Allow me to elaborate with the following, very rough example

Allow me to Ddoc-ify your example code ...

---D source---

  /**
  $(doc $(lang(en_us),
  $(author $(name Danger Duck), $(date 01.12.07), $(license GPLv3))
    A fake variable passed to secure this message against flame

    params: 
     sec_uid = A security user identifier.

    returns: $(link util.fire.safety, FlameRetardantSuit) to protect user
             against singing

    $(example example1,
      Suit s = Suit.getRetardantSuit(my_long_security_id); /* pass in
unique id*/
      s.buttonUpItsGonnaGetHotInHere(); /* Lock yourself in the vault */
      s.waitForAllClear(clear_handler); /* Whew!, saved my tail feathers
again! */
      s.divest(); /* release the lock */
    )

   $(tutorial
    You have to know what you're doing when you use this object.  Put it on
too soon, and you may overheat and cook your own goose.  Put it on too
late, and those henpecked farmers may get your gizzard.  As you can see
from this $(local example1, example) the feathers are really flying.  Use
it carefully, though, and it'll all be like water off a duck's back.

 I apologize for all the fowl phrases.
    )

  )
**/
--- end D ---

> As you can see, it's possible to implement documentation at a level that can be
> directly transformed into any number of kinds of documentation.

Just as one can do with Ddoc.

>   You could
> publish the API and the examples on the Web; you could publish a library
> reference in PDF; you could distribute a localized tutorial in every language
> imaginable.  The possibilities, frankly, for brining in people form around the
> world are virtually limitless.  I know that this probably seems like way too
> much documentation for a single method, but I think the idea is essentially
> there -- it just has to be mined efffectively.

Yeah, like I said. Ddoc is designed with that very functionality in mind.
 
> Second:
> ... I would propose a two-tiered solution ...

I like where that idea is going. 


> One last thing before I slip off to bed: I really want to rally around an open
> source license for this project, particularly one that strives for complete
> transparency. 

The only thing that is not transparent is the DigitalMars compiler
back-end; the part that converts the IL into optimized machine code. And
this is mainly because of historical reasons I believe. Anyone is free to
develop an open source back end if they want a different implementation of
the compiler. However, the language itself is not 'closed' even though the
text of the DigitalMars specification is copyrighted.

-- 
Derek
(skype: derek.j.parnell)
Melbourne, Australia
"Down with mediocracy!"
27/04/2006 4:20:33 PM