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.
