xqdoc does no dependency checking on inputs

[Chris Hillery]

Every time you type "make doc" it re-does the whole process, even if none of the inputs has changed. Until this is corrected, it is not reasonable to make the documentation part of the normal build process.

[Chris Hillery (ceejatec)]

(Removing "Postponed" Resolution; marking as "v2.1" is sufficient)

[Sorin Marian Nasoi (sorin.marian.nasoi)]

This can not be implemented in the suggested way:
- even if the XQuery module did not change, if anything in the XQDoc style has changed, the XHTML output *has to* change, thus the XQDoc documentation page for all modules have to be regenerated.

We should however try to squeeze more performance out of the XQDoc generatator such that we can remove the 3 templates for the following modules:
- http://www.w3.org/2005/xpath-functions
- http://www.w3.org/2005/xpath-functions/math
- http://www.functx.com/

[Chris Hillery (ceejatec)]

It's actually easily possible in CMake to introduce dependencies on any files. So it would be easy to ensure that the "doc" target also depends on the stylesheets and so forth.

[Sorin Marian Nasoi (sorin.marian.nasoi)]

Chris I was not talking about a stylesheet I am talking about changes in what we display, meaniing changes in the xqdoc2xhtml module that impact all XQDoc generated XHTML pages.
If for instance
- we decide it's better to show another section between the module description and function summary (like it was the case with the annotations section)
- or we decide that one of the sections should look different (like it was the case with the variables section)

Then, all XQDoc pages change. One can not know that something has changed until one generates all the new XQDoc pages.

So you see why I say that the CMake way does not help in this case?

The solution is to have 'make xqdoc' even quicker and generate all the pages every time: do you agree?

[Sorin Marian Nasoi (sorin.marian.nasoi)]

If 'make xqdoc' only took a template and put content in some sections, then one could have implemented your suggestion and regenerate XHTML pages only for the modules that changed, or for all modules if the template has changed.

But this is not the case: most of the last changes were in xqdoc2xhtml module itself.

So one can not know when the changes in xqdoc2xhtml module impact all XHTML generated documentation or only some pages.

So the solution IMHO is to generate all XHTML pages for all modules as quick as possible.

[Chris Hillery (ceejatec)]

In that case, the "doc" target should have dependencies on the xqdoc2xhtml module.

No matter what, a build target always does one thing: take a set of inputs (which could be data, code, whatever) and produce some outputs. In all cases, the target should depend on all inputs, so that it only runs when the outputs are out of date in relation to any input.

*Ideally* it would be able to do some form of incremental build, but I can see that that would be challenging for xqdoc, and in some cases impossible like you said. However, that's not actually what the bug was asking for. At the time, it was being proposed that "make doc" should be added to the ALL target, so that it will be built *by default*. For that to be reasonable, IMHO it needs to have completely correct dependency checking, as well as being very fast (ideally under 10 seconds on reasonable hardware).

However, at the moment, I'm not sure that anyone is asking for xqdoc to be built by default anymore. So, this bug is not as high a priority as it was. I think it would be nice if you typed "make doc" twice, that the second time it would do nothing. But that's not super-urgent.

I'm adding Matthias to the CC for his take, and for the moment I'm lowering the priority and removing from Milestone 2.1.

[Sorin Marian Nasoi (sorin.marian.nasoi)]

This is an older issue that is fixed in the trunk.

Although the dependency checking on inputs is not done, the "make xqdoc" takes a short time and is currently included as a test called 'make_xqdoc'.

Marking this as "Fix committed".