buildling links between docs

[Stuart Yeates <st...@oucs.ox.ac.uk>]

Hello

I'm looking for an explanation of how to compose links between
documents.

Specifically, in the DOAP plugin, I want to add links back to the
index by category, pointing at the anchor for a specific category.

Problems I'm having are:
*) Getting the root of the forrest build rather than the root of the
website (i.e. knowing where .../build/site maps to on the web)
*) Escaping the items being indexed ("Category Name" vs "Category+Name")
*) Knowing what indexes are created and how to address them

I've looked at a number of places in the code where this is done,
but so much seems to be implicit that I'm having difficulty adapting
it. I've googled and browsed the forrest docs without success.

cheers
stuart
-- 
OSS Watch: http://www.oss-watch.ac.uk/

Re: buildling links between docs

[Ross Gardler <rg...@apache.org>]

Stuart Yeates wrote:
> Hello
> 
> I'm looking for an explanation of how to compose links between
> documents.
> 
> Specifically, in the DOAP plugin, I want to add links back to the
> index by category, pointing at the anchor for a specific category.
> 
> Problems I'm having are:
> *) Getting the root of the forrest build rather than the root of the
> website (i.e. knowing where .../build/site maps to on the web)

[caveat - this is what I *think* happens. I've not fully tested this]

build/sites (i.e. the root of the generated documentation) always maps 
to the root of the server.

If you want to host your content somewhere other than the root of your 
server you need to set @href in the site element of site.xml, i.e. 
href="myroot" will result in the root of your application being 
http://domain.org/myroot/.

[this part I know to be correct]

That then leaves us with the problem of getting that in XML as paths 
such as "/projectDetails/*", as used in the DOAP plugin at present, will 
break. You need to import the dotdots.xsl which provides some templates 
to do this. There are usage comments in the file.

> *) Escaping the items being indexed ("Category Name" vs "Category+Name")

I'm not sure what you mean here. If I point you at 
replaceCharsInString.xsl does it help?

(incidentally, I did not know about this XSL until looking for the 
answers to these questions - this looks like a tidier solution to your 
patch escaping characters in JSON files in the DOAP plugin)

> *) Knowing what indexes are created and how to address them

If the XDoc contains section @id then this is used. In this case, the 
XDoc is generated from the locationmap and it does not contain @id.

If the XDoc does not contain section @id then it is created in 
document-to-html.xsl. See the tocLinkGenerator template.

Ross