gabe wrote:

> 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.

I agree. But there is no need to actually write documentation in xml format, which is unbelievably painful to use. Writing it in Ddoc format is pretty simple, and Ddoc's output can be automatically transformed into XML by providing a different set of ddoc macros.

gabe wrote:
> 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.  Not only does this really promote a sense of sharing and
> community, but I feel that it also gives newcomers and old hackers some ideals
> to really identify with.  To that end I would suggest the GPL as the starting
> point -- possibly even liscenesed under some kind of dual GPL/LGPL liscense.
> This kind of transparency, I feel, really invites people to the table in an
> egalitarian and communal way.  (Not to mention the fact that putting it under
> the GPL opens up the floodworks for linking into other GPL code -- and there's
> tons of it.)

The license for Phobos is in one of the following forms:

1) public domain

2)
/*
 *  Copyright (C) 2006 by [your name]
 *  Written by [your name]
 *
 *  This software is provided 'as-is', without any express or implied
 *  warranty. In no event will the authors be held liable for any damages
 *  arising from the use of this software.
 *
 *  Permission is granted to anyone to use this software for any purpose,
 *  including commercial applications, and to alter it and redistribute it
 *  freely, subject to the following restrictions:
 *
 *  o  The origin of this software must not be misrepresented; you must not
 *     claim that you wrote the original software. If you use this software
 *     in a product, an acknowledgment in the product documentation would be
 *     appreciated but is not required.
 *  o  Altered source versions must be plainly marked as such, and must not
 *     be misrepresented as being the original software.
 *  o  This notice may not be removed or altered from any source
 *     distribution.
 */

I think that covers it. It's open source, and far less restrictive than the GPL.

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

gabe wrote:

> I've been reading these posts for a while now, and going over the documentation, and discovering some of the tools, and a few things have jumped out at me about the D language and the D community:

You absolutely has given this thought, but have you tried the language? If you had participated at least some in the discussions around here, you would have discovered that unlike Java, D isn't backed by a huge corporation that wants to take over the world, more like the mad professor (no insults intended Walter ;) who wants to take over the world.

> 
> Arrow One: The Message

You are right, D's message is somewhat unclear, and it has been discussed whether D should get a strategy for market deployment. Possibly, but D is still under development, and it turns out it has so much promise that we're not really sure where it'll end.

Hmm, I guess you really talked about documentation, and it's true, it mostly
sucks. But then it is so much more fun coding D than writing docs for
it! :D

> 
> Arrow Two: Liscenses.

Not any issue IMHO, the liscenses are circumventable, most libraries available open source, we have GDC which is a fully open source compiler, and almost nothing is licensed in a way that would prevent it from being used in a commercial projects (which already exists in several locations).

> 
> Arrow Third: Solidarity and conformance.

While I'd like coding standards and such, those following D are not particularly homogenic in their thoughts on the matter. Just try to read a couple of the project internal style discussions over at DScource. And many ppl actually don't like such conventions, so restrict too much and you might push away some of the small group already committed to D.

> 
> Exclamation Solutions:
> I would like to get involved in the D community in developing the tools
> that will make D a truly great language. To make that possible, however,
> we need to add a centralizing force and focus to the disparate goals of
> the project. First, we need to design some kind of mission statement --
> something that uniquely defines our goals as a community and as a group of
> programmers devoted to making D a better language for everyone to use.
> Second, we need to decide on some goals -- goals that will help us realize
> our mission by making it easer for people to come to D from other
> languages (or even there first language!). Third, we need to organize
> ourselves into groups that can work on aspects of the mission and can
> communicate easily to one another. This means that we need redundancy in
> projects (so that if someone leaves, someone else can take over),
> democratization across the group (so that API's and tools can have
> community input), and distributied responsibilites for all members (so
> that each person feels that they belong through to the group -- not merely
> because they say they do, but because they have earned the respect and the
> trust of their fellow members). In short, D should be a language where the
> community that bands around it is one of openness, respect, and excited
> collaboration.
> 
> I would like to post some more ideas about this, and I'd like to start organizing those people who are interested in joining together. I'd like to hear back from the community about this. I'd like to hear back from people excited about making D the best possible language it can be -- and making programming in D an absolute joy.
> 
> I look forward to hearing from you!
> _________________
> New to the land of D, but I like the look of the place.
> -Gabe

