get-link-policy-target - Check that the `link policy' is satisfied by a target element.

Description

This function expresses the `link policy' we wish this stylesheet to impose on the element (in a separate document) which is the putative target of a link.

Check link policy, and return a pair. The car of the pair is #f if the policy is satisfied, and a string otherwise (this is an error, which should be signalled with the string as an explanation, and no link should be made); the cdr is a string URL giving the URL to be used, or #f if the policy is satisfied but no link should be made (ie, if the urllinkpolicy is NONE).

The link policy is as follows. If the documentsummary element's exportedlinkpolicy has the value "exportedonly", we may only link to targets which have the export attribute present and set to "export": that is, if we have "exportedonly" but no export, then the policy is trivially satisfied, but we do not return any URL. If the documentsummary element's urllinkpolicy attribute is "automatic", then the urlpath attribute must not be present, and we generate a URL based on the element's location in the hierarchy; if it is "explicit", the urlpath must be present; if it is "none", then the policy is satisfied, but no URL should be returned.

Irrespective of the link policy settings, we take it that it is always permissable to link to the document element.

Note that this function is designed to emit URLs as part of its response. That is, it is partly specific to the stylesheet which generates HTML. The link policy, however, is not specific to HTML, and the link with the HTML stylesheet is only because that stylesheet is the most sophisticated one, to which is delegated such tasks as checking the link policy by calling this function. For these reasons, this function should indeed be in this common set of functions. It may be called from the LaTeX stylesheet, however, in which case the keyed argument no-urls should be set true, to prevent the function referencing the undefined (in that stylesheet) variables %starlink-document-server and href-to (actually, this fails to work, due to what may be either a bug, or implementation-defined behaviour in Jade, so the calling file should specify dummy values for these two variables).

Argument list

nd = singleton-node-list (Given)

The node we want to check.

no-urls = boolean (Given), keyword

If true, simply return #t or #f in the cdr of the pair, rather than returning a URL.

Return value

Type: pair

If car is true, the policy has been violated and the car contains an error. If cdr is true, then a link should be made, using the URL in cdr.