(no subject)

[Nicola Pero]

It took me the whole day but I've written my HTMLLinker.

It's quite a generic tool and does not depend on any of the conventions
used in the gsdoc/autogsdoc tools - you can freely change those
conventions without having to touch the linker.  The provided
functionality should greatly simplify the gsdoc/autogsdoc architecture,
and make it more powerful.

The engine of the linker is perfectly working ... as far as my little
tests went.  It is possible that it contains bugs in the parsing code as
it's fresh newly-born software, just-out-of-the-oven - but nothing
essential, we just fix them as we discover them - the engine is done.

the problem now is how to control the engine from the command line ... to
choose the command line options to run the linker comfortably.

there are lot of possible options for the linker.

first, we want to specify the input files - the files which the linker
should fix up.  Easy enough, you list them on the command line and that's
it - the easy part.

second, we want to specify the destination files - the files which can be
the destinations of links in the input files.  This is less easy.  Now,
these files come after a --Destionations option on the command line.  But
- first, on a system there are probably tons of those files, we need to
list them all on the command line, unless we accept directories as well
and the tool will read - recursively - all the .html files in the
specified directories (what we want to do is of course to pass the
GNUSTEP_LOCAL_ROOT/Documentation directory and have it use all .html files
there as destination files.  but now the problem is we need to keep the
javadoc's generated .html files out of our way!  So perhaps we should
agree to install all autogsdoc-generated files into
GNUSTEP_LOCAL_ROOT/Documentation/Autogsdoc/ or something like that, so
that we can easily name them all by specifying that directory to the
linker ? this would fix the problems)

Last, we want to consider what happens when you want to install the stuff
into a web server.  The problem here is that you might have different
destination files around the filesystem, but the URI corresponding to the
files should be *different* from the actual filesystem path.  For example,
you expose your /usr/GNUstep/System/Documentation/Autogsdoc and your
/usr/GNUstep/Local/Documentation/Autogsdoc as
http://xxx/GNUstepDoc/System/ and http://xxx/GNUstepDoc/Local/
respectively.  Now the linker needs to read the files from the filesystem
location (to check that the links are correct) but needs to fixup the
links using a different name.  It's all ready in the linker code, just we
need to invent comfortable command-line arguments to tell the linker about
this special situation.

Perhaps something like 

HTMLLinker test.html --Destionations \
           /usr/GNUstep/System/Documentation/Autogsdoc \
           --ReferToAs /GNUstepDoc/System \
           /usr/GNUstep/Local/Documentation/Autogsdoc \
           --ReferToAs /GNUstepDoc/Local 

?

Any suggestions for the options ?