mirror of
https://github.com/gnustep/libs-base.git
synced 2025-04-23 09:04:13 +00:00
Correct commit file
git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@25014 72102866-910b-0410-8b05-ffd578937521
This commit is contained in:
Adam Fedor
parent
9eec14aa14
commit
d918d7535f
1 changed files with 0 additions and 415 deletions
|
|
@ -18,421 +18,6 @@
|
|||
If not, write to the Free Software Foundation,
|
||||
59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
|
||||
|
||||
<chapter>
|
||||
<heading>The HTMLLinker tool</heading>
|
||||
<section>
|
||||
<heading>Introduction</heading>
|
||||
<p>
|
||||
The GNUstep HTML linker is able to fixup links from one HTML
|
||||
document to other HTML ones. By link we mean the standard
|
||||
<code><a href="NSString.html#DescriptionOfNSString"></code>
|
||||
tag. By fixing up a link we mean to modify the path in the
|
||||
<code>href</code> so that it points to the actual file on disk.
|
||||
For example, if you the <code>DescriptionOfNSString</code>
|
||||
location is in the file <code>NSStringOverview.html</code> in the
|
||||
directory <code>/home/nicola/Doc</code>, when the linker fixes up
|
||||
the <code><a
|
||||
href="NSString.html#DescriptionOfNSString"></code> link, it
|
||||
will replace it with <code><a
|
||||
href="/home/nicola/Doc/NSStringOverview.html#DescriptionOfNSString"></code>.
|
||||
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 <code>DescriptionOfNSString</code>
|
||||
in the example).
|
||||
|
||||
<h4>Practical Usage of the linker</h4>
|
||||
|
||||
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
|
||||
<code>function$function_name</code>. For example, the place in
|
||||
the doc where it documents the <code>start_library()</code>
|
||||
function would have the HTML tag <code><a
|
||||
name="function$start_library"></code>. Having established this
|
||||
convention, in any HTML file in your documentation in which you
|
||||
want to create a link to the documentation for the
|
||||
<code>start_library()</code> function, you use the code
|
||||
<code><a rel="dynamic"
|
||||
href="#function$start_library"></code> (please note that you
|
||||
ignore the problem of locating the actual file which contains the
|
||||
documentation for the <code>start_library()</code> 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
|
||||
<pre>
|
||||
HTMLLinker -BuildRelocationFileForDir Documentation
|
||||
</pre>
|
||||
if for example the project documentation is in the
|
||||
<code>Documentation</code> subdirectory. This will create a
|
||||
<code>Documentation/table.htmlink</code> 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
|
||||
<code>/opt/gnustep/Local/Documentation/MyProject</code>), and once
|
||||
it's installed, you can run the linker to update all links so that
|
||||
they point to the actual files
|
||||
<pre>
|
||||
HTMLLinker /opt/gnustep/Local/Documentation/MyProject \
|
||||
-l /opt/gnustep/Local/Documentation/MyProject \
|
||||
-l /opt/gnustep/Local/Documentation/MyOtherProject
|
||||
</pre>
|
||||
This will fixup all links in <code>MyProject</code>'s HTML files
|
||||
by using the relocation files of both <code>MyProject</code> and
|
||||
<code>MyOtherProject</code>, so all links to anything which is
|
||||
documented inside those files will be generated correctly.
|
||||
|
||||
<h4>Usage of the tool with autogsdoc</h4>
|
||||
|
||||
You can use the tool with documentation generated by autogsdoc to
|
||||
perform the linking (or to relink it). Make sure to use the option
|
||||
<code>-LinksMarker gsdoc</code> because autogsdoc marks the links
|
||||
to be fixed up by the linker by using <code>rel="gsdoc"</code>.
|
||||
|
||||
<h3>Specification</h3>
|
||||
|
||||
<h4>Modes of operation</h4>
|
||||
The HTML linker works in two phases:
|
||||
|
||||
<ul>
|
||||
|
||||
<li> The first (called <i>generation of the relocation
|
||||
table</i>) preprocesses a given set of HTML files so that it can
|
||||
be the destination of links. It builds a relocation table for
|
||||
the given set of HTML files. This relocation table simply maps
|
||||
all names (as in <code><a name="xxx"></code>) 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 <i>relocation files</i>).
|
||||
</li>
|
||||
|
||||
<li> The second (called <i>linking</i>) links a given file to
|
||||
the available HTML files on disk, by using the relocation table
|
||||
to modify the HTML links in the file so that they point to
|
||||
existing files.
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
|
||||
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 <code>table.htmlink</code> file
|
||||
in that directory for later reuse.
|
||||
|
||||
There are three kinds of files:
|
||||
|
||||
<ul>
|
||||
|
||||
<li>
|
||||
<em>input files</em>: these are HTML files which are modified
|
||||
as a consequence of linking; they have their links fixed up.
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<em>destination files</em>: these are HTML files which are
|
||||
read to produce relocation tables.
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<em>relocation files</em>: these files are not HTML files -
|
||||
they are only created and read by the linker (unless you have
|
||||
a tool which can manage them), and are in a specific - very
|
||||
simple - format. They are used to save relocation information
|
||||
for later reuse, so that the linker can run faster. Normally,
|
||||
they have a <code>.htmlink</code> extension.
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
|
||||
<h4>Linker behaviour</h4>
|
||||
|
||||
The linker keeps a main relocation table, which is empty at the
|
||||
beginning. When run, the linker performs the following steps:
|
||||
|
||||
<ol>
|
||||
<li>
|
||||
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.
|
||||
</li>
|
||||
<li>
|
||||
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.
|
||||
</li>
|
||||
<li>
|
||||
if any input files are specified on the command line, the
|
||||
linker links the files using the relocation table.
|
||||
</li>
|
||||
</ol>
|
||||
|
||||
<h4>Specifying input, destination and relocation files</h4>
|
||||
|
||||
All command line arguments which do not begin with a hypen
|
||||
(<code>-</code>), and which are not the values of defaults (for
|
||||
example, not the <code>YES</code> in <code>-Warn YES</code>,
|
||||
because that is the value of the default <code>-Warn</code>), are
|
||||
interpreted as input files. Each destination file is specified by
|
||||
using a <code>-d</code> option, and each relocation file by using
|
||||
a <code>-l</code> 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:
|
||||
<code>.html</code>, <code>.HTML</code>, <code>.htm</code> or
|
||||
<code>.HTM</code>. 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
|
||||
<code>.htmlink</code>. A typical invocation of the linker is as
|
||||
follows:
|
||||
<pre>
|
||||
HTMLLinker -BuildRelocationFileForDir Doc
|
||||
</pre>
|
||||
Builds a relocation file for the documentation in the
|
||||
directory <code>Doc</code>. After this has been done, the
|
||||
directory <code>Doc</code> can be used as a <code>-l</code>
|
||||
argument.
|
||||
<pre>
|
||||
HTMLLinker test.html -l Doc
|
||||
</pre>
|
||||
Links the file <code>test.html</code> using the relocation file
|
||||
just generated in the <code>Doc</code> directory.
|
||||
|
||||
<h4>What is a link</h4>
|
||||
|
||||
A link is an anchor tag with and <code>href</code>, such as
|
||||
<code><a href="dest.html#location"></code>. The destination
|
||||
file of the link is the file specified in the <code>href</code>;
|
||||
<code>dest.html</code> in the example. The destination file is
|
||||
ignored by the linker; the name of the link (which is everything which
|
||||
follows the <code>#</code>) is used to perform the linking.
|
||||
|
||||
<h4>Which links are fixed up</h4>
|
||||
|
||||
Normally, the linker will only fixup links which have the
|
||||
<code>rel</code> attribute set to <code>dynamic</code>, as in the
|
||||
following example: <code><a href="nicola.html"
|
||||
rel="dynamic"></code>. 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 <code>-LinksMarker</code> options, as in
|
||||
<code>-LinksMarker gsdoc</code>, which causes the linker to fixup
|
||||
all links with the <code>rel</code> attribute set to
|
||||
<code>gsdoc</code> rather than <code>dynamic</code>. In certain
|
||||
situations you might want to force the linker to attempt to fixup
|
||||
all links; you can run the linker with the <code>-FixupAllLinks
|
||||
YES</code> option to cause this behaviour. As a special
|
||||
exception, links which obviously are not to be fixed up, such as
|
||||
links beginning with <i>mailto:</i> or <i>news:</i>, or links
|
||||
without a name, are never fixed up.
|
||||
|
||||
<h4>How links are fixed up </h4>
|
||||
|
||||
When the HTML linker encounters a link which needs to be fixed up
|
||||
(say <code><a href="dest.html#location"></code>), it
|
||||
searches the relocation table for a destination file which
|
||||
contains the <code>location</code> 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 <code><a
|
||||
href="#location"></code>. 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
|
||||
<code>/home/nicola/Doc/dest.html</code> contains the name
|
||||
<code>location</code>, the HTML linker will fixup the link to be
|
||||
<code><a href="/home/nicola/Doc/dest.html#location"></code>
|
||||
(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
|
||||
<code>NSObject.html</code> and <code>NSString.html</code> both
|
||||
containing the name <code>init</code>, then the linker can't
|
||||
resolve <code><a href="#init"></code>, 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
|
||||
<code>NSObject_i_init</code> and <code>NSString_i_init</code> if
|
||||
the first link is in the place documenting the <code>-init</code>
|
||||
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.
|
||||
|
||||
<h4>How links are checked</h4>
|
||||
|
||||
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.
|
||||
|
||||
<h4>Path mappings</h4>
|
||||
|
||||
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
|
||||
<code>/opt/doc/base</code> and some other HTML documentation in
|
||||
<code>/opt/doc/gui</code>. 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 <code>/Base</code> (meaning as in
|
||||
requests from a browser of the form
|
||||
<code>http://www.server.org/Base</code>) by taking files from
|
||||
<code>/opt/doc/base</code>, and URLs beginning with
|
||||
<code>Gui</code> by taking files from <code>/opt/doc/gui</code>.
|
||||
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
|
||||
<pre>
|
||||
-PathMapping '{ "/opt/doc/base"="/Base"; "/opt/doc/gui"="/Gui"; }'
|
||||
</pre>
|
||||
to the linker.
|
||||
|
||||
Each path mapping maps a <em>path on disk</em> to a <em>virtual
|
||||
path</em>. For example, it maps the path on disk
|
||||
<code>/opt/doc/base</code> to the virtual path <code>/Base</code>.
|
||||
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 <em>path on disk</em>
|
||||
of one of the path mappings, then that <em>path on disk</em> is
|
||||
replaced with the corresponding <em>virtual path</em> 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 <code><a
|
||||
href="hi.html#nicola"></code>, where the destination file is
|
||||
<code>/opt/doc/base/nicola/hi.html</code>, then the destination
|
||||
path matches the path mapping for <code>/opt/doc/base</code>, so
|
||||
the path mapping is applied and the link is fixed up to be
|
||||
<code><a href="/Base/nicola/hi.html#nicola"></code> rather than
|
||||
<code><a href="/opt/doc/base/nicola/hi.html#nicola"></code> as it
|
||||
would normally have been without the path mapping.
|
||||
|
||||
<h4>Specifying path mappings</h4>
|
||||
|
||||
<h5>On the command line</h5>
|
||||
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
|
||||
<code>-PathMappings</code>, as in
|
||||
<pre>
|
||||
-PathMappings '{ "/opt/doc/base"="/Base"; "/opt/doc/gui"="/Gui"; }'
|
||||
</pre>
|
||||
where <code>/opt/doc/base</code> and <code>/opt/doc/gui</code> are
|
||||
the paths on disk and <code>/Base</code> and <code>/Gui</code> are
|
||||
the corresponding web server URL paths.
|
||||
|
||||
<h5>In a path mappings file</h5>
|
||||
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
|
||||
<pre>
|
||||
{
|
||||
"/opt/doc/base"="/Base";
|
||||
"/opt/doc/gui"="/Gui";
|
||||
}
|
||||
</pre>
|
||||
and then tell the linker to read the path mappings from that file,
|
||||
by giving the filename as option to the
|
||||
<code>-PathMappingsFile</code>. For example, if the file
|
||||
containing the mappings is called <code>mappings</code>, then you need
|
||||
to pass
|
||||
<pre>
|
||||
-PathMappingsFile mappings
|
||||
</pre>
|
||||
to the linker to have it read mappings from the file.
|
||||
|
||||
<h5>Command line path mappings override file path mappings</h5>
|
||||
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.
|
||||
|
||||
<h3>Summary of all the options</h3>
|
||||
|
||||
Each of the options beginning with a single hypen (<code>-</code>)
|
||||
require an argument, as in
|
||||
<pre>
|
||||
HTMLLinker Documentation -LinksMarker gsdoc -d Documentation
|
||||
</pre>
|
||||
which sets <code>LinksMarker</code> to <code>gsdoc</code>. The
|
||||
options might be anywhere on the command line. Options which do
|
||||
not begin with a single hypen (such as <code>--help</code>) do not
|
||||
require an argument, as in
|
||||
<pre>
|
||||
HTMLLinker --help
|
||||
</pre>
|
||||
|
||||
<h4>-d</h4>
|
||||
|
||||
Followed by a destination HTML file, or a directory containing
|
||||
destination HTML files.
|
||||
|
||||
<h4>-l</h4>
|
||||
|
||||
Followed by a relocation file, or a directory containing relocation files.
|
||||
|
||||
<h4>-FixupAllLinks</h4>
|
||||
|
||||
If set to <code>NO</code> (the default) only links containing the
|
||||
<code>rel</code> attribute set to <code>dynamic</code> (or
|
||||
whatever specified as <code>LinksMarkers</code>)are fixed up in
|
||||
the input files. If set to <code>YES</code>, all links are fixed
|
||||
up.
|
||||
|
||||
<h4>-LinksMarker</h4>
|
||||
|
||||
If set (and if <code>FixupAllLinks</code> is <code>NO</code>),
|
||||
only links with the <code>rel</code> attribute set to its value
|
||||
are processed. By default it is set to <code>dynamic</code>.
|
||||
|
||||
<h4>-PathMappings</h4>
|
||||
|
||||
If set to a dictionary, read the dictionary as path mappings. See
|
||||
above for more details of path mappings.
|
||||
|
||||
<h4>-PathMappingsFile</h4>
|
||||
|
||||
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.
|
||||
|
||||
<h4>-Verbose</h4>
|
||||
|
||||
If set to <code>YES</code> prints some more messages than if set
|
||||
to <code>NO</code> (the default).
|
||||
|
||||
<h4>--help</h4>
|
||||
|
||||
Prints a quick explanation of the command line syntax and exits.
|
||||
|
||||
<h4>--version</h4>
|
||||
|
||||
Prints the version and exits.
|
||||
|
||||
<hr>
|
||||
<address><a href="mailto:n.pero@mi.flashnet.it">Nicola Pero</a></address>
|
||||
<!-- Created: Fri Jan 4 08:30:07 GMT 2002 -->
|
||||
<!-- hhmts start -->
|
||||
Last modified: Sun Jan 6 22:54:58 GMT 2002
|
||||
<!-- hhmts end -->
|
||||
</body>
|
||||
</html>
|
||||
|
||||
|
||||
*/
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue