Created attachment 220916 [details] [review]
Use GTKDOC_REBASE and GTK_DOC_USE_REBASE

For people (like me) who don't want to rebase their docs, the way to do so is to configure with GTKDOC_REBASE=`which echo` or something like that (note that it must be something that looks like a path, otherwise configure script won't accept it). I.e. override rebase binary with a dummy. GTK_DOC_USE_REBASE sounds promising, but it is simply set to True when gtkdoc-rebase is found or specified by the user, there's no switch to disable rebasing.

What is the problem with using rebase? That the build takes a few seconds longer?

I would prefer to see:

 - the gtk-doc requirement bumped to a more
   recent version which has -rebase

 - detect rebase path in configure and use it
   in the Makefile

 - no USE_REBASE conditional please, KISS

1) Bumping gtk-doc requirement is out of my hands. Ask ensonic.

2) Configure script DOES detect gtkdoc-rebase. HOWEVER, if user defined GTKDOC_REBASE at configure stage, and it looks like a path, configure script will use that instead of trying to find gtkdoc-rebase by itself. No matter how it finds gtkdoc-rebase, it will push it towards Makefile as GTKDOC_REBASE, and will define AM conditional GTK_DOC_USE_REBASE.

3) That conditional is defined in common/m4/gtk-doc.m4, see the bottom of the file:
  AM_CONDITIONAL([ENABLE_GTK_DOC], [test x$enable_gtk_doc = xyes])
  AM_CONDITIONAL([GTK_DOC_BUILD_HTML], [test x$enable_gtk_doc_html = xyes])
  AM_CONDITIONAL([GTK_DOC_BUILD_PDF], [test x$enable_gtk_doc_pdf = xyes])
  AM_CONDITIONAL([GTK_DOC_USE_LIBTOOL], [test -n "$LIBTOOL"])
  AM_CONDITIONAL([GTK_DOC_USE_REBASE], [test -n "$GTKDOC_REBASE"])
So it wasn't my idea. Ask ensonic to remove it. But then there will have to be a way to block $(GTKDOC_REBASE) from being run (since GTKDOC_REBASE would be defined to empty string). Maybe like this:
  if test -n $(GTKDOC_REBASE); then \
    $(GTKDOC_REBASE) ... \
  fi
Or maybe gtk-doc.m4 should be modified to define GTKDOC_REBASE to be a dummy if it fails to find real gtkdoc-rebase. In that case $(GTKDOC_REBASE) can be used unconditionally.

Oh, and the last bit i should have mentioned:

I don't like rebase, because it turns relative hrefs into _absolute_ hrefs. This is bad already, as it hardcodes absolute paths into docs, making them non-relocatable. And i see no profit in using absolute hrefs when every bit of gtk-doc is in the same share/gtk-doc subdirectory, and can easily cross-reference with relative hrefs just as well.

But it's worse than that. gtkdoc-rebase does not take into account that "c:/mingw32/share/gtk-doc" is NOT a valid URI (on *nix something like "/usr/share/gtk-doc" might be, i wouldn't know), and is not accepted by any W32 browser. It should be "file:///c:/mingw32/share/gtk-doc" instead. But gtk-doc is not smart enough to figure that out. As a result, all rebased docs have broken hrefs in them. Very annoying.

Now, this might be fixed by patching gtk-doc to be smarter, but since NOT rebasing the docs works just as well for me, i've taken the easier path - fixing GStreamer.

