August 07, 2010
bearophile wrote:
> Walter has said that putting ddoc inside the compiler helps keep ddoc
> uniform, so people don't invent/use something different. In theory this is a
> nice purpose, but in practice I have seen lot of people use other
> documentation means for D, Doxygen. Walter seems to ignore how much often
> such other systems are used instead of ddoc.

It's fine if people choose to use other documentation systems. Ddoc, though, sets a minimum standard, and it's always there, requires no additional installs, is always synced to the compiler, is always on every platform D is, etc.

My experience with languages that do not have built in doc abilities is, by and large, only a tiny minority of programmers use a doc system. Having to research, download, install, read the manual, address incompatibilities, etc., takes effort and the reality is that by making such effort close to zero it greatly encourages people to use it.

The same goes for unit tests.

For another example, back in the 80's, it was commonplace for people to dis the C text preprocessor as "not a real macro system". Those who wanted a better one were advised to "just use m4". How many people using C or C++ today use m4 as the preprocessor? Zilch. The C preprocessor was good enough to get the job done, it was always there, always ready, and that was that.

(Note that I'm not defending the preprocessor, I'm just illustrating the power of having something built in as opposed to being a separate tool.)
August 07, 2010
On 08/07/2010 02:53 PM, Walter Bright wrote:
> bearophile wrote:
>> Walter has said that putting ddoc inside the compiler helps keep ddoc
>> uniform, so people don't invent/use something different. In theory
>> this is a
>> nice purpose, but in practice I have seen lot of people use other
>> documentation means for D, Doxygen. Walter seems to ignore how much often
>> such other systems are used instead of ddoc.
>
> It's fine if people choose to use other documentation systems. Ddoc,
> though, sets a minimum standard, and it's always there, requires no
> additional installs, is always synced to the compiler, is always on
> every platform D is, etc.
>
> My experience with languages that do not have built in doc abilities is,
> by and large, only a tiny minority of programmers use a doc system.
> Having to research, download, install, read the manual, address
> incompatibilities, etc., takes effort and the reality is that by making
> such effort close to zero it greatly encourages people to use it.
>
> The same goes for unit tests.
>
> For another example, back in the 80's, it was commonplace for people to
> dis the C text preprocessor as "not a real macro system". Those who
> wanted a better one were advised to "just use m4". How many people using
> C or C++ today use m4 as the preprocessor? Zilch. The C preprocessor was
> good enough to get the job done, it was always there, always ready, and
> that was that.
>
> (Note that I'm not defending the preprocessor, I'm just illustrating the
> power of having something built in as opposed to being a separate tool.)

Boost's preprocessor library is a powerful exhibit in favor of your argument. I think I wouldn't be mistaken to say that everything it does can be done much easier and much better, plus with m4 you can do a lot other things of interest. But the Boost preprocessor library wins because "it's there".


Andrei
August 08, 2010
On Sat, 07 Aug 2010 01:55:35 -0700, Jonathan M Davis wrote:

> On Friday 06 August 2010 20:06:59 Bernard Helyer wrote:
>> On Sun, 01 Aug 2010 13:22:53 -0700, Walter Bright wrote:
>> > 1. Being a defined part of D means it's ALWAYS there. That means there won't be D compilers without ddoc.
>> 
>> /me waves.
>> 
>> I'm writing a D compiler, and have zero plans to add DDoc support. I couldn't do it well enough for me to waste my time on it.
> 
> Well, that's your choice, but then you haven't followed the D spec in that regard, so your compiler wouldn't be properly standard D.

Nope. But it doesn't matter. It doesn't affect the code built or generated, and that's my focus -- at least for the foreseeable future.

I'm writing a compiler, not a half-arsed documentation generator (because if I wrote the DDoc stuff, that's exactly what it would be).
August 08, 2010
On 08/08/2010 01:32, Bernard Helyer wrote:
> Nope. But it doesn't matter. It doesn't affect the code built or
> generated, and that's my focus -- at least for the foreseeable future.
>
> I'm writing a compiler, not a half-arsed documentation generator (because
> if I wrote the DDoc stuff, that's exactly what it would be).

Sounds cool. What are you writing it in and is it going to be public?

