[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: (no subject)

From: Richard Frith-Macdonald
Subject: Re: (no subject)
Date: Thu, 3 Jan 2002 23:03:17 +0000

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.

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

-Projects '{Base.igsdoc = "";; Gui.igsdoc = "";}'

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.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]