Node:href, Next:size, Previous:exists, Up:XPath functions
Usage: href(pathname [, base])
To create hyperlinks to target files, you need to know the name
and location of the target files. Transbuild provides this XPath
extension function to convert the names (such as those obtained from
the TBA:source attribute) into a target file
name.
Relative paths are always generated (relative to the current target file). This allows your generated HTML files to be tested before putting onto a Web server. They can be tested by opening generated files directly in a browser. If absolute paths were generated those links would not work, because they would be absolute paths in the Web server, but not in the file system.
In general, you should try to only refer to files and
directories in the source tree file space, and use the
TBF:href function to map them into the target tree
file space. If source .xml files are being transformed into target
.html files, always refer to the ".xml" files and never to the
.html files. Work in the source tree file space, and let Transbuild
worry about the target tree file space.
In addition to Transbuild URIs, the TBF:href
XPath function also operates on absolute paths (absolute to the source
tree root directory) and relative paths from the currently processed
source file.
The transbuild:// scheme used in annotations
does not serve any real function, other than alerting anyone seeing it
that they are working in the source tree file space. For example,
there is no difference between
transbuild://abc/def.xml and
/abc/def.xml.
An error will be raised if TBF:href tries to
reference a file or directory which does not exist or is outside of
the source tree.
The two argument form of TBF:href takes a
base file or directory as the second argument. The resulting path will
be relative to that base. The base (like the first argument) must be
a file or directory which exists in the source tree, otherwise an
error will be raised. The one argument form simply uses the current
source file as the base.
The two argument form is only useful in advanced scripts where you are generating extra output files. And then, only if you are creating those output files in a different directory from where the current target file will be placed.
<emphasis>Note: in the current implementation, the base must be a source source file (and not a directory) for it to work properly. Except when the pathname is to a file in the same directory as the base, in which case the base must be a directory. Yes, this is inconsistent, confusing and hopefully will be fixed in future releases. However, this is a low priority since I don't expect many people will be creating files in such a complex manner. It is much simpler putting the extra output files in the same directory as the current file.</emphasis>