- 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#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).
-
-
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.
-
- -LinksMarker gsdoc because autogsdoc marks the links
- to be fixed up by the linker by using rel="gsdoc".
-
- <a name="xxx">) in the files
- to the file in which the name is found. The HTML files are not
- touched. The linker is able to merge this dynamically generated
- relocation table with pregenerated relocation tables loaded from
- files (called relocation files).
- table.htmlink file
- in that directory for later reuse.
-
- There are three kinds of files:
-
- .htmlink extension.
- -), and which are not the values of defaults (for
- 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 -BuildRelocationFileForDir Doc -- 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.
-
- 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. 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.
-
- 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. 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.
-
- <a href="dest.html#location">), it
- 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 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 link names for
- the linker to work properly. For example, if you have two
- 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.
-
- /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#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#nicola"> rather than
- <a href="/opt/doc/base/nicola/hi.html#nicola"> as it
- would normally have been without the path mapping.
-
- -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.
-
-
- {
- "/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. - -
-)
- require an argument, as in
- - HTMLLinker Documentation -LinksMarker gsdoc -d Documentation -- 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 -- -
NO (the default) only links containing the
- 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.
-
- FixupAllLinks is NO),
- only links with the rel attribute set to its value
- are processed. By default it is set to dynamic.
-
- YES prints some more messages than if set
- to NO (the default).
-
-