Improving ddoc

[Joseph Rushton Wakeling via Digitalmars-d]

On 03/01/15 01:11, Walter Bright via Digitalmars-d wrote:
> An interesting thing about Ddoc is we've gotten a heluva lot of mileage out of a
> rather simple piece of code.

Very much so, and your point elsewhere in this thread about how valuable it is 
to have a built-in documentation tool is absolutely spot-on.  A story to 
illustrate this ...

A few days ago I had a go at building and installing the rust compiler (no, I'm 
not jumping ship, I just decided it was about time I started getting some proper 
hands-on understanding of some of the alternative design approaches out 
there:-).  This uses pandoc to generate documentation, which in turn evokes 
pdflatex, xelatex or lualatex, with the last of these being the preferred option.

One ./configure && make later, and after quite a bit of compilation, the 
compiler itself was built -- at which point, the makefile tried to go on and 
build the documentation, and failed, for reasons I still don't understand (it 
was the lualatex command that was failing, but the error message was not very 
clear in conveying what the actual problem was).

OK, well, the compiler is built, right?  So let's try 'make install' ... oh no, 
the first thing it tries to do is to complete the 'make all' target and build 
the docs, and of course that fails, so it doesn't install anything. :-\

Now, full credit to the rust community: they were immediately friendly and 
helpful in advising me how to deal with this (you can pass a flag to the 
./configure command to request not to build the docs).  And of course you can 
see this as primarily a fault in how the build system defines its targets and 
their dependencies.  But the simple fact is, had documentation generation been 
built in rather than relying on 3rd-party tools, it would never have been an 
issue, _and_ I'd have ended up having the documentation as well as just the 
compiler executable and libraries.