Similar suggestions has been made before, I think it's 2+ years now since I made mine. Anyway, I also think it's needed at some point, but doubt it can be pulled off already now. I wouldn't mind you trying though, but for me to follow, you would have to show a genuine interest in the language (preferably by helping out an existing project, and it would be wonderful if this would actually be documentation.)

It is also fairly common to disclose your real name here, and preferably at least type of occupation and previous experience. I'd like to know who drives any car I'm a passenger in.

When that is said, feel free to post any preliminary documents on whatever subject, I'd very much like to see them.

--
Lars Ivar Igesund
blog at http://larsivi.net
DSource & #D: larsivi

Walter Bright wrote:

> The license for Phobos is in one of the following forms:
> 
> 1) public domain
> 
> 2)
> /*
>  *  Copyright (C) 2006 by [your name]
>  *  Written by [your name]
>  *
>  *  This software is provided 'as-is', without any express or implied
>  *  warranty. In no event will the authors be held liable for any damages
>  *  arising from the use of this software.
>  *
>  *  Permission is granted to anyone to use this software for any purpose,
>  *  including commercial applications, and to alter it and redistribute it
>  *  freely, subject to the following restrictions:
>  *
>  *  o  The origin of this software must not be misrepresented; you must not
>  *     claim that you wrote the original software. If you use this software
>  *     in a product, an acknowledgment in the product documentation would be
>  *     appreciated but is not required.
>  *  o  Altered source versions must be plainly marked as such, and must not
>  *     be misrepresented as being the original software.
>  *  o  This notice may not be removed or altered from any source
>  *     distribution.
>  */
> 
> I think that covers it. It's open source, and far less restrictive than the GPL.

If you want to make things easier/shorter when talking with Open Source guys, this license is commonly known as the "zlib / libpng license"...

http://www.opensource.org/licenses/zlib-license.php


However, for DMD 0.154 it is not entirely true. There are still some
exceptions to this rule, mostly for the old Synesis Software modules:

http://www.prowiki.org/wiki4d/wiki.cgi?PhobosLicenseIssues

As many have pointed out, std.loader and std.recls needs to be fixed.
My own suggestion is to rewrite std.loader, and to drop the std.recls ?

--anders

Walter Bright wrote:
> Probably the biggest problem you mentioned is the documentation. Fortunately, though, we now have Ddoc. I've been converting more of the older documentation files over to Ddoc format, and discovered what I expected: every one of the module documentation files either:
> 
> 1) did not mention some of the functions
> 
> 2) documented functions that did not exist
> 
> 3) had documentation at odds with the code comments for the same function
> 
> Ddoc, while not terribly sophisticated, is good enough to use, and it offers an enormous step forward in making it easy to write and keep up to date the documentation. It easily cuts the work in half, maybe more, and it certainly makes it easy to enforce a common look & feel to the documentation.
> 
> Anyhow, I hear you. I welcome your help in any way you feel you can best contribute.

Really? If this is really true, and you welcome help, what shall we do? How is one supposed to help you if you do not have a list of things we can help you with?

On Thu, 27 Apr 2006 00:31:12 -0700, Kyle Furlong wrote:

> Walter Bright wrote:
>> Probably the biggest problem you mentioned is the documentation. Fortunately, though, we now have Ddoc. I've been converting more of the older documentation files over to Ddoc format, and discovered what I expected: every one of the module documentation files either:
>> 
>> 1) did not mention some of the functions
>> 
>> 2) documented functions that did not exist
>> 
>> 3) had documentation at odds with the code comments for the same function
>> 
>> Ddoc, while not terribly sophisticated, is good enough to use, and it offers an enormous step forward in making it easy to write and keep up to date the documentation. It easily cuts the work in half, maybe more, and it certainly makes it easy to enforce a common look & feel to the documentation.
>> 
>> Anyhow, I hear you. I welcome your help in any way you feel you can best contribute.
> 
> Really? If this is really true, and you welcome help, what shall we do? How is one supposed to help you if you do not have a list of things we can help you with?

For example Walter, can I send you Phobos modules with improved documentation in them and no source code changes? What is the method you use to accept Phobos source code changes? I presume you do a line-by-line analysis and manually incorporate those lines you wish to.

-- 
Derek
(skype: derek.j.parnell)
Melbourne, Australia
"Down with mediocracy!"
27/04/2006 6:03:13 PM

gabe wrote:

