gnustep/libs-base
0
0
Fork 0
mirror of https://github.com/gnustep/libs-base.git synced 2025-05-31 08:41:03 +00:00
Code Issues Projects Releases Packages Wiki Activity

Removed tool which nobody was using and which was just bloating the library

Browse source 
git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@17275 72102866-910b-0410-8b05-ffd578937521
This commit is contained in:
nico 2003-07-21 09:58:54 +00:00
parent 2c6ab181bd
commit 3b0f126539
4 changed files with 8 additions and 1768 deletions
Download patch file Download diff file Expand all files Collapse all files

6
ChangeLog
View file

@ -1,3 +1,9 @@
Mon Jul 21 11:03:48 2003 Nicola Pero <n.pero@mi.flashnet.it>
* Tools/HTMLLinker.m: Removed.
* Tools/HTMLLinker.html: Removed.
* Tools/GNUmakefile: Do not compile it.
2003-07-20 Richard Frith-Macdonald <rfm@gnu.org> 2003-07-20 Richard Frith-Macdonald <rfm@gnu.org>
* Source/NSProxy.m: Implement essential methods for a proxy to be * Source/NSProxy.m: Implement essential methods for a proxy to be

8
Tools/GNUmakefile
View file

@ -50,7 +50,7 @@ ifeq ($(add),yes)
TOOL_NAME = autogsdoc TOOL_NAME = autogsdoc
else else
TOOL_NAME = autogsdoc cvtenc gdnc defaults plmerge \ TOOL_NAME = autogsdoc cvtenc gdnc defaults plmerge \
plparse sfparse pldes plser pl2link HTMLLinker xmlparse plparse sfparse pldes plser pl2link xmlparse
CTOOL_NAME = gdomap CTOOL_NAME = gdomap
SUBPROJECTS = make_strings SUBPROJECTS = make_strings
@ -75,13 +75,9 @@ plparse_OBJC_FILES = plparse.m
sfparse_OBJC_FILES = sfparse.m sfparse_OBJC_FILES = sfparse.m
pl2link_OBJC_FILES = pl2link.m pl2link_OBJC_FILES = pl2link.m
locale_alias_OBJC_FILES = locale_alias.m locale_alias_OBJC_FILES = locale_alias.m
HTMLLinker_OBJC_FILES = HTMLLinker.m
xmlparse_OBJC_FILES = xmlparse.m xmlparse_OBJC_FILES = xmlparse.m
DOCUMENT_NAME = autogsdoc HTMLLinkerDoc DOCUMENT_NAME = autogsdoc
HTMLLinkerDoc_DOC_INSTALL_DIR = Developer/Tools
HTMLLinkerDoc_INSTALL_FILES = HTMLLinker.html
# Documentation rules for autogsdoc # Documentation rules for autogsdoc
autogsdoc_AGSDOC_FLAGS = -Up autogsdoc autogsdoc_AGSDOC_FLAGS = -Up autogsdoc

422
Tools/HTMLLinker.html
View file

@ -1,422 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
<head>
<title>The GNUstep HTML Linker</title>
</head>
<body bgcolor="white" text="black" alink="red" vlink="purple" link="blue">
<h1>The GNUstep HTML Linker</h1>
<h3>Introduction</h3>
<h4>What the HTML linker does</h4>
The GNUstep HTML linker is able to fixup links from one HTML
document to other HTML ones. By link we mean the standard
<code>&lt;a href="NSString.html#DescriptionOfNSString"&gt;</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>&lt;a
href="NSString.html#DescriptionOfNSString"&gt;</code> link, it
will replace it with <code>&lt;a
href="/home/nicola/Doc/NSStringOverview.html#DescriptionOfNSString"&gt;</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>&lt;a
name="function$start_library"&gt;</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>&lt;a rel="dynamic"
href="#function$start_library"&gt;</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>&lt;a name="xxx"&gt;</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>&lt;a href="dest.html#location"&gt;</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>&lt;a href="nicola.html"
rel="dynamic"&gt;</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>&lt;a href="dest.html#location"&gt;</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>&lt;a
href="#location"&gt;</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>&lt;a href="/home/nicola/Doc/dest.html#location"&gt;</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>&lt;a href="#init"&gt;</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>&lt;a
href="hi.html#nicola"&gt;</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>&lt;a href="/Base/nicola/hi.html#nicola"&gt;</code> rather than
<code>&lt;a href="/opt/doc/base/nicola/hi.html#nicola"&gt;</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>

1340
Tools/HTMLLinker.m
View file

File diff suppressed because it is too large Load diff