Resolving cross-references among components

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

Resolving cross-references among components

David Nečas (Yeti)-2

Hello, what is the recommended method/best practice for getting right
bidirectional cross-references in documentation?

Imagine a project that builds two libraries, libA and libB, with
separate documentation.  If documentation for libA is built while
index.sgml in libB documentation does not exist yet, cross-links from A
to B will not resolve.  And vice versa.  Even if B strictly depends on A
one may want to reference B from the documentation of A to point out
implementations of abstractions, more high-level facilities or other
code in B that builds on A's features.

Since index.sgml is distributed anyone who rebuilds the documentation
from a tarball will get cross-references both ways right.  But what
about fresh checkouts?  I can only think of two ways to get correct
cross-references, one uglier than the other:
- build documentation twice
- keep index.sgml in the version control system

Yeti

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

Re: Resolving cross-references among components

Stefan Sauer-4
On 11/18/2012 12:12 AM, David Nečas wrote:

> Hello, what is the recommended method/best practice for getting right
> bidirectional cross-references in documentation?
>
> Imagine a project that builds two libraries, libA and libB, with
> separate documentation.  If documentation for libA is built while
> index.sgml in libB documentation does not exist yet, cross-links from A
> to B will not resolve.  And vice versa.  Even if B strictly depends on A
> one may want to reference B from the documentation of A to point out
> implementations of abstractions, more high-level facilities or other
> code in B that builds on A's features.
>
> Since index.sgml is distributed anyone who rebuilds the documentation
> from a tarball will get cross-references both ways right.  But what
> about fresh checkouts?  I can only think of two ways to get correct
> cross-references, one uglier than the other:
> - build documentation twice
> - keep index.sgml in the version control system
I can't add anything here. Do you have a case where this happens? I
would probably build twice as checking in generated files lead to all
sort of hassle :/
>
> Yeti
>
> _______________________________________________
> gtk-doc-list mailing list
> [hidden email]
> https://mail.gnome.org/mailman/listinfo/gtk-doc-list

Stefan

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

Re: Resolving cross-references among components

David Nečas (Yeti)-2
On Sun, Nov 18, 2012 at 09:44:27PM +0100, Stefan Sauer wrote:
> I can't add anything here. Do you have a case where this happens?

It should happen everywhere.  For instance, Gdk references Gtk+ symbols
dozens of times.  Why almost no one observes it?  Most of the time if
you build Gtk+, even from a fresh checkout, you already have *some* Gtk+
installed.  So gtkdoc-fixxref takes index.sgml from the system directory.
Occasionally, you miss a couple of new symbols, but who notices it...

I run into this during nightly builds of Gwyddion (too complex to serve
as a clear example) that are done in a relatively clean environment.
Certainly it is not installed anywhere where it could be picked up
during the build.

It would suffice to split the fixxref stage off the normal HTML building
stange and run it once that is done in all subdirectories.  But this
is not possible within gtk-doc.make, it requires the introduction of
some HTML-has-been-built stamp on the package level (or at least inside
some docs subdirectory).

Yeti

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

Re: Resolving cross-references among components

Stefan Sauer-4
On 11/18/2012 10:59 PM, David Nečas wrote:

> On Sun, Nov 18, 2012 at 09:44:27PM +0100, Stefan Sauer wrote:
>> I can't add anything here. Do you have a case where this happens?
> It should happen everywhere.  For instance, Gdk references Gtk+ symbols
> dozens of times.  Why almost no one observes it?  Most of the time if
> you build Gtk+, even from a fresh checkout, you already have *some* Gtk+
> installed.  So gtkdoc-fixxref takes index.sgml from the system directory.
> Occasionally, you miss a couple of new symbols, but who notices it...
>
> I run into this during nightly builds of Gwyddion (too complex to serve
> as a clear example) that are done in a relatively clean environment.
> Certainly it is not installed anywhere where it could be picked up
> during the build.
>
> It would suffice to split the fixxref stage off the normal HTML building
> stange and run it once that is done in all subdirectories.  But this
> is not possible within gtk-doc.make, it requires the introduction of
> some HTML-has-been-built stamp on the package level (or at least inside
> some docs subdirectory).
>
> Yeti
>
If we want to fix this we probably need to make it so that docA/html
depends on doc{A,B}/index.sgml and docB/html likewise. That is we need
to first run gtkdoc-mkdb in all doc modules and then continue with
gtkdoc-mkhtml and gtkdoc-fixxref.

That said, I don't feel like hacking that into our current makefiles :/

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