diff --git a/Tools/HTMLLinker.html b/Tools/HTMLLinker.html index 48aeca1fc..f040543b5 100644 --- a/Tools/HTMLLinker.html +++ b/Tools/HTMLLinker.html @@ -13,164 +13,252 @@ 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">. + <a href="NSString.html#DescriptionOfNSString"> + 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 the DescriptionOfNSString + location is in the file NSStringOverview.html in the + directory /home/nicola/Doc, when the linker fixes up + the <a + href="NSString.html#DescriptionOfNSString"> link, it + will replace it with <a + href="/home/nicola/Doc/NSStringOverview.html#DescriptionOfNSString">. + Please note that when fixing up the link, the linker modifies both + the path and the file name that the link points to, but not the + location inside the file (the DescriptionOfNSString + in the example). -

Example

+

Practical Usage of the linker

- 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. + The typical usage of the linker is with maintaining + cross-references in software documentation. You need to establish + some sort of convention used by all your software documentation + for the link names. For example, suppose that your documentation + is about C libraries. For each C function, you might decide to + tag its documentation in the files with the name + function$function_name. For example, the place in + the doc where it documents the start_library() + function would have the HTML tag <a + name="function$start_library">. Having established this + convention, in any HTML file in your documentation in which you + want to create a link to the documentation for the + start_library() function, you use the code + <a rel="dynamic" + href="#function$start_library"> (please note that you + ignore the problem of locating the actual file which contains the + documentation for the start_library() function, that + is precisely what the linker will do for you). Whenever you + install the documentation for a new project, you first create a + relocation file for the project documentation, by running + 
+      HTMLLinker -BuildRelocationFileForDir Documentation
+
+ if for example the project documentation is in the + Documentation subdirectory. This will create a + Documentation/table.htmlink file, which contains a + list of all names found in the project documentation, and for each + of them, the file in which it's found. Then, you install the + project documentation (say for example that it's installed into + /opt/gnustep/Local/Documentation/MyProject), and once + it's installed, you can run the linker to update all links so that + they point to the actual files + 
+      HTMLLinker /opt/gnustep/Local/Documentation/MyProject \
+              -l /opt/gnustep/Local/Documentation/MyProject \
+              -l /opt/gnustep/Local/Documentation/MyOtherProject
+
+ This will fixup all links in MyProject's HTML files + by using the relocation files of both MyProject and + MyOtherProject, so all links to anything which is + documented inside those files will be generated correctly. -

Real world usage of the linker

+

Usage of the tool with autogsdoc

- 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. + You can use the tool with documentation generated by autogsdoc to + perform the linking (or to relink it). Make sure to use the option + -LinksMarker gsdoc because autogsdoc marks the links + to be fixed up by the linker by using rel="gsdoc".

Specification

-

Input and destination files

+

Modes of operation

+ The HTML linker works in two phases: - 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. + + + The HTML linker can also be run in a special mode, to generate a + relocation file for later reuse. In this mode, the HTML linker + will build the relocation table for all files in a directory, then + save the relocation table into a table.htmlink file + in that directory for later reuse. + + There are three kinds of files: + + + +

Linker behaviour

+ + The linker keeps a main relocation table, which is empty at the + beginning. When run, the linker performs the following steps: + +
    +
  1. + the linker reads and parses all relocation files specified on + the command line, and merges the relocation tables found there + into the main relocation table. +
    2. +
  2. + the linker reads and parses all destination files specified on + the command line, and builds a relocation table for them, + merging it into the main relocation table. +
    3. +
  3. + if any input files are specified on the command line, the + linker links the files using the relocation table. +
    4. +
+ +

Specifying input, destination and relocation 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: + example, not the YES in -Warn YES, + because that is the value of the default -Warn), are + interpreted as input files. Each destination file is specified by + using a -d option, and each relocation file by using + a -l option. 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. If a directory is specified as a relocation + file, the linker will add to the list of relocation files all + files in the directory which have the extension + .htmlink. A typical invocation of the linker is as + follows: 
-      HTMLLinker myfile.html --Destinations /usr/GNUstep/System/Documentation
+      HTMLLinker -BuildRelocationFileForDir Doc
- 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. + Builds a relocation file for the documentation in the + directory Doc. After this has been done, the + directory Doc can be used as a -l + argument. + 
+      HTMLLinker test.html -l Doc
+
+ Links the file test.html using the relocation file + just generated in the Doc directory.

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>. + dest.html in the example. The destination file is + ignored by the linker; the name of the link (which is everything which + follows the #) is used to perform the linking.

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 + rel attribute set to dynamic, as in the + following example: <a href="nicola.html" + rel="dynamic">. 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. + don't want to be. You can change the type of links to be fixed up + by using the -LinksMarker options, as in + -LinksMarker gsdoc, which causes the linker to fixup + all links with the rel attribute set to + gsdoc rather than dynamic. In certain + situations you might want to force the linker to attempt to fixup + all links; you can run the linker with the -FixupAllLinks + 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:, or links + without a name, 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 + searches the relocation table for a destination file which + contains the location name. 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 + the file with a link to the destination without the filename. In + the example, it would simply emit <a + href="#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 - according + to the relocation table, the file + /home/nicola/Doc/dest.html contains the name + location, 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 + It's important to notice that you must have unique link names 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. + different destination files containing the same name, say + NSObject.html and NSString.html both + containing the name init, then the linker can't + resolve <a href="#init">, because it has no way + to know if you meant the link to point to the first or the second + destination file! You should choose names better so that they + uniquely specify what they represent contents, for example + NSObject_i_init and NSString_i_init if + the first link is in the place documenting the -init + method of the NSObject class and the second one the one of the + NSString class. Then all links will clearly refer to one place 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. + When a link is fixed up, the linker implicitly checks that the link + is correct, because if the link name can't be found in the relocation + tables, a warning is issued.

Path mappings

@@ -214,12 +302,12 @@ 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 + href="hi.html#nicola">, 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 + <a href="/Base/nicola/hi.html#nicola"> rather than + <a href="/opt/doc/base/nicola/hi.html#nicola"> as it would normally have been without the path mapping.

Specifying path mappings

@@ -266,33 +354,38 @@ Each of the options beginning with a single hypen (-) require an argument, as in 
-      HTMLLinker Documentation -CheckLinks YES --Destinations Documentation
+      HTMLLinker Documentation -LinksMarker gsdoc -d 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 + which sets LinksMarker to gsdoc. 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

+

-d

+ + Followed by a destination HTML file, or a directory containing + destination HTML files. + +

-l

- 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. + Followed by a relocation file, or a directory containing relocation files.

-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. + rel attribute set to dynamic (or + whatever specified as LinksMarkers)are fixed up in + the input files. If set to YES, all links are fixed + up. + +

-LinksMarker

+ + If set (and if FixupAllLinks is NO), + only links with the rel attribute set to its value + are processed. By default it is set to dynamic.

-PathMappings

@@ -319,19 +412,11 @@ 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 +Last modified: Sun Jan 6 22:54:58 GMT 2002