Bug 31344

So based on our conversation:

1. nbbuild/template.xml should support a param "javadoc.arch", value a
file location for an arch *.xml file. If this prop is defined, should
create a file ${javadoc.out}/arch.html based on running <arch> with
that input param.

2. For a module which is properly separated and has its own docs -
e.g. openide/compiler - it is the responsibility of the module to
include a link to arch.html somewhere appropriate in the
documentation. E.g. first paragraph of a doc-files/api.html.

2a. Note: currently template.xml does not support Javadoc overview
files, so you can't link to it from there; would be nice to solve
that, though it is hard to make the <javadoc> task include an overview
only conditionally. (Would need two copies of <javadoc> in
template.xml - ugly.) Maybe there could be a default overview page
used for any module which does not supply its own - it would have to
include links to arch.html if ${javadoc.arch} is specified, and/or a
link to ${javadoc.main.page} if that is specified. May just be easier
to make the overview file mandatory.

3. The openide main module is harder because currently it does not use
template.xml for <javadoc> - maybe it could, I don't know. Anyway that
has several arch.xml's associated with it. So for now, suggest that
openide/build.xml directly run <arch> and include the results in
openide/javadoc/OpenAPIs/*.html. openide/api/doc/overview.html would
of course need to link to all of them.

4. We could think about permitting @OPENIDE@ and similar tokens in the
arch *.xml documents, to make it easier for these to link to published
APIs. Note that this would mean that */arch/build.xml and whatever you
use to generate the final ARC case would need to do these replacements
- currently only nbbuild/template.xml (and openide/build.xml) knows
about them.

I am working on rather similar changes for issue #29313 anyway, so I
think it will be easiest if I just do this together with those.

Done.

Verified.