diff --git a/Tools/HTMLLinker.html b/Tools/HTMLLinker.html
new file mode 100644
index 000000000..48aeca1fc
--- /dev/null
+++ b/Tools/HTMLLinker.html
@@ -0,0 +1,337 @@
+
+
+
+ The GNUstep HTML Linker
+
+
+
+ The GNUstep HTML Linker
+
+ Introduction
+
+ What the HTML linker does
+
+ The GNUstep HTML linker is able to fixup links from one HTML
+ document to other HTML ones. By link we mean the standard
+ <a href="NSString.html"> tag. By fixing up a
+ link we mean to modify the path in the href so that
+ it points to the actual file on disk. For example, if you have
+ the file NSString.html in the directory
+ /home/nicola/Doc, when the linker fixes up the
+ <a href="NSString.html"> link, it will replace
+ it with <a
+ href="/home/nicola/Doc/NSString.html">.
+
+ Example
+
+ Say that you have a collection of HTML files, all in the same
+ directory, with working links from one file to the other one. Now
+ you move the files around, scattering them in many directories -
+ of course the links no longer work! By running the HTML linker on
+ the files, the HTML linker will modify all links inside the files,
+ resolving each of them to point to the actual full path of the
+ required file. The links will work again.
+
+ Real world usage of the linker
+
+ In the real world, it's more complicated than this because you
+ normally put the HTML files across different directories from the
+ very beginning. The HTML linker becomes helpful because you can
+ create links between these files as if they were in the same
+ directory ... and then - only at the end - run the HTML linker to
+ actually fixup the links and make them work. If you move around
+ the files or mess in any way with their paths, you can always
+ fixup the links afterwards by rerunning the linker - you don't
+ need to regenerate the HTML files.
+
+ Specification
+
+ Input and destination files
+
+ The HTML linker uses input files and destination
+ files. Both type of files are always supposed to be HTML
+ files. Input files are modified by the linker during the run
+ (they have their links fixed up), while destination files are only
+ read (and sometime not even read). When the HTML linker is run,
+ it first prepares the list of input files and destination files
+ from the arguments on the command line. Then, it reads each input
+ file from disk in turn. It examines all links in the file, and
+ replaces the file with a new version of the file where all links
+ have been fixed up.
+
+ Specifying input and destination files
+
+ All command line arguments which do not begin with a hypen
+ (-), and which are not the values of defaults (for
+ example, not the YES in -CheckLinks YES,
+ because that is the value of the default
+ -CheckLinks), are interpreted as input files if they
+ come before the --Destinations argument, and as
+ destination files if they come after it. If a directory is
+ specified as an input (or destination) file, the linker will
+ recurse into the directory and add to the list of input (or
+ destination) files all files in the directory (and in the
+ directory's subdirectories, no matter how deeply nested) which
+ have one of the following extensions: .html,
+ .HTML, .htm or .HTM. The
+ --Destinations argument ends the list of input files,
+ and is followed by the list of destination files. A typical
+ invocation of the linker might be as follows:
+
+ HTMLLinker myfile.html --Destinations /usr/GNUstep/System/Documentation
+
+ this invokes the linker with a single input file,
+ myfile.html, and all the HTML files inside the
+ /usr/GNUstep/System/Documentation directory as
+ destination files.
+
+ What is a link
+
+ A link is an anchor tag with and href, such as
+ <a href="dest.html#location">. The destination
+ file of the link is the file specified in the href;
+ dest.html in the example. If the link contains a
+ path to the file, for example <a
+ href="/nicola/Documentation/dest.html#location">, the
+ path is ignored, so this link is considered by the linker to be
+ exactly the same as <a
+ href="dest.html#location>.
+
+ Which links are fixed up
+
+ Normally, the linker will only fixup links which have the
+ rel attribute set to dynamical, as in
+ the following example: <a href="nicola.html"
+ rel="dynamical">. In this way, you can specify in your
+ HTML document which links you want to be fixed up, and which you
+ don't want to be. But in certain situations you might want to
+ force the linker to attempt to fixup all links; you can run the
+ linker with the -CheckAllLinks YES option to cause
+ this behaviour. As a special exception, links which obviously are
+ not to be fixed up, such as links beginning with mailto: or
+ news:, and links without a filename (which means they refer
+ to the same file they are in) are never fixed up.
+
+ How links are fixed up
+
+ When the HTML linker encounters a link which needs to be fixed up
+ (say <a href="dest.html#location">), it
+ searches the list of destination files for a file with the same
+ name as the destination file of the link. If no such file is
+ found, the HTML linker emits a warning, and replaces the link in
+ the file with a link to the pathless filename. In the example, it
+ would simply emit <a
+ href="dest.html#location">. If the destination file is
+ found in the list, instead, the HTML linker replaces the link with
+ the full path to the destination file on disk. For example, if
+ there is a /home/nicola/Doc/dest.html destination
+ file, the HTML linker will fixup the link to be <a
+ href="/home/nicola/Doc/dest.html#location"> (as a
+ special exception, if there is a path mapping which matches the
+ path to the destination file, it's applied to the path in the
+ link. See below for a detailed explanation of path mappings).
+ It's important to notice that you must have unique filenames for
+ the linker to work properly. For example, if you have two
+ different destination files with the same name, say
+ NSObject.html, then a link to
+ NSObject.html is likely not to be properly resolved
+ because the linker has no way to know if you meant the link to
+ point to the first or the second destination file! You should
+ choose filenames better to more uniquely specify their contents,
+ for example NSObject_class.html and
+ NSObject_protocol.html if the first file documents
+ the NSObject class and the second one the NSObject protocol. Then
+ all links will clearly refer to one file or the other one, and no
+ confusion will arise. If there are multiple destination files for
+ a link, the linker will guess which one is the right one, and that
+ might not give the desired result.
+
+ How links are checked
+
+ When a link is fixed up, the linker also performs some checking
+ that the link is correct. The first basic check, which is always
+ performed, is that the destination file can be resolved. A
+ warning is emitted if the destination file can't be resolved - in
+ this case (see above) the links can not even be fixed up, and its
+ path is left unspecified. Then, if the destination file was found
+ and if the linker was run with the option -CheckLinks
+ YES (note that this option is the default, so the second
+ check is normally performed unless you pass -CheckLinks
+ NO to the linker), the linker will actually check that the
+ link can be resolved. In practice, the linker checks that the
+ destination file actually contains the specified named section.
+ For example, consider the link <a
+ href="dest.html#location">. This link points to the
+ name location inside the dest.html file.
+ When checking the link, the linker will read the destination file
+ dest.html, and parse it looking for an anchor tag
+ with a name attribute set to location - in practice
+ something like <a name="location">. If it does
+ not find it, it emits a warning. If you already know that all
+ links can be resolved, you can run the linker with
+ -CheckLinks NO skipping the parsing of destination
+ files in order to get peak performance.
+
+ Path mappings
+
+ Path mappings are an additional feature of the HTML linker which
+ can be used when exporting documentation to be served by a web
+ server. If you are not putting your documentation on a web server
+ but simply reading it from the filesystem, then you don't need the
+ path mappings. The issue with exporting documentation to a web
+ server is that you refer to files using paths which are not
+ necessarily the same paths where the files are on disk. For
+ example, suppose that you have some HTML documentation in
+ /opt/doc/base and some other HTML documentation in
+ /opt/doc/gui. The HTML files in the two
+ documentation directories refer to each other. You can run the
+ HTML linker and fixup all links, and we are happy. But now
+ suppose that you set up a web server; the web server, for example,
+ will serve URLs beginning with /Base (meaning as in
+ requests from a browser of the form
+ http://www.server.org/Base) by taking files from
+ /opt/doc/base, and URLs beginning with
+ Gui by taking files from /opt/doc/gui.
+ To fixup the links in this case, you need path mappings. A path
+ mapping specifies that a certain directory on disk is to be
+ referred in some different way in links. In the example, you
+ would pass
+
+ -PathMapping '{ "/opt/doc/base"="/Base"; "/opt/doc/gui"="/Gui"; }'
+
+ to the linker.
+
+ Each path mapping maps a path on disk to a virtual
+ path. For example, it maps the path on disk
+ /opt/doc/base to the virtual path /Base.
+ Each time the linker fixes up a link, after finding the
+ destination file, it checks the list of path mappings. If the
+ path to the destination file begins with the path on disk
+ of one of the path mappings, then that path on disk is
+ replaced with the corresponding virtual path in the path
+ to the destination file before the path to the destination file is
+ written out in the link.
+
+ For example, if you have the path mapping explained above, and if
+ the linker is fixing up the link <a
+ href="hi.html">, where the destination file is
+ /opt/doc/base/nicola/hi.html, then the destination
+ path matches the path mapping for /opt/doc/base, so
+ the path mapping is applied and the link is fixed up to be
+ <a href="/Base/nicola/hi.html"> rather than
+ <a href="/opt/doc/base/nicola/hi.html"> as it
+ would normally have been without the path mapping.
+
+ Specifying path mappings
+
+ On the command line
+ Each path mapping specifies a mapping of a path on disk to a web
+ server alias. The first way to specify the mappings is on the
+ command line, in the form of a dictionary argument to the
+ -PathMappings, as in
+
+ -PathMappings '{ "/opt/doc/base"="/Base"; "/opt/doc/gui"="/Gui"; }'
+
+ where /opt/doc/base and /opt/doc/gui are
+ the paths on disk and /Base and /Gui are
+ the corresponding web server URL paths.
+
+ In a path mappings file
+ The other way to specify mappings is to write them into a file,
+ in the format of a dictionary, as, for example, in a file containing
+ the following lines
+
+ {
+ "/opt/doc/base"="/Base";
+ "/opt/doc/gui"="/Gui";
+ }
+
+ and then tell the linker to read the path mappings from that file,
+ by giving the filename as option to the
+ -PathMappingsFile. For example, if the file
+ containing the mappings is called mappings, then you need
+ to pass
+
+ -PathMappingsFile mappings
+
+ to the linker to have it read mappings from the file.
+
+ Command line path mappings override file path mappings
+ Both command line path mappings and path mappings from a file can
+ be used at the same time; in case of conflict, command line path
+ mappings override path mappings from the file.
+
+ Summary of all the options
+
+ Each of the options beginning with a single hypen (-)
+ require an argument, as in
+
+ HTMLLinker Documentation -CheckLinks YES --Destinations Documentation
+
+ which sets CheckLinks to YES. The options
+ might be anywhere on the command line. Options which do not begin
+ with a single hypen (such as --help) do not require
+ an argument, as in
+
+ HTMLLinker --help
+
+
+ -CheckLinks
+
+ If set to YES (the default) causes the linker,
+ whenever it fixes up a link, to check that the destination file
+ actually contains the target <a name=""> tag.
+ (bug - does not manage yet the id attribute as per
+ newer HTML specifications). You might set it to NO
+ if you already know all links are correct, this will give you a
+ performance improvement because the linker does not need to parse
+ destination files to check links then.
+
+ -FixupAllLinks
+
+ If set to NO (the default) only links containing the
+ rel attribute set to dynamical are fixed
+ up in the input files. If set to YES, all links are
+ fixed up.
+
+ -PathMappings
+
+ If set to a dictionary, read the dictionary as path mappings. See
+ above for more details of path mappings.
+
+ -PathMappingsFile
+
+ If set to a string, consider it to be the name of a file; read
+ path mappings from that file. The file must contain the path
+ mappings in the form of a dictionary. See above for more details
+ on path mappings.
+
+ -Verbose
+
+ If set to YES prints some more messages than if set
+ to NO (the default).
+
+ --help
+
+ Prints a quick explanation of the command line syntax and exits.
+
+ --version
+
+ Prints the version and exits.
+
+ --Destinations
+
+ Ends the list of input files and starts the list of destination
+ files. All files (or directories) on the command line appearing
+ before --Destinations are considered input files,
+ while all files (or directories) after --Destinations
+ are considered destination files.
+
+
+ Nicola Pero
+
+
+Last modified: Fri Jan 4 11:44:15 GMT 2002
+
+
+