After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 434134 - fixxrefs like sed for installing pregenerated docs
fixxrefs like sed for installing pregenerated docs
Status: RESOLVED FIXED
Product: gtk-doc
Classification: Platform
Component: general
unspecified
Other Linux
: Normal enhancement
: 1.9
Assigned To: gtk-doc maintainers
gtk-doc maintainers
Depends on:
Blocks: 434720
 
 
Reported: 2007-04-28 15:18 UTC by Stefan Sauer (gstreamer, gtkdoc dev)
Modified: 2007-09-22 19:51 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
implementation (8.66 KB, patch)
2007-07-16 13:10 UTC, Yeti
committed Details | Review

Description Stefan Sauer (gstreamer, gtkdoc dev) 2007-04-28 15:18:55 UTC
we need something that does simillar job like fixxrefs even if there is no gtk-doc available (to use the right xrefs links or remove them if lib is not there).
Comment 1 Behdad Esfahbod 2007-05-16 22:47:29 UTC
CC doesn't hurt.
Comment 2 Damon Chaplin 2007-05-17 09:29:22 UTC
Why can't it just depend on gtk-doc?

This only affects people building from source, doesn't it?
I think that people building from source should just make sure they have gtk-doc.
Comment 3 Behdad Esfahbod 2007-05-17 15:31:21 UTC
I'm been told that rebuilding docs for Gtk+ literally takes hours.  People not touching source shouldn't need to rebuild docs.  If you think they do, what's the point of shipping docs in tarballs then?
Comment 4 Damon Chaplin 2007-05-17 22:01:04 UTC
Oh, I see what you mean - we aren't installing the pregenerated docs properly.

I wouldn't want to create another package just with gtkdoc-fixxref in it.

Maybe we can change the gtk-doc Makefile stuff so that even when gtk-doc
is disabled gtkdoc-fixref is used to install the docs if they are there.
Comment 5 Behdad Esfahbod 2007-05-17 22:57:33 UTC
Exactly.
Comment 6 Behdad Esfahbod 2007-05-18 00:05:20 UTC
It's a bit more complicated.  We want the tarball to have links to online docs for all known modules, and to fix refs to installed docs if they exist only in the installed destination.  So gtk-doc Makefile needs to know both the online location and the installed location (if any).
Comment 7 Damon Chaplin 2007-05-21 10:30:35 UTC
That sounds to me like too much trouble for source tarballs - how many people
use source tarballs as opposed to packages?

It would only help people using source tarballs who don't have all the other
docs installed already, and who need cross-references.
Comment 8 Behdad Esfahbod 2007-05-22 19:41:13 UTC
At the end of the day I don't really care as long as distro-installed docs do the right thing, preferably without having to rebuild docs when building distro packages.
Comment 9 Yeti 2007-07-16 13:10:06 UTC
Created attachment 91854 [details] [review]
implementation

This patch adds gtkdoc-rebase command, to be used on documentation installed into its final location.

It can do the following:
- fix local cross-references to on-line (provided the corresponding packages define the on-line location as suggested in bug 454916, use --online)
- fix on-line location to local
- create either absolute or relative (use --relative) local cross-references
- with a high probability fix random locations from upstream author's system to correct local or on-line locations (use --aggressive)
- take into account the installation into a staging area during distro package build (use --dest-dir) and create relative references even in this case

It is intended to be installed as a part of gtk-doc, but it operates on already installed HTML, therefore the dreaded xsltproc invocation is avoided.

Please test and complain about the bugs...
Comment 10 Stefan Sauer (gstreamer, gtkdoc dev) 2007-08-02 19:21:48 UTC
2007-08-02  Stefan Kost  <ensonic@users.sf.net>

	patch by: David Nečas <yeti@physics.muni.cz>

	* Makefile.am:
	* configure.in:
	* gtkdoc-rebase.in:
	  Allow rebasing cross-references in generated docs. Fixes #434134.
Comment 11 Behdad Esfahbod 2007-08-02 19:25:59 UTC
So, how exactly does it work?  What should the user library do to get the fix?
Comment 12 Stefan Sauer (gstreamer, gtkdoc dev) 2007-08-02 19:46:02 UTC
I belive you dist the gtkdoc-rebase and then run this after installing
gtkdoc-rebase --html-dir=/usr/share/gtk-doc/html/pango --aggressive

Lets see what Yeti suggests.
Comment 13 Yeti 2007-08-02 19:52:59 UTC
1. To enable linking to their on-line references, libraries put something like

<releaseinfo>
  The latest version of this document can be found on-line at
  <ulink role="online-location"
         url="http://gwyddion.net/documentation/libgwyapp/index.php">http://gwyddion.net/documentation/libgwyapp/</ulink>.
</releaseinfo>

into the book (foo-docs.sgml).  The key part is the <ulink> with role "online-location" in <releaseinfo>.  This URL is the put into the installed index.sgml of the library as <ONLINE> tag.

The problem with this bit is that someone has to do it for each relevant library.


2a. When making dists, developers use --online option of fixxref to refer to on-line instead of local version of other documentation (if it comes with <ONLINE>).

2b. When making dists, developers use gtkdoc-rebase --online on the documentation copied to dist-directory.  Local file URIs are converted to on-line (again, requires <ONLINE> from the referred libraries).

The second is easier and can be relatively simply integrated to the `dist' target.  Neither 2a nor 2b is actually present in gtk-doc.make at this point.


3. Distro packagers that do not want to waste resources rebuilding the documentation but want local cross-references, use gtkdoc-rebase again (without --online) after `make install' to convert on-line paths to correct local paths for their system.  If they install into a staging area, they use --dest-dir to specify the to-be-ignored prefix.


4. Local packagers can also point <ONLINE> and/or "online-location" to other places when building packages (somewhere on LAN for instance).


=========================================================================
Please, please, give it some testing.

Also, I'm not sure if 2a is a viable option at all.  Maybe it would be better to leave the functionality in rebase and the revert fixxref on-line patch?
Comment 14 Behdad Esfahbod 2007-08-02 20:01:02 UTC
Well, I was mostly expecting an answer along the lines "nothing, it all Just Works automagically" :)
Comment 15 Yeti 2007-08-02 20:06:30 UTC
1 unfortunately does not happen automagically.

2. will happen automatically once we implement it -- if you use the supplied gtk-doc.make, people using customized makefiles have to update them to get this functionality.

You probably need not to care about 3. and 4.