-- 
My enormous talent is exceeded only by my outrageous laziness.
http://www.ssTk.co.uk
August 08, 2010
== Quote from Bernard Helyer (b.helyer@gmail.com)'s article
> I'm writing a compiler, not a half-arsed documentation generator (because if I wrote the DDoc stuff, that's exactly what it would be).

I'll concur with Walter.  I think that sometimes power users of a given tool/feature fail to realize that very often simple, good enough and works out of the box beats well-designed, feature-packed, efficient, but a PITA to set up and use, overkill for simple cases, and not available out of the box.  I understand treating ddoc as a low priority feature, but **please** support it eventually, as the whole point of it is that it's just there on any implementation (nothing separate to download/configure) and just works for the simplest 80-90% of cases even if its deficiencies become obvious in the last 10-20%.

In general I also think that DDoc's evolution is actually good design strategy.  I wish more tools were designed by pinning down how the simplest 80-90% of cases should work first, treating that as a constraint and then figuring out how to make the most complicated 10-20% work within the constraint.  Designing with "everything must be possible" as the first goal encourages overengineering such that users with simple needs end up reinventing the wheel because it's the path of least resistance.  For example, I'd probably never use Ddoc if I had to use XML for it.
August 08, 2010
On Sun, 08 Aug 2010 02:02:28 +0100, div0 wrote:

> On 08/08/2010 01:32, Bernard Helyer wrote:
>> Nope. But it doesn't matter. It doesn't affect the code built or generated, and that's my focus -- at least for the foreseeable future.
>>
>> I'm writing a compiler, not a half-arsed documentation generator (because if I wrote the DDoc stuff, that's exactly what it would be).
> 
> Sounds cool. What are you writing it in and is it going to be public?

D. It's already public[1], but there's not a lot to show yet. You can compile `int main() { return 42; }`, but that's about it, so far. :P

[1]:http://github.com/bhelyer/SDC
August 08, 2010
On Sun, 08 Aug 2010 02:22:30 +0000, dsimcha wrote:

> == Quote from Bernard Helyer (b.helyer@gmail.com)'s article
>> I'm writing a compiler, not a half-arsed documentation generator (because if I wrote the DDoc stuff, that's exactly what it would be).
> I understand treating ddoc as a low priority feature,
> but **please** support it eventually,

Well, sure, once basically *everything* else is done, I'll probably poke at it. But it is a very low priority.
August 14, 2010
Sun, 08 Aug 2010 02:22:30 +0000, dsimcha wrote:

> == Quote from Bernard Helyer (b.helyer@gmail.com)'s article
>> I'm writing a compiler, not a half-arsed documentation generator (because if I wrote the DDoc stuff, that's exactly what it would be).
> 
> I'll concur with Walter.  I think that sometimes power users of a given tool/feature fail to realize that very often simple, good enough and works out of the box beats well-designed, feature-packed, efficient, but a PITA to set up and use, overkill for simple cases, and not available out of the box.  I understand treating ddoc as a low priority feature, but **please** support it eventually, as the whole point of it is that it's just there on any implementation (nothing separate to download/configure) and just works for the simplest 80-90% of cases even if its deficiencies become obvious in the last 10-20%.
> 
> In general I also think that DDoc's evolution is actually good design strategy.  I wish more tools were designed by pinning down how the simplest 80-90% of cases should work first, treating that as a constraint and then figuring out how to make the most complicated 10-20% work within the constraint.  Designing with "everything must be possible" as the first goal encourages overengineering such that users with simple needs end up reinventing the wheel because it's the path of least resistance.  For example, I'd probably never use Ddoc if I had to use XML for it.

The problem with ddoc is that even though 1000+ documentation formats already existed, he wanted to reinvent his own. The ddoc syntax is terrible ad-hoc crap and geared towards html (3.2/4). Has anyone seriously tried to generate any non-html documents with ddoc which look as good as better than those created with e.g. doxygen?! I've personally just filtered out the bad constructs from the sources and rendered with the buggy doxygen. Much better. I get nice pdf/tex/man/xml output.
Next ›   Last »
1 2
Top | Discussion index | About this forum | D home