> Second:
> I've heard back from a few people about having a small core library.  I can
> certainly respect that: coming from Java, I know what it feels like to have a
> glut of options.  On the other hand, one of the undeniable draws for a language
> is a substantial library of well-tested code.  The functionality of a language
> is, in this sense, directly reflected in the composition of its libraries.  To
> that end, I would propose a two-tiered solution.  On the first tier, there sits
> two basic libraries: 'lang' and 'sys'.  Unlike Java, which hides much of the
> implementation details of the system, D users should be allowed the freedom to
> deal directly with the hardware and the underlying system when needed.  For this
> reason, the sys and the lang packages will supply all of the basic functionality
> needed for D to run in any environment.  This should especially appeal to
> systems programmers and library implementers, as one can hide a good deal of
> existing c code behind some carefully constructed interfaces or superior
> packaging.  The 'lang' package, in particular, needs the 'sys' libs in order to
> deliver all of the low-level coding required by each operating system, thus, I
> believe, releiving even some of the lower details from language implementors.

Q: How is this different from how D things currently work ?
We have Phobos/Ares ('lang') calling the C library ('sys')

All that is needed to use C libraries is to write an import
module, for C++ you need to export it as extern "C" {} first.

So I think it already works this way, it's how I am using it.

> It should be the case that these two packages are automatically searched and
> compiled into any running program, though the top level DPATH may only refer to
> '/usr/include/d/', or whatnot.  

The standard install of GDC uses e.g. /usr/include/d/3.3.6,
(where the version signifies the GCC that it was built with)
for including the std Phobos/runtime files from the compiler.

It used to search /usr/include/d as well, for user libraries,
but I think it doesn't anymore (had to add: -I/usr/include/d)
I think /usr/include/d is good, the same as /usr/include/c++

The C library is used automatically, and then it adds: -lphobos
(DMD uses "gcc" to link, while GDC normally uses "gdc" there too)

So both the C and D libraries are searched and included already ?

> The second part of this teir delivers everything else that the core library
> lacks, including complicated IO, data structures, utilities, ui components, and
> parsers.  I've given a rough outline of what the library might looklike below.
> Of course, much of my model liberally samples (i.e. outright steals) from the
> Java and C# library implementations.  This is the way I feel that it should be
> -- each language should stand on the shoulders of the one that came before it --
> and I think each of those languages are quite good at packaging together
> disparate pieces.  Of course, we wouldn't import from d.xxx -- we can drop the
> 'd.' syntax entirely once the compiler supports native library builds; I always
> did resent the whole 'import java....' fiasco.  This seems to be an ok solution
> as long as we make sure that we don't conflict with URL domains in these
> top-level directories.  

Adding all those features to *one* single library / project,
would make it quite heavy and rather big - don't you think ?

But Mango does cover a fair lot of the "server" ones now...
DWT was supposed to cover GUI, but it seems to be in trouble.

> ----- ERL - Extended Runtime Library ------
[...]
> os (or 'kaos', for nameing conflicts [kernel and o/s] -- hsa mythic overtones)
> posix
> c
> windows
> c
> ..
> com
> ..
> dotnet
> linux
> c

GDC is currently divided into Windows and Unix (*not* Posix !),
which I think is an improvement over what DMD has (only linux)

std.windows.*
std.unix.*

std.c.windows.*
std.c.unix.*

The different Unix platforms are available too, mostly empty:
linux/darwin/freebsd/cygwin/aix/solaris, plus any future ones.

> ui curses
> thea (D language graphical system based on the qt framework)
> opengl
> window
> ..
> ..

Another UI framework ? Didn't know there was a working Qt->D wrapper ?
(then again the DIUP port looks promising, for any simple interfaces)

> 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.  Not only does this really promote a sense of sharing and
> community, but I feel that it also gives newcomers and old hackers some ideals
> to really identify with.  To that end I would suggest the GPL as the starting
> point -- possibly even liscenesed under some kind of dual GPL/LGPL liscense.
> This kind of transparency, I feel, really invites people to the table in an
> egalitarian and communal way.  (Not to mention the fact that putting it under
> the GPL opens up the floodworks for linking into other GPL code -- and there's
> tons of it.)

But many people hate the GPL with a passion... So a common solution is a
dual GPL/proprietary license (like DMD), or a BSD license (like Phobos)

