Re: (no subject)

[Nicola Pero]

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

Possibly ... I didn't know you were.  I wouldn't probably have written it
had I realized that.

Anyway, HTMLLinker does not need libxml.  That means people without libxml
can download the prebuild HTML documentation, and then install it;
HTMLLinker can fixup all the links in the final html files, so they can
install it wherever they want, fixup the links with HTMLLinker and the
links will be OK.  Because the idea is that the HTMLLinker is
automatically run by gnustep-make when the .html files are installed (and
you wouldn't even know it's run unless you are inside how the thing
works), that means they can install the pregenerated documentation
wherever they want on the filesystem, even if they don't have
libxml/autogsdoc.

HTMLLinker should be pretty fast as well, it hardly reads the HTML files
it processes.

In my idea, while generating the documentation requires a full-blown
XML/HTML tool, fixing up the links in the final html files should only
require a little fast tool always available.

And because it's so fast, we can run it so often. :-)

The other point is that I think it's a good idea to try and break the
process into littler steps ... having separated all the 'linking' stage
into a final separate tool means that - in practice - autogsdoc does not
need any code for managing references any longer!

I'm sure there is some - perhaps a lot of - overlap with facilities
already provided by autogsdoc.  I'm sorry about that - but I think the
HTMLLinker as a separate non-libxml tool is the definitive solution for
our reference problems and issues.

The .html files can then be generated by autogsdoc/gsdoc with 'naive'
references.  Then HTMLLinker (which now comes bundled with gnustep-base
even if you don't have libxml) resolves those references to actual paths
on disk (or on the web server) when the documentation is installed, or
moved, or updated.

I think the whole .igsdoc files framework can be dropped.


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

And also all occurrances of 

<a href="/some-other-path/file.html" rel="dynamical">

to be fixed up in the same way (anything with last path component of
'file.html' gets fixed up in the same way).  For this to work properly,
file names must be chosen in a unique manner :-)

The idea is that if a file contains documentation for a certain class,
it's named after the class, and since the classes all share the same
namespace and classnames are unique, filenames should be unique as well.  
(But then there are protocols, and you want NSObject class to be different
from NSObject protocol ... so it's a little more complex but anyway the
concept still holds).

HTMLLinker does not depend on the convention you use in autogsdoc to name
files ... it only requires you to establish one ... that is, you should
never have two different .html files with the same name.


> Does that mean that an html file can be linked only once?

Not sure what you mean - if you mean running the linker on an html file
more than once, re-fixing the links in the file, yes you can run it as
many times as you want :-).  That's the good point of it :-) you can
re-link at will.

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

Well, all .html destination files share the same namespace ... not sure if
that is a problem, depends on the convention used to name files - I
thought that javadoc files might have conflicting .html names - but you're
probably right, there should/might be no problem.  What I was thinking as
a problem is, eg, if the javadoc for NSObject, say, is called
NSObject.html, then it would be a conflict if gnustep-base's doc for
NSObject is also called NSObject.html ...

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

I'm not quite sure what functionality is included in the autogsdoc stuff,
but I see there are .igsdoc files et similia to build references, and my
feeling is that if the .html output of autogsdoc is suited to be processed
by the HTMLLinker, I don't see why autogsdoc would need to do anything at
all to build references.  I don't like (no longer like) the idea that
projects should have index files and that you resolve/check references by
looking at those index files.  I far prefer the idea that you build up
freely all the links you want following some predetermined convention, and
the links are resolved and checked at link time.  HTMLLink *does* check
that all links are resolved if run with -CheckLinks YES, and warns about
any unresolved link.

I'm not sure the tool can be used to relink javadoc documentation ... I'd
need to inspect how filenames and links are build in the javadoc .html
files.  In general, the tool as it is will not touch any link in a javadoc
.html file because it only fixup links having rel=dynamical (I thought it
was a good idea to mark out the links to fixup from the links *not* to
fixup, I think you do the same with rel=gsdoc - since HTMLLinker can be
used outside gsdoc, I use rel=dynamical), but it can of course easily be
modified to fixup all links ... I don't think it's a good idea though.

> > 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";}'

Ok - so that would mean something like 

-Projects '{"/usr/GNUstep/System/Documentation/Base" = "/Documentation/Base";
"/usr/GNUstep/System/Documentation/Gui" = "/Documenation/Gui";}'
 
that would mean to consider all .html files inside
/usr/GNUstep/System/Documentation/Base/ and subdirs as potential
destination files, and - when fixing up links to them - use
/Documentation/Base/ as the base path to them.

Makes sense.

I'll also allow you to specify a file containing a dictionary of mappings.

> 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 

Yes

I don't want to insist on the virtues of HTMLLinker also considering that
I wouldn't have written the HTMLLinker at all if I realized you were
implementing the html relocation in autogsdoc itself ... even if I truly
prefer the separate fast non-libxml HTMLLinker tool, it was tiresome to
write, for natural laziness I wouldn't probably have done all this work
even if I thought it was good.  Almost certain.  :-)  But since I've now
done it, let's try to take advantage of it.

I'll clear and complete the command line options tomorrow, then well this
one - the HTML linker - was meant to be my personal contribution to the
success of autogsdoc :-) - you can do what you want with it - I hope it
fits somewhat - to me it looked like I designed it enough general purpose
that it would brilliantly fit as the latest stage in most html
documentation generation frameworks, in particular, with some changes
perhaps to autogsdoc, in autogsdoc.  I also think it should simplify the
previous stages ... relieve them of cross-reference issues almost
completely ... drop all .igsdoc in this case ... drop all -Projects and
-LocalProjects and stuff ... drop all link code ...  should be a
consistent simplification.

Having a separate linker program with a clean separate specification and
API means that separate people can more easily work on them as separate
(cooperating) pieces of software ... the linker can have its own options
and bloatings, separated from autogsdoc.  I quite like the idea that it's
a separate software and it does not depend on the internal conventions of
(auto)gsdoc.  Btw, the HTML linker seems to really have uses outside
autogsdoc.

The other thing to do - *before* we do the gnustep-make and gnustep-base
release, is to write the appropriate make rules.  I wanted to write those
this morning, then saw the linker was missing, so thought I would
contribute it, wrote it.  I'll see if I can write them perhaps tomorrow.