Re: Ok to redirect http://developer.gnome.org/doc/API/2.0/ to GNOME Library?

[Behdad Esfahbod <behdad behdad org>]

On Thu, 2007-08-16 at 11:27 +0200, Frederic Peters wrote:
> Behdad Esfahbod wrote:
> 
> >   - In http://library.gnome.org/developers/pango/ I see the following
> > available versions:
> > 
> >   * 1.10
> >       * 1.12
> >       * 1.14
> >       * 1.16
> >       * 1.17
> > 
> > It makes sense to clearly mark 1.17 as devel/unstable.
> 
> I'll do this.

Thanks.

> >   - Like others have said already, a
> > http://library.gnome.org/developers/pango/latest alias that links to the
> > latest stable release may make sense.
> 
> stable is link to latest stable release, and latest to latest
> (eventually development) release; isn't it ok that way ?

It probably is.   The only reason I prefer latest to point to latest
stable is that I guess people will start linking to latest, and I don't
want them to point users to unstable-will-changing API.

> >   - Why not list the minor version of each of those available versions?
> 
> It would multiply required disk space while not offering much
> advantages over current situation; me thinks.

I wasn't suggesting that you build docs for all micro versions.  Just to
write which micro version of pango 1.16 it is.  The URL should stay at
1.16 though.  Just pring 1.16.5 instead of 1.16.


> >   - The page http://library.gnome.org/developers/ links to a specific
> > version, not the listing.  How is one supposed to get to the listing?
> 
> Using the wonderful 'up' toolbar button of Epiphany :)  Seriously, I
> know there is currently no way to get to the version listing page; I
> have to list versions in the index.
> 
> >   - This one may need changes in gtk-doc, but would be very useful if we
> > could have something like
> > http://library.gnome.org/developers/pango/symbols/pango_layout_set_text
> > and have it work.  In fact, what would be more useful would be to make
> > http://library.gnome.org/pango_layout_set_text redirect to where it
> > should.  That's how php.net works and it has been extremely useful.  If
> > I want to read docs for the function phpinfo(), I go to
> > http://php.net/phpinfo
> 
> I believe this to be doable with RewriteMap; I just have to parse
> devhelp files and generate a big dbm file.  Added to TODO.

That would totally rock.  We need to do something like that in cairo
too, and then we can hack the wiki software to automatically link
cairo_*() symbols to their docs.  It doesn't need much parsing even,
this is how the .devhelp file looks like:

    <function name="pango_language_get_sample_string ()" link="pango-Miscellaneous-Utilities.html#pango-language-get-sample-string"/>
    <function name="pango_is_zero_width ()" link="pango-Miscellaneous-Utilities.html#pango-is-zero-width"/>
    <function name="pango_quantize_line_geometry ()" link="pango-Miscellaneous-Utilities.html#pango-quantize-line-geometry"/>
    <function name="PANGO_VERSION_ENCODE()" link="pango-Version-Checking.html#PANGO-VERSION-ENCODE:CAPS"/>


>         Frederic
-- 
behdad
http://behdad.org/

"Those who would give up Essential Liberty to purchase a little
 Temporary Safety, deserve neither Liberty nor Safety."
        -- Benjamin Franklin, 1759