And both Public Domain and LGPL/wxWidgets licenses are used for some big D existing projects, too. (e.g. MinWin, wxD) There's lots of options...

--anders

Derek Parnell wrote:
> On Thu, 27 Apr 2006 00:31:12 -0700, Kyle Furlong wrote:
>> Walter Bright wrote:
>>> Anyhow, I hear you. I welcome your help in any way you feel you can best contribute.
>> Really? If this is really true, and you welcome help, what shall we do? How is one supposed to help you if you do not have a list of things we can help you with?
> 
> For example Walter, can I send you Phobos modules with improved
> documentation in them and no source code changes? What is the method you
> use to accept Phobos source code changes? I presume you do a line-by-line
> analysis and manually incorporate those lines you wish to.


On any Phobos changes, yes, I do a line by line check on any changes, and do a manual merge.

Two areas that could use big improvements are in the Ddoc comments and in the unit tests. For Ddoc in particular, usage examples for every function are needed.

For unit tests, enough needs to be there to get 100% coverage as verified by the D coverage analyzer. Having 100% coverage means that it's much easier to improve the libraries without slipping into reverse.

I know there isn't much glory in either of those two tasks, but Ddoc and the D coverage analyzer make them much easier, and they make the difference between a professional and an amateur project.

gabe wrote:

> In article <e2pgfg$4s3$1@digitaldaemon.com>, nick says...
>>
>>Sounds to me as though you are really eager to have D1.0 right this moment and you are frustrated with all the things that aren't working just the way you like them.
>>
> 
> Well, you're only partially right about that.  I do have some
> dissapointment
> that things don't exactly 'work'.  I think that anything that doesn't just
> 'work' for people coming to the language (or even working in it for a long
> time), tends to make D look inflexible and amaturish compared to other
> efforts. That is not to say that D is in any way either of those things --
> I think it has the potential to be very robust and quite user-friendly,
> but in order for the language to really succeed, you're going to have to
> convince more than just me. In order to succeed, you're going to have to
> convince all the other beginning, 10 cent hackers out there that D is a
> language of the future -- that it HAS a
> future -- at the center of a stable and growing community.  All this feeds
> into
> the notions that I outlined in my first message.  Design a system -- not
> just part of the language -- to foster growth and stability, and people
> will search
> YOU out, and not the other way around.  The keys to that system revolves
> around finding what is necessary within the community and then designing
> toward those goals.

I wonder why I didn't see this message the first time around... Anyway, I got my morning coffee now :)

Your thoughts are all sound, but the community IS building what it needs. As I said in my last post about Java (which applies to C# too), the infrastructure at the bottom there is NOT created by the community, but by the backing corporations. Which is why D still might end up as you envision, but it will take time :)

> 
> So, with that in mind, let me offer up some ideas that I have been ruminating upon.
> 
> First: The Build Mechanism

Build is an extremely powerful tool that I in general find well documented, but it is a command line tool, which probably is not whay you have in mind? But build should be easily usable from an IDE (and I think it is used in several already).

> 
> ---D source---

Please no XML in the source code, it is NOT easily readable (or writable). As has been said DDoc already fills this space (although it still could be improved) and it is possible to make additional tools to process the output into a fullblown Javadoc style documentation, or maybe something even better. CandyDoc which can be found under the Helix project at DSource is a starting point for what is possible.

> 
> Second:

> ------ BRL - Basic Runtime Library ------
> 
> ----- ERL - Extended Runtime Library ------

I like these ideas (it is not as if they haven't been suggested before), but I agree with Anders in that the BRL part of it is mostly there, he suggests Phobos, I think Ares got it even clearer, although it is not as complete yet.

As for the ERL, I think that will be much more difficult to get right, although it would be nice to have a "standard" that could be shipped with the compiler. Walter already has suggested to have a standard GUI, and other packages might follow. I guess if we as a community actually can agree on a setup, he might include it all.

The reason I think it might be difficult, is because D in itself gives us many more possibilities than VM based languages such as Java and C#, and because we might care even more about speed, we probably will pick and choose the right library for us even more than others do, similar to what happens in the C/C++ world.

Oh, and AFAIK, an effort to make a Qt inspired library in D has just been started :D Just to give is just a tiny bit more choice ;) Or possibly because someone got tired of hearing about how good Qt is and why it should be ported to D...

--
Lars Ivar Igesund
blog at http://larsivi.net
DSource & #D: larsivi