(In reply to comment #5)
> Oh, and the last bit i should have mentioned:
> 
> I don't like rebase, because it turns relative hrefs into _absolute_ hrefs.
> This is bad already, as it hardcodes absolute paths into docs, making them
> non-relocatable. And i see no profit in using absolute hrefs when every bit of
> gtk-doc is in the same share/gtk-doc subdirectory, and can easily
> cross-reference with relative hrefs just as well.

This is not the case. It is possible to have the docs in several places (e.g. when installing a devel version in home).

> 
> But it's worse than that. gtkdoc-rebase does not take into account that
> "c:/mingw32/share/gtk-doc" is NOT a valid URI (on *nix something like
> "/usr/share/gtk-doc" might be, i wouldn't know), and is not accepted by any W32
> browser. It should be "file:///c:/mingw32/share/gtk-doc" instead. But gtk-doc
> is not smart enough to figure that out. As a result, all rebased docs have
> broken hrefs in them. Very annoying.

File a bug against gtk-doc please.

> Now, this might be fixed by patching gtk-doc to be smarter, but since NOT
> rebasing the docs works just as well for me, i've taken the easier path -
> fixing GStreamer.

Cool if it works for you, but you are aware that gtkdoc-rebase was not added just for the fun of it.

(In reply to comment #6)
> (In reply to comment #5)
> > Oh, and the last bit i should have mentioned:
> > 
> > I don't like rebase, because it turns relative hrefs into _absolute_ hrefs.
> > This is bad already, as it hardcodes absolute paths into docs, making them
> > non-relocatable. And i see no profit in using absolute hrefs when every bit of
> > gtk-doc is in the same share/gtk-doc subdirectory, and can easily
> > cross-reference with relative hrefs just as well.
> 
> This is not the case. It is possible to have the docs in several places (e.g.
> when installing a devel version in home).
It is possible to have docs in several places. But that is not my case. I'm only concerned with my case.

> > But it's worse than that. gtkdoc-rebase does not take into account that
> > "c:/mingw32/share/gtk-doc" is NOT a valid URI (on *nix something like
> > "/usr/share/gtk-doc" might be, i wouldn't know), and is not accepted by any W32
> > browser. It should be "file:///c:/mingw32/share/gtk-doc" instead. But gtk-doc
> > is not smart enough to figure that out. As a result, all rebased docs have
> > broken hrefs in them. Very annoying.
> 
> File a bug against gtk-doc please.
See #681663

> > Now, this might be fixed by patching gtk-doc to be smarter, but since NOT
> > rebasing the docs works just as well for me, i've taken the easier path -
> > fixing GStreamer.
> 
> Cool if it works for you, but you are aware that gtkdoc-rebase was not added
> just for the fun of it.
I'm aware. And i want it to work for me first, and solve everyone else's problems second.

If gtkdoc-rebase is fixed, and you'd insist that what i'm doing (not rebasing the docs) should not be possible or supported in any way, then i'd have to implement a package manager for W32 (or try to use existing ones, which are often low-quality; or port a good one), package gst docs with it, and find a way to rebase docs every time they are installed (using some kind of post-install script). Which will require bundling MSys with the package manager, since gtkdoc is written in goddamn Perl, and (to me) doesn't look portable (my own solution in such cases is to rewrite the program in Python, with portability in mind (i suck at Perl), and that's even more work).

That would be the correct way of fixing this situation. And it would require lots of work in several areas, which is not something i am willing to undertake just now.

OR we could just agree to fix the way GStreamer invokes gtkdoc-rebase (which, objectively, requires fixing - it doesn't make use of gtk-doc.m4 to its full extent right now), which, as a useful (to me) side-effect, will allow me to not to rebase docs, which works for me just fine, and will likely keep working for me just fine until the issue can be fixed in a correct way.

P.S. Issue status is still "UNCONFIRMED", but the patch is "accepted-commit_now". What does that mean?

Created attachment 222129 [details] [review]
Use GTKDOC_REBASE instead of hard-coding

GTKDOC_REBASE will be set to /bin/true if gtkdoc-rebase is missing.
Remove unused GTK_DOC_USE_REBASE conditional.

Created attachment 222130 [details] [review]
Bump gtk-doc requirement to 1.12

I bumped the gtk-doc requiremnts in all modules in master. As we agreed on IRC, the other patch should just use GTKDOC_REBASE instead of making it conditional.