2
<heading>The HTMLLinker tool</heading>
4
<heading>Introduction</heading>
6
The GNUstep HTML linker is able to fixup links from one HTML
7
document to other HTML ones. By link we mean the standard
8
<code><a href="NSString.html#DescriptionOfNSString"></code>
9
tag. By fixing up a link we mean to modify the path in the
10
<code>href</code> so that it points to the actual file on disk.
11
For example, if you the <code>DescriptionOfNSString</code>
12
location is in the file <code>NSStringOverview.html</code> in the
13
directory <code>/home/nicola/Doc</code>, when the linker fixes up
15
href="NSString.html#DescriptionOfNSString"></code> link, it
16
will replace it with <code><a
17
href="/home/nicola/Doc/NSStringOverview.html#DescriptionOfNSString"></code>.
18
Please note that when fixing up the link, the linker modifies both
19
the path and the file name that the link points to, but not the
20
location inside the file (the <code>DescriptionOfNSString</code>
26
<heading>Practical Usage of the linker</heading>
28
The typical usage of the linker is with maintaining
29
cross-references in software documentation. You need to establish
30
some sort of convention used by all your software documentation
31
for the link names. For example, suppose that your documentation
32
is about C libraries. For each C function, you might decide to
33
tag its documentation in the files with the name
34
<code>function$function_name</code>. For example, the place in
35
the doc where it documents the <code>start_library()</code>
36
function would have the HTML tag <code><a
37
name="function$start_library"></code>. Having established this
38
convention, in any HTML file in your documentation in which you
39
want to create a link to the documentation for the
40
<code>start_library()</code> function, you use the code
41
<code><a rel="dynamic"
42
href="#function$start_library"></code> (please note that you
43
ignore the problem of locating the actual file which contains the
44
documentation for the <code>start_library()</code> function, that
45
is precisely what the linker will do for you). Whenever you
46
install the documentation for a new project, you first create a
47
relocation file for the project documentation, by running
49
HTMLLinker -BuildRelocationFileForDir Documentation
51
if for example the project documentation is in the
52
<code>Documentation</code> subdirectory. This will create a
53
<code>Documentation/table.htmlink</code> file, which contains a
54
list of all names found in the project documentation, and for each
55
of them, the file in which it's found. Then, you install the
56
project documentation (say for example that it's installed into
57
<code>/opt/gnustep/Local/Documentation/MyProject</code>), and once
58
it's installed, you can run the linker to update all links so that
59
they point to the actual files
61
HTMLLinker /opt/gnustep/Local/Documentation/MyProject \
62
-l /opt/gnustep/Local/Documentation/MyProject \
63
-l /opt/gnustep/Local/Documentation/MyOtherProject
65
This will fixup all links in <code>MyProject</code>'s HTML files
66
by using the relocation files of both <code>MyProject</code> and
67
<code>MyOtherProject</code>, so all links to anything which is
68
documented inside those files will be generated correctly.
72
<heading>Usage of the tool with autogsdoc</heading>
74
You can use the tool with documentation generated by autogsdoc to
75
perform the linking (or to relink it). Make sure to use the option
76
<code>-LinksMarker gsdoc</code> because autogsdoc marks the links
77
to be fixed up by the linker by using <code>rel="gsdoc"</code>.
81
<heading>Modes of operation</heading>
82
The HTML linker works in two phases:
86
<li> The first (called <i>generation of the relocation
87
table</i>) preprocesses a given set of HTML files so that it can
88
be the destination of links. It builds a relocation table for
89
the given set of HTML files. This relocation table simply maps
90
all names (as in <code><a name="xxx"></code>) in the files
91
to the file in which the name is found. The HTML files are not
92
touched. The linker is able to merge this dynamically generated
93
relocation table with pregenerated relocation tables loaded from
94
files (called <i>relocation files</i>).
97
<li> The second (called <i>linking</i>) links a given file to
98
the available HTML files on disk, by using the relocation table
99
to modify the HTML links in the file so that they point to
105
The HTML linker can also be run in a special mode, to generate a
106
relocation file for later reuse. In this mode, the HTML linker
107
will build the relocation table for all files in a directory, then
108
save the relocation table into a <code>table.htmlink</code> file
109
in that directory for later reuse.
111
There are three kinds of files:
116
<em>input files</em>: these are HTML files which are modified
117
as a consequence of linking; they have their links fixed up.
121
<em>destination files</em>: these are HTML files which are
122
read to produce relocation tables.
126
<em>relocation files</em>: these files are not HTML files -
127
they are only created and read by the linker (unless you have
128
a tool which can manage them), and are in a specific - very
129
simple - format. They are used to save relocation information
130
for later reuse, so that the linker can run faster. Normally,
131
they have a <code>.htmlink</code> extension.
138
<heading>Linker behaviour</heading>
140
The linker keeps a main relocation table, which is empty at the
141
beginning. When run, the linker performs the following steps:
145
the linker reads and parses all relocation files specified on
146
the command line, and merges the relocation tables found there
147
into the main relocation table.
150
the linker reads and parses all destination files specified on
151
the command line, and builds a relocation table for them,
152
merging it into the main relocation table.
155
if any input files are specified on the command line, the
156
linker links the files using the relocation table.
161
<heading>Specifying input, destination and relocation files</heading>
163
All command line arguments which do not begin with a hypen
164
(<code>-</code>), and which are not the values of defaults (for
165
example, not the <code>YES</code> in <code>-Warn YES</code>,
166
because that is the value of the default <code>-Warn</code>), are
167
interpreted as input files. Each destination file is specified by
168
using a <code>-d</code> option, and each relocation file by using
169
a <code>-l</code> option. If a directory is specified as an input
170
(or destination) file, the linker will recurse into the directory
171
and add to the list of input (or destination) files all files in
172
the directory (and in the directory's subdirectories, no matter
173
how deeply nested) which have one of the following extensions:
174
<code>.html</code>, <code>.HTML</code>, <code>.htm</code> or
175
<code>.HTM</code>. If a directory is specified as a relocation
176
file, the linker will add to the list of relocation files all
177
files in the directory which have the extension
178
<code>.htmlink</code>. A typical invocation of the linker is as
181
HTMLLinker -BuildRelocationFileForDir Doc
183
Builds a relocation file for the documentation in the
184
directory <code>Doc</code>. After this has been done, the
185
directory <code>Doc</code> can be used as a <code>-l</code>
188
HTMLLinker test.html -l Doc
190
Links the file <code>test.html</code> using the relocation file
191
just generated in the <code>Doc</code> directory.
193
<heading>What is a link</heading>
195
A link is an anchor tag with and <code>href</code>, such as
196
<code><a href="dest.html#location"></code>. The destination
197
file of the link is the file specified in the <code>href</code>;
198
<code>dest.html</code> in the example. The destination file is
199
ignored by the linker; the name of the link (which is everything which
200
follows the <code>#</code>) is used to perform the linking.
202
<heading>Which links are fixed up</heading>
204
Normally, the linker will only fixup links which have the
205
<code>rel</code> attribute set to <code>dynamic</code>, as in the
206
following example: <code><a href="nicola.html"
207
rel="dynamic"></code>. In this way, you can specify in your
208
HTML document which links you want to be fixed up, and which you
209
don't want to be. You can change the type of links to be fixed up
210
by using the <code>-LinksMarker</code> options, as in
211
<code>-LinksMarker gsdoc</code>, which causes the linker to fixup
212
all links with the <code>rel</code> attribute set to
213
<code>gsdoc</code> rather than <code>dynamic</code>. In certain
214
situations you might want to force the linker to attempt to fixup
215
all links; you can run the linker with the <code>-FixupAllLinks
216
YES</code> option to cause this behaviour. As a special
217
exception, links which obviously are not to be fixed up, such as
218
links beginning with <i>mailto:</i> or <i>news:</i>, or links
219
without a name, are never fixed up.
221
<heading>How links are fixed up </heading>
223
When the HTML linker encounters a link which needs to be fixed up
224
(say <code><a href="dest.html#location"></code>), it
225
searches the relocation table for a destination file which
226
contains the <code>location</code> name. If no such file is
227
found, the HTML linker emits a warning, and replaces the link in
228
the file with a link to the destination without the filename. In
229
the example, it would simply emit <code><a
230
href="#location"></code>. If the destination file is found in
231
the list, instead, the HTML linker replaces the link with the full
232
path to the destination file on disk. For example, if - according
233
to the relocation table, the file
234
<code>/home/nicola/Doc/dest.html</code> contains the name
235
<code>location</code>, the HTML linker will fixup the link to be
236
<code><a href="/home/nicola/Doc/dest.html#location"></code>
237
(as a special exception, if there is a path mapping which matches
238
the path to the destination file, it's applied to the path in the
239
link. See below for a detailed explanation of path mappings).
240
It's important to notice that you must have unique link names for
241
the linker to work properly. For example, if you have two
242
different destination files containing the same name, say
243
<code>NSObject.html</code> and <code>NSString.html</code> both
244
containing the name <code>init</code>, then the linker can't
245
resolve <code><a href="#init"></code>, because it has no way
246
to know if you meant the link to point to the first or the second
247
destination file! You should choose names better so that they
248
uniquely specify what they represent contents, for example
249
<code>NSObject_i_init</code> and <code>NSString_i_init</code> if
250
the first link is in the place documenting the <code>-init</code>
251
method of the NSObject class and the second one the one of the
252
NSString class. Then all links will clearly refer to one place or
253
the other one, and no confusion will arise. If there are multiple
254
destination files for a link, the linker will guess which one is
255
the right one, and that might not give the desired result.
257
<heading>How links are checked</heading>
259
When a link is fixed up, the linker implicitly checks that the link
260
is correct, because if the link name can't be found in the relocation
261
tables, a warning is issued.
263
<heading>Path mappings</heading>
265
Path mappings are an additional feature of the HTML linker which
266
can be used when exporting documentation to be served by a web
267
server. If you are not putting your documentation on a web server
268
but simply reading it from the filesystem, then you don't need the
269
path mappings. The issue with exporting documentation to a web
270
server is that you refer to files using paths which are not
271
necessarily the same paths where the files are on disk. For
272
example, suppose that you have some HTML documentation in
273
<code>/opt/doc/base</code> and some other HTML documentation in
274
<code>/opt/doc/gui</code>. The HTML files in the two
275
documentation directories refer to each other. You can run the
276
HTML linker and fixup all links, and we are happy. But now
277
suppose that you set up a web server; the web server, for example,
278
will serve URLs beginning with <code>/Base</code> (meaning as in
279
requests from a browser of the form
280
<code>http://www.server.org/Base</code>) by taking files from
281
<code>/opt/doc/base</code>, and URLs beginning with
282
<code>Gui</code> by taking files from <code>/opt/doc/gui</code>.
283
To fixup the links in this case, you need path mappings. A path
284
mapping specifies that a certain directory on disk is to be
285
referred in some different way in links. In the example, you
288
-PathMapping '{ "/opt/doc/base"="/Base"; "/opt/doc/gui"="/Gui"; }'
292
Each path mapping maps a <em>path on disk</em> to a <em>virtual
293
path</em>. For example, it maps the path on disk
294
<code>/opt/doc/base</code> to the virtual path <code>/Base</code>.
295
Each time the linker fixes up a link, after finding the
296
destination file, it checks the list of path mappings. If the
297
path to the destination file begins with the <em>path on disk</em>
298
of one of the path mappings, then that <em>path on disk</em> is
299
replaced with the corresponding <em>virtual path</em> in the path
300
to the destination file before the path to the destination file is
301
written out in the link.
303
For example, if you have the path mapping explained above, and if
304
the linker is fixing up the link <code><a
305
href="hi.html#nicola"></code>, where the destination file is
306
<code>/opt/doc/base/nicola/hi.html</code>, then the destination
307
path matches the path mapping for <code>/opt/doc/base</code>, so
308
the path mapping is applied and the link is fixed up to be
309
<code><a href="/Base/nicola/hi.html#nicola"></code> rather than
310
<code><a href="/opt/doc/base/nicola/hi.html#nicola"></code> as it
311
would normally have been without the path mapping.
313
<heading>Specifying path mappings</heading>
315
<h5>On the command line</h5>
316
Each path mapping specifies a mapping of a path on disk to a web
317
server alias. The first way to specify the mappings is on the
318
command line, in the form of a dictionary argument to the
319
<code>-PathMappings</code>, as in
321
-PathMappings '{ "/opt/doc/base"="/Base"; "/opt/doc/gui"="/Gui"; }'
323
where <code>/opt/doc/base</code> and <code>/opt/doc/gui</code> are
324
the paths on disk and <code>/Base</code> and <code>/Gui</code> are
325
the corresponding web server URL paths.
327
<h5>In a path mappings file</h5>
328
The other way to specify mappings is to write them into a file,
329
in the format of a dictionary, as, for example, in a file containing
333
"/opt/doc/base"="/Base";
334
"/opt/doc/gui"="/Gui";
337
and then tell the linker to read the path mappings from that file,
338
by giving the filename as option to the
339
<code>-PathMappingsFile</code>. For example, if the file
340
containing the mappings is called <code>mappings</code>, then you need
343
-PathMappingsFile mappings
345
to the linker to have it read mappings from the file.
347
<h5>Command line path mappings override file path mappings</h5>
348
Both command line path mappings and path mappings from a file can
349
be used at the same time; in case of conflict, command line path
350
mappings override path mappings from the file.
352
<h3>Summary of all the options</h3>
354
Each of the options beginning with a single hypen (<code>-</code>)
355
require an argument, as in
357
HTMLLinker Documentation -LinksMarker gsdoc -d Documentation
359
which sets <code>LinksMarker</code> to <code>gsdoc</code>. The
360
options might be anywhere on the command line. Options which do
361
not begin with a single hypen (such as <code>--help</code>) do not
362
require an argument, as in
369
Followed by a destination HTML file, or a directory containing
370
destination HTML files.
374
Followed by a relocation file, or a directory containing relocation files.
376
<h4>-FixupAllLinks</h4>
378
If set to <code>NO</code> (the default) only links containing the
379
<code>rel</code> attribute set to <code>dynamic</code> (or
380
whatever specified as <code>LinksMarkers</code>)are fixed up in
381
the input files. If set to <code>YES</code>, all links are fixed
384
<h4>-LinksMarker</h4>
386
If set (and if <code>FixupAllLinks</code> is <code>NO</code>),
387
only links with the <code>rel</code> attribute set to its value
388
are processed. By default it is set to <code>dynamic</code>.
390
<h4>-PathMappings</h4>
392
If set to a dictionary, read the dictionary as path mappings. See
393
above for more details of path mappings.
395
<h4>-PathMappingsFile</h4>
397
If set to a string, consider it to be the name of a file; read
398
path mappings from that file. The file must contain the path
399
mappings in the form of a dictionary. See above for more details
404
If set to <code>YES</code> prints some more messages than if set
405
to <code>NO</code> (the default).
409
Prints a quick explanation of the command line syntax and exits.
413
Prints the version and exits.
added
removed
Tools/HTMLLinker.gsdoc
