retard wrote:
> 3. these other systems also support generating correct, conforming HTML/
> XML/TeX/PDF/MAN/whatever. With ddoc you need to use some semi-official templates you need to dig from the newsgroup archives. Doxygen provides all this by default. How is that bad for productivity?

If you would be willing to clean up those templates and submit them, I'll make them part of the official distribution.


> So overall the other systems are much better and I also think I could write something 10 times better than ddoc in 2..7 days if someone would give me an untainted GPL licensed frontend that didn't look so butt ugly.

I'd welcome your contributions to improving ddoc.

On Saturday 14 August 2010 13:06:04 retard wrote:
> Comparing hand-written html to ddoc is a bit unfair. I've used several CMS and template systems. They even have good support for D. My experiences tell me that
> 
> 1. ddoc has worse productivity than real document generators such as doxygen or good cms/markup/web template systems.
> 
> 2. these other systems also support commenting out stuff
> 
> 3. these other systems also support generating correct, conforming HTML/ XML/TeX/PDF/MAN/whatever. With ddoc you need to use some semi-official templates you need to dig from the newsgroup archives. Doxygen provides all this by default. How is that bad for productivity?
> 
> 4. these other systems also support conditional compilation
> 
> 5-6. these other systems also support separating the style/layout from the structure.
> 
> 7. ditto (and it's better than what ddoc produces by default)
> 
> 8. ditto (and it's better than what ddoc produces). ddoc doesn't extract all components of symbol signatures in a structured way.
> 
> 9. ditto
> 
> 10. the other systems look better than ddoc
> 
> So overall the other systems are much better and I also think I could write something 10 times better than ddoc in 2..7 days if someone would give me an untainted GPL licensed frontend that didn't look so butt ugly.

It's quite possible that other documentation generators are better than ddoc, but to some extent, that's not the point. ddoc is supposed to be simple and always available with the D compiler so that there is always a doc generator which you can count on. By having it included with the compiler, it encourages people to actually write documentation and generate it. People who actually care about writing good documentation anyway and are looking for powerful doc generators can easily use more powerful doc generators such as doxygen. Whether ddoc exists or not has no effect on that.

So, I don't think that there's really much reason to harp on ddoc. If there are improvements which can be made to it without making it more complex or harder to use, then I'm sure that Walter is open to them (especially if they make it simpler and/or _easier_ to use). But it's not meant to be the end all and be all of doc generators. It's meant to be a basic, simple tool that you can count on being there. If you want fancier, more powerful doc generation, you're free to use 3rd party doc generators like doxygen.

- Jonathan M Davis

retard wrote:
> Sat, 07 Aug 2010 16:54:03 +0200, Jacob Carlborg wrote:
> 

> So overall the other systems are much better and I also think I could write something 10 times better than ddoc in 2..7 days if someone would give me an untainted GPL licensed frontend that didn't look so butt ugly.

What prevents you from contributing to the frontend under its current license?

On Sat, 14 Aug 2010 20:20:49 -0500, Mike Parker <aldacron@gmail.com> wrote:

>
> What prevents you from contributing to the frontend under its current license?

Apparently he doesn't like butt-ugly frontends. That's the game breaker for him  :|

-- 
Yao G.

Yao G. Wrote:

> You are just becoming a parody of yourself.

Everyone deserves respect when expresses opinions honestly and in an civil way, even when the ideas are wrong.

Bye,
bearophile

On Sat, 14 Aug 2010 20:32:18 -0500, bearophile <bearophileHUGS@lycos.com> wrote:

> Yao G. Wrote:
>
>> You are just becoming a parody of yourself.
>
> Everyone deserves respect when expresses opinions honestly and in an civil way, even when the ideas are wrong.
>
> Bye,
> bearophile

Civil way? Really? But you are right about the freedom to express opinions.


-- 
Yao G.

Sat, 14 Aug 2010 21:32:18 -0400, bearophile wrote:

> Yao G. Wrote:
> 
>> You are just becoming a parody of yourself.
> 
> Everyone deserves respect when expresses opinions honestly and in an civil way, even when the ideas are wrong.

I just made some arguments against using ddoc since in my opinion it provides lower productivity than the competing tools. There are perfectly valid reasons to not use it. These are my opinions:

 - the markup/macro syntax is NIH new. It might be simpler for Walter to
improve on, but a user i) has to learn yet another new syntax (it's quite
likely that a developer already knows html/xml or javadoc/doxygen style
or something like markdown) and ii) the user has to adapt to changes
because the functionality is very primitive and users expect more
features as the user base grows. This is a real issue if the project
grows beyond say 5000 LOC. The managers/users of the documented project
might expect features such as a TOC or inter-module hyperlinks.

 - the existing ddoc documents encourage writing in "html 3.2 optimized"
way. Other document generators try to provide a generic interface with
documentation syntax that improves the readability of the source code. As
a result, doxygen generates all kinds of documentation output, but ddoc
is mostly used to produce html pages. The candydoc system with its
terrible javascript hangs many older workstations. The same functionality
is better achieved with a more complete document generator.

 - the simple utility looks intriguing at first, however it doesn't scale
much up. You might wish for new features/bugfixes, but the tool has very
low priority. You can check the commit history - nothing revolutionary
happens usually. Also, contributing new code to the toolchain requires an
order of magnitude more effort than learning some other document
generator. That probably explains why ddoc development is so dead.


Someone might ask, why I don't contribute or use ddoc. I have my custom made filters for .d files and I use doxygen. Works just fine. On web pages I use a template engine with syntax highlighting support. These system also support D just fine nowadays. This way I've maximized my productivity. I can use the same documentation tool for C/C++/Java/C#/D projects. No need to learn new syntax.

> It's meant to be a basic, simple tool that you can count on being there. If you want fancier, more powerful doc generation, you're free to use 3rd party doc generators like doxygen.

The default toolchain creates a certain kind of ecosystem. Ddoc encourages amateurish hobbyist project look and feel. It can't even compete with javadoc or rdoc feature-wise. Comparing with C or C++ here is moot, because those languages were invented more or less before these kind of document generators even existed.

Usually the larger projects count on tools being there. But it sounds weird to encourage the use of primitive ddoc in those projects.

Sat, 14 Aug 2010 20:24:33 -0500, Yao G. wrote:

> On Sat, 14 Aug 2010 20:20:49 -0500, Mike Parker <aldacron@gmail.com> wrote:
> 
> 
>> What prevents you from contributing to the frontend under its current license?
> 
> Apparently he doesn't like butt-ugly frontends. That's the game breaker for him  :|

I'm using the same argumentation as Walter here. If I ever contributed code to the proprietary dmd, I would get sued by a group of lawyers when contributing code later to some other proprietary / open source compiler. Even seeing the code might taint my mind. Just like Walter refuses to read Tango's code to prevent license issues with Phobos.

Dmd's code also has several problems. I don't think it supports multi- core CPUs very well when parsing files. The other issues are: forward reference bugs, lack of a good internal garbage collector (CTFE & templates), not well documented (I know nearly nothing about compiler implementation).

To me, the biggest appeal of ddoc is that it doesn't require markup to give good enough results. It's almost mindless to use.

On Sat, 14 Aug 2010 21:18:19 -0500, retard <re@tard.com.invalid> wrote:

> [snip]

Thanks for your informative post. I'm really glad that you don't use such primitive, butt-ugly tools like DDOC.


-- 
Yao G.