Re: Problem with (using) autogsdoc

[Richard Frith-Macdonald]

On Monday, September 16, 2002, at 11:23 PM, Chris B. Vetter wrote:

> On Mon, 16 Sep 2002 23:15:26 +0100
> Richard Frith-Macdonald <richard@brainstorm.co.uk> wrote:
> > On Monday, September 16, 2002, at 08:47 PM, Chris B. Vetter wrote:
> > > Hi,
> > > I'm having some problems using 'autogsdoc' to document some source
> > > code. It does a reasonable good job on "flat" directory layouts, that
> > > is, one directory containing all the source and the GNUmakefile(s).
> > > There seems to be a (minor) problem though, that Functions.html does
> > > not have an [Up]
> > > link, even when specifically defined in xxx_AGSDOC_FLAGS.
> > I guess that's because Functions.gsdoc is a template into which the
> > function documentation is inserted, rather than a wholly generated
> > document. Perhaps that should be changed (or the default content of the
> > template should take account of the flags).
>
> Since the classes files do have the [Up] link, I think it's not that
> tragic. Would be nice though.
>
> [...]
> > > What would be the easiest way to create the HTML/gsdoc documentation
> > > with MyFramework.html as the "index" file? I always end up either
> > > overriding the previous entries in MyFramework.html, or 'autogsdoc'
> > > complaining about sth like "<xxx>.m not where expected"...
> > Something like this in the top level makefile ...
> > DOCUMENT_NAME=MyFramework
> > MyFramework_AGSDOC_FILES =\
> >      MyFramework.gsdoc \
> >      Extension.subproj/Extension1.h \
> >      Extension.subproj/Extension2.h \
> >      Extension.subproj/Extension3.h \
> >      Functions.subproj/Functions1.h \
> >      Functions.subproj/Functions2.h \
> >      PrincipalClass.h \
> >      SubClass1.subproj/SubClass1.h \
> >      SubClass2.subproj/SubClass2.h \
>
> That's what I thought, too - alas that's when I get the "XXX.m source
> file is not where expected" warnings/errors. And the index of
> MyFramework.html ONLY contains links to the LAST processed XXX.h 
> file(s).
>
> I used '-Verbose YES' in AGSDOC_FLAGS, and noticed that [parser source]
> (I think) takes 'directory/file.h' and cuts off the 'directory/' part to
> create 'file.m'. That would explain, why it can't find the source file.

Ah ... I think I'd consider that a bug then ... I'll look into it when I
have time.

In the meantime, there is a workaround/hack, in that you can list the
source files used by a header within the header itsself and thus control
which files are used explicitly for each header.  The paths listed for
source files can be either absolute, or relative to the directory in
which autogsdoc is running (though perhaps that should be changed so
that paths are interpreted relative to the location of the header?)

eg. Put the following in a header to use two source files for it -

/**
 * AutogsdocSource:    Functions.subproj/Functions1.m
 * AutogsdocSource:    Functions.subproj/Functions2.m
 */