1.17 cross refs

classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

1.17 cross refs

Philip Kovacs
It's been some time since I rebuilt my docs with gtk-doc and I wanted to comment
about this weird behavior I am seeing with 1.17 and cross refs.  To summarize;

My project, like many gtk-doc projects, has libraries in the tree which contain
references to each other.  An ordinary layout, much like this:

project
-+liba
-+libb
-+docs
--+reference
---+liba
---+libb


Now, liba contains no doc references into libb, but libb contains some references
to liba.  When I build the project, as follows:

./autogen.sh
./configure --enable-gtk-doc [...]
make

the cross references from libb into liba are _not_ created in the source tree.
I get warnings of the form: "warning; no link to:".  After I install the project:

make install

the installed docs also have no links from libb into liba, but here is where it
gets interesting:

_AFTER_ the make install is performed, if I return to the source tree, cd into
the ..docs/reference/libb directory and

make clean
make

the cross references are successfully made in the source tree!  Issuing a new
make install, the valid libb docs are delivered to the installation area. If I
subsequently delete the installation tree, and cd back to the source tree
../docs/reference/libb and

make clean
make

the cross references are broken again.

So, in my situation, it seems that the cross references are being repaired in
the source tree only after gtk-doc has an installation tree to inspect.

Is there something I need to adjust in my project to alleviate this rather
weird behavior?

Phil

 






_______________________________________________
gtk-doc-list mailing list
[hidden email]
http://mail.gnome.org/mailman/listinfo/gtk-doc-list

signature.asc (205 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: 1.17 cross refs

David Nečas (Yeti)-2
On Wed, Sep 14, 2011 at 03:29:13PM -0400, Philip Kovacs wrote:

> project
> -+liba
> -+libb
> -+docs
> --+reference
> ---+liba
> ---+libb
>
>
> Now, liba contains no doc references into libb, but libb contains some references
> to liba.  When I build the project, as follows:
>
> ./autogen.sh
> ./configure --enable-gtk-doc [...]
> make
>
> the cross references from libb into liba are _not_ created in the source tree.

Do you have

FIXXREF_OPTIONS=--extra-dir=../liba/html

in docs/references/libb/Makefile.am?  The symptoms look like you don't.

Yeti

_______________________________________________
gtk-doc-list mailing list
[hidden email]
http://mail.gnome.org/mailman/listinfo/gtk-doc-list
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: 1.17 cross refs

Philip Kovacs
* David Nečas <[hidden email]> [2011-09-14 21:39:04 +0200]:

> On Wed, Sep 14, 2011 at 03:29:13PM -0400, Philip Kovacs wrote:
> > project
> > -+liba
> > -+libb
> > -+docs
> > --+reference
> > ---+liba
> > ---+libb
> >
> >
> > Now, liba contains no doc references into libb, but libb contains some references
> > to liba.  When I build the project, as follows:
> >
> > ./autogen.sh
> > ./configure --enable-gtk-doc [...]
> > make
> >
> > the cross references from libb into liba are _not_ created in the source tree.
>
> Do you have
>
> FIXXREF_OPTIONS=--extra-dir=../liba/html
>
> in docs/references/libb/Makefile.am?  The symptoms look like you don't.
Yes, in fact I do have that line.  Doesn't seem to help.  Still investigating.

Phil

_______________________________________________
gtk-doc-list mailing list
[hidden email]
http://mail.gnome.org/mailman/listinfo/gtk-doc-list

signature.asc (205 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: 1.17 cross refs

Stefan Sauer-4
Am 14.09.2011 22:23, schrieb Philip Kovacs:

> * David Nečas<[hidden email]>  [2011-09-14 21:39:04 +0200]:
>
>> On Wed, Sep 14, 2011 at 03:29:13PM -0400, Philip Kovacs wrote:
>>> project
>>> -+liba
>>> -+libb
>>> -+docs
>>> --+reference
>>> ---+liba
>>> ---+libb
>>>
>>>
>>> Now, liba contains no doc references into libb, but libb contains some references
>>> to liba.  When I build the project, as follows:
>>>
>>> ./autogen.sh
>>> ./configure --enable-gtk-doc [...]
>>> make
>>>
>>> the cross references from libb into liba are _not_ created in the source tree.
>>
>> Do you have
>>
>> FIXXREF_OPTIONS=--extra-dir=../liba/html
>>
>> in docs/references/libb/Makefile.am?  The symptoms look like you don't.
>
> Yes, in fact I do have that line.  Doesn't seem to help.  Still investigating.
>
> Phil
>
I've just tried this locally and it works fine for me. I have release 1.18
today. Maybe you could try with that as well. Also
FIXXREF_OPTIONS=--extra-dir=.. should just work already.

Stefan
_______________________________________________
gtk-doc-list mailing list
[hidden email]
http://mail.gnome.org/mailman/listinfo/gtk-doc-list
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: 1.17 cross refs

Philip Kovacs
* Stefan Kost <[hidden email]> [2011-09-14 22:46:10 +0200]:

> Am 14.09.2011 22:23, schrieb Philip Kovacs:
> > * David Nečas<[hidden email]>  [2011-09-14 21:39:04 +0200]:
> >
> >> On Wed, Sep 14, 2011 at 03:29:13PM -0400, Philip Kovacs wrote:
> >>> project
> >>> -+liba
> >>> -+libb
> >>> -+docs
> >>> --+reference
> >>> ---+liba
> >>> ---+libb
> >>>
> >>>
> >>> Now, liba contains no doc references into libb, but libb contains some references
> >>> to liba.  When I build the project, as follows:
> >>>
> >>> ./autogen.sh
> >>> ./configure --enable-gtk-doc [...]
> >>> make
> >>>
> >>> the cross references from libb into liba are _not_ created in the source tree.
> >>
> >> Do you have
> >>
> >> FIXXREF_OPTIONS=--extra-dir=../liba/html
> >>
> >> in docs/references/libb/Makefile.am?  The symptoms look like you don't.
> >
> > Yes, in fact I do have that line.  Doesn't seem to help.  Still investigating.
> >
> > Phil
> >
> I've just tried this locally and it works fine for me. I have release 1.18
> today. Maybe you could try with that as well. Also
> FIXXREF_OPTIONS=--extra-dir=.. should just work already.
My eyes are not as sharp as they used to be I guess:

FIXXREF_OPTIONS==--extra-dir=../liba/html
       
changed to:

FIXXREF_OPTIONS=--extra-dir=../liba/html

and now it works perfectly.  My apologies.

Phil

_______________________________________________
gtk-doc-list mailing list
[hidden email]
http://mail.gnome.org/mailman/listinfo/gtk-doc-list

signature.asc (205 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: 1.17 cross refs

Philip Kovacs

I observe that the process to build fully linked documentation from a pristine
source tree (dist|maintainer clean) is two-pass when there are subtrees that
have cross references to each other.  This is understandable, as there must be
html files in the subtrees in order to fix the cross references.

So, from a pristine tree, one needs to build, e.g. as follows:

./autogen.sh
./configure --enable-gtk-doc [...]
make (<- observe  crossref errors to subtrees not yet built)
cd docs/reference
make clean
make

Obviously you can adjust the Makefile.am to build the doc subtrees in the desired
order, but when there are circular cross references (subtree a xrefs to b and
b xrefs to a), you must build docs with two make passes.

Phil

_______________________________________________
gtk-doc-list mailing list
[hidden email]
http://mail.gnome.org/mailman/listinfo/gtk-doc-list

signature.asc (205 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: 1.17 cross refs

Stefan Sauer-4
Hi Phil,

On 09/14/11 23:36, Philip Kovacs wrote:
I observe that the process to build fully linked documentation from a pristine 
source tree (dist|maintainer clean) is two-pass when there are subtrees that 
have cross references to each other.  This is understandable, as there must be 
html files in the subtrees in order to fix the cross references.

So, from a pristine tree, one needs to build, e.g. as follows:

./autogen.sh
./configure --enable-gtk-doc [...]
make (<- observe  crossref errors to subtrees not yet built)
cd docs/reference
make clean
make

Obviously you can adjust the Makefile.am to build the doc subtrees in the desired
order, but when there are circular cross references (subtree a xrefs to b and 
b xrefs to a), you must build docs with two make passes.
I'd suggest to adjust the order in Makefile.am. Having circular dependencies will not only bit you when building the docs. We do have a bug for the shortcomings of the fixxref warnings (https://bugzilla.gnome.org/show_bug.cgi?id=658359) although those described there have different reasons. If you can think of a scheme that would address the particualr issues you have, please let us know - I can't think of a solution right now (except building twice).

Stefan
Phil
_______________________________________________ gtk-doc-list mailing list [hidden email] http://mail.gnome.org/mailman/listinfo/gtk-doc-list


_______________________________________________
gtk-doc-list mailing list
[hidden email]
http://mail.gnome.org/mailman/listinfo/gtk-doc-list
Loading...