Re: (no subject)

[Richard Frith-Macdonald]

On Thursday, January 3, 2002, at 04:47 PM, Nicola Pero wrote:

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

I also added html relocation code to autogsdoc today ... does this mean
I have been wasting my time?

> 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.

Not sure how it would do that ... but being able to relocate html files
in general, rather than just gsdoc output files seems like a good thing.

> 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.

If I understand correctly, the idea is that supplying an argument like
--Destination /some-path/file.html will cause all occurances of
<a href="file.html..."> to become <a href="/some-path/file.html">
Does that mean that an html file can be linked only once?
I thought the idea was to be able to re-link it as many times as you 
might want ...
perhaps I've missed how that works.

> 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)

At present the autogsdoc tool and makefile stuff is set up to put the
documentation for a particular project in a single directory ... so if
you wanted to run things project by project there would be no problem.

And I don't see why there should be a problem with javadoc generated
html anyway.

I guess part of my problem is that I don't actually understand what
functionality this tool is intended to add to the autogsdoc stuff
and why it would not equally well apply to javadoc documentation.


> 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 ?

You could do it the way autogsdoc does it ...

eg.
-Projects '{Base.igsdoc = "http://www.gnustep.org/Documentation/Base";; 
Gui.igsdoc = "http://www.gnustep.org/Documentation/Gui";}'

Since HTMLLinker seems to be designed ot work on a per-document basis 
rather than a per-project basis, the
mappings would want to be from file names to full URLs rather than from 
project index files to partial URLs,
but the principle is the same.