[Caml-list] LablGtk-documentation...

[Caml-list] LablGtk-documentation...

[Oliver Bandel]

Hello,

possibly some people who are responsible for the LablGtk-documentation  
are reading here on this list.

The ressources are spread over different documents, and these documents
contain a lot of broken links.

What seems to be the main page for LablGtk, IMO, is this one:

http://lablgtk.forge.ocamlcore.org/


There are links to API-descriptions as well as a README and tutorials.


  1
===
Let's look at the API-documentation:
   http://lablgtk.forge.ocamlcore.org/refdoc/index.html

Nice to have that document. But the links to GtK (C-API) are not available.

Example: http://lablgtk.forge.ocamlcore.org/refdoc/GEdit.html
If you look for "val entry_completion" there is a linkt to the  
documentation of
"GtkEntryCompletion".
But that link is the following:  
"file:///usr/share/gtk-doc/html/gtk/GtkEntryCompletion.html"
and thats, why the document is not avaialable.

I think, it would be much better to have detailed information inside the
API-description itself (instead of comparing LablGtk/OCaml and GtK/C  
documentation),
but as long as that is not the case, the link to GtK itself would be better
than not to have such a link.

So it would be nice, to make these links avaialable.

  2
===
Let's look at the "LablGtk2 Tutorial by SooHyoung Oh", which is very  
helpful, btw.
But it suffers from the same broken-link desease.

Example:  
http://plus.kaist.ac.kr/~shoh/ocaml/lablgtk2/lablgtk2-tutorial/x459.html
There is a link to "GPack.table"-documentation.
But following the link gives "Server not found".
So, izt seems the document has changed it's location a while ago,
and the links weren't updated in the document.


  3
===
Let's look at the "Treeview Tutorial by SooHyoung Oh", which I did not  
explored
in depth so far. But just testing for broken links, arbitrarily picking a page
immediately also brought a broken link.

Example:  
http://plus.kaist.ac.kr/~shoh/ocaml/lablgtk2/treeview-tutorial/ch03s05.html
The link to the "get" method gives "Server not found", and the link to  
"gtk_tree_model_get"
gives document not found.

(Looks like the Gnome-documents have changed location.)


These are just some examples.
I assume there will be more issues to find.

I would like to ask the people, who maintain these documents,
to fix these (and possibly other) issues, so that the quality of the
documentation could become better.

Also, if there are other docs abozt GtK/LablGtk, it would be nice if  
they could be added
to the above mentioned main page, so that these other docs are  
available easily.


Thanks In Advance,
     Oliver

Re: [Caml-list] LablGtk-documentation...

[Hendrik Boom]

On Thu, Sep 17, 2015 at 10:27:18AM +0200, Oliver Bandel wrote:
> Hello,
> 
> possibly some people who are responsible for the
> LablGtk-documentation are reading here on this list.
> 
> The ressources are spread over different documents, and these documents
> contain a lot of broken links.
> 
> What seems to be the main page for LablGtk, IMO, is this one:
> 
> http://lablgtk.forge.ocamlcore.org/
> 
> 
> There are links to API-descriptions as well as a README and tutorials.
> 
> 
>  1
> ===
> Let's look at the API-documentation:
>   http://lablgtk.forge.ocamlcore.org/refdoc/index.html
> 
> Nice to have that document. But the links to GtK (C-API) are not available.
> 
> Example: http://lablgtk.forge.ocamlcore.org/refdoc/GEdit.html

The links seem still to be broken.

But I found a GTK tutorial at 
http://ocaml.org/learn/tutorials/introduction_to_gtk.html

I have no idea whether this is the same one.  Anyone knot?

-- hendrik

Re: [Caml-list] LablGtk-documentation...

[Adrien Nader]

Hi,

For the C API, you should probably just load
https://developer.gnome.org/gtk2/stable/ and keep it around: the
documentation tends to not "regress" and it's often useful to have the
most recent one so that you can see that an API that you might need is
available in a newer version.

As you've probably seen, the C API links are file:/// URIs. This means
they're neither wrong nor right: it depends on the machine used to
display the documentation. I cannot tell what is the major on-disk path
for that documentation. For some people it would be solved by installing
the corresponding distribution package.

You can definitely argue that the links should point to gnome.org or
gtk.org but the issue remains: they point to an external resource which
is free to change. In any case, I agree that this should be fixed but I
don't have a definitive answer about how.

I'm partly to blame because I had started with lablgtk but subsequently
mostly gave up on GTK+ (not lablgtk) and therefore don't practice it.
Technically-speaking, I could fix it but I wouldn't be dog-feeding it,
making changes risky. Anyway, if you're interested in contributing, your
involvement will be welcome and I'll make my best to help you with that
(off-list preferably for simplicity matters).

-- 
Adrien Nader

Re: [Caml-list] LablGtk-documentation...

[Hendrik Boom]

On Thu, Dec 03, 2015 at 09:14:35PM +0100, Adrien Nader wrote:
> Hi,
> 
> For the C API, you should probably just load
> https://developer.gnome.org/gtk2/stable/ and keep it around: the
> documentation tends to not "regress" and it's often useful to have the
> most recent one so that you can see that an API that you might need is
> available in a newer version.
> 
> As you've probably seen, the C API links are file:/// URIs. This means
> they're neither wrong nor right: it depends on the machine used to
> display the documentation. I cannot tell what is the major on-disk path
> for that documentation. For some people it would be solved by installing
> the corresponding distribution package.
> 
> You can definitely argue that the links should point to gnome.org or
> gtk.org but the issue remains: they point to an external resource which
> is free to change. In any case, I agree that this should be fixed but I
> don't have a definitive answer about how.
> 
> I'm partly to blame because I had started with lablgtk but subsequently
> mostly gave up on GTK+ (not lablgtk) and therefore don't practice it.
> Technically-speaking, I could fix it but I wouldn't be dog-feeding it,
> making changes risky. Anyway, if you're interested in contributing, your
> involvement will be welcome and I'll make my best to help you with that
> (off-list preferably for simplicity matters).


It would seem that https://developer.gnome.org/gtk2/stable/ would be the 
definitive link to the C API, which together with the lablgtk source 
code would provide strong clues.

There shoud also be a tutorial by SooHyoung Oh somewhere.  Links on the 
web point to  
http://plus.kaist.ac.kr/~shoh/ocaml/lablgtk2/lablgtk2-tutorial/ and to 
http://plus.kaist.ac.kr/~shoh/ocaml/lablgtk2/treeview-tutorial/
neither of which seem to exist.

It would be useful to locate a copy.

-- hendrik
> 
> -- 
> Adrien Nader