buildling links between docs

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.u
k/

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