Initial documentation for xwidgets

Initial documentation for xwidgets

[Eli Zaretskii]

I've pushed commit ef760b8, which is the initial attempt to document
the xwidget features.  The user manual mentions a single command and
the mode it enters.  The section in the ELisp manual mentions some of
the primitives I thought were important to document.  The particular
selection I decided to document, and the ones I decided to omit might
not make sense, which is OK -- the whole issue makes very little sense
to me for now, and the (abysmally inadequate, IMO) GTK documentation
of the APIs used by xwidget.c doesn't help at all.  The result cannot
be good enough by any measure.  Still, IMO it's better than no
documentation at all, and at least a seasonal WebKit programmer should
be able to figure the stuff out.

Please review and comment on functions/commands that should be added
to the documentation, and also on the correctness of the text.

Thanks.

Re: Initial documentation for xwidgets

[joakim]

Eli Zaretskii <eliz@gnu.org> writes:

> I've pushed commit ef760b8, which is the initial attempt to document
> the xwidget features.  The user manual mentions a single command and
> the mode it enters.  The section in the ELisp manual mentions some of
> the primitives I thought were important to document.  The particular
> selection I decided to document, and the ones I decided to omit might
> not make sense, which is OK -- the whole issue makes very little sense
> to me for now, and the (abysmally inadequate, IMO) GTK documentation
> of the APIs used by xwidget.c doesn't help at all.  The result cannot
> be good enough by any measure.  Still, IMO it's better than no
> documentation at all, and at least a seasonal WebKit programmer should
> be able to figure the stuff out.
>
> Please review and comment on functions/commands that should be added
> to the documentation, and also on the correctness of the text.
>
> Thanks.

I finally read the documentation you wrote for xwidgets, and it was really good thanks!

I have just two things.

- This fixme, I dont really have a good answer.
  @c FIXME: What else can a URI specify in this context?
The uri is just any ury webkit accepts, which isnt a very helpful
  explanation of course.

- When I read the documentation I noticed the term 'webkit-osr'. -osr
  stands for 'off screen rendering'.

There used to be different types of widgets, that weren't rendered
off-screen. I don't think I will re-introduce those widgets because they
were unreliable.

So, there will likely only ever be osr widgets, which makes the osr suffix
redundant.

I guess people might have started tinkering with xwidget-osr.

What do you think, should I change this, or does it not matter?


-- 
Joakim Verona

Re: Initial documentation for xwidgets

[Paul Eggert]

On 02/12/2016 01:08 PM, joakim@verona.se wrote:
> I guess people might have started tinkering with xwidget-osr.
>
> What do you think, should I change this, or does it not matter?

I'd change it. Anybody who's using this very-recently-introduced code 
can surely cope.

Re: Initial documentation for xwidgets

[Eli Zaretskii]

> From: joakim@verona.se
> Cc: emacs-devel@gnu.org
> Date: Fri, 12 Feb 2016 22:08:03 +0100
> 
> I finally read the documentation you wrote for xwidgets, and it was really good thanks!

Are you sure?  I cannot imagine I was that lucky.  There are some
functions I didn't document, some of them in xwidget.c, others in
xwidget.el -- did I decide correctly which ones should be documented
and which shouldn't?

> I have just two things.
> 
> - This fixme, I dont really have a good answer.
>   @c FIXME: What else can a URI specify in this context?
> The uri is just any ury webkit accepts, which isnt a very helpful
>   explanation of course.

Examples could help.  Can you provide examples of URIs that are
neither URLs nor file names?

> - When I read the documentation I noticed the term 'webkit-osr'. -osr
>   stands for 'off screen rendering'.
> 
> There used to be different types of widgets, that weren't rendered
> off-screen. I don't think I will re-introduce those widgets because they
> were unreliable.
> 
> So, there will likely only ever be osr widgets, which makes the osr suffix
> redundant.
> 
> I guess people might have started tinkering with xwidget-osr.
> 
> What do you think, should I change this, or does it not matter?

We can still change it, it's not too late.

Thanks.

Re: Initial documentation for xwidgets

[joakim]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: joakim@verona.se
>> Cc: emacs-devel@gnu.org
>> Date: Fri, 12 Feb 2016 22:08:03 +0100
>> 
>> I finally read the documentation you wrote for xwidgets, and it was really good thanks!
>
> Are you sure?  I cannot imagine I was that lucky.  There are some
> functions I didn't document, some of them in xwidget.c, others in
> xwidget.el -- did I decide correctly which ones should be documented
> and which shouldn't?

I think you did a better job than I would have done. But let me have an
extra look.

>
>> I have just two things.
>> 
>> - This fixme, I dont really have a good answer.
>>   @c FIXME: What else can a URI specify in this context?
>> The uri is just any ury webkit accepts, which isnt a very helpful
>>   explanation of course.
>
> Examples could help.  Can you provide examples of URIs that are
> neither URLs nor file names?
>
>> - When I read the documentation I noticed the term 'webkit-osr'. -osr
>>   stands for 'off screen rendering'.
>> 
>> There used to be different types of widgets, that weren't rendered
>> off-screen. I don't think I will re-introduce those widgets because they
>> were unreliable.
>> 
>> So, there will likely only ever be osr widgets, which makes the osr suffix
>> redundant.
>> 
>> I guess people might have started tinkering with xwidget-osr.
>> 
>> What do you think, should I change this, or does it not matter?
>
> We can still change it, it's not too late.

Ok, I will change it then.

BTW, when will it be too late to make these kind of changes? I think
this is the only api change, the other requested changes were more of
the bugfix kind. 

(let's assume I'm stuck in a time warp bubble where time moves quite
slowly as compared to the outside)

> Thanks.

-- 
Joakim Verona

Re: Initial documentation for xwidgets

[joakim]

joakim@verona.se writes:

> Eli Zaretskii <eliz@gnu.org> writes:
>
>>> From: joakim@verona.se
>>> Cc: emacs-devel@gnu.org
>>> Date: Fri, 12 Feb 2016 22:08:03 +0100
>>> 
>>> I finally read the documentation you wrote for xwidgets, and it was really good thanks!
>>
>> Are you sure?  I cannot imagine I was that lucky.  There are some
>> functions I didn't document, some of them in xwidget.c, others in
>> xwidget.el -- did I decide correctly which ones should be documented
>> and which shouldn't?
>
> I think you did a better job than I would have done. But let me have an
> extra look.
>
>>
>>> I have just two things.
>>> 
>>> - This fixme, I dont really have a good answer.
>>>   @c FIXME: What else can a URI specify in this context?
>>> The uri is just any ury webkit accepts, which isnt a very helpful
>>>   explanation of course.
>>
>> Examples could help.  Can you provide examples of URIs that are
>> neither URLs nor file names?
>>
>>> - When I read the documentation I noticed the term 'webkit-osr'. -osr
>>>   stands for 'off screen rendering'.
>>> 
>>> There used to be different types of widgets, that weren't rendered
>>> off-screen. I don't think I will re-introduce those widgets because they
>>> were unreliable.
>>> 
>>> So, there will likely only ever be osr widgets, which makes the osr suffix
>>> redundant.
>>> 
>>> I guess people might have started tinkering with xwidget-osr.
>>> 
>>> What do you think, should I change this, or does it not matter?
>>
>> We can still change it, it's not too late.
>
> Ok, I will change it then.
>
> BTW, when will it be too late to make these kind of changes? I think
> this is the only api change, the other requested changes were more of
> the bugfix kind. 

Sorry, there was the proposed change to remove unused arguments from
make-xwidget as well. So two api changes.

>
> (let's assume I'm stuck in a time warp bubble where time moves quite
> slowly as compared to the outside)
>
>> Thanks.

-- 
Joakim Verona

Re: Initial documentation for xwidgets

[Paul Eggert]

On 02/12/2016 01:40 PM, joakim@verona.se wrote:
> Sorry, there was the proposed change to remove unused arguments from
> make-xwidget as well. So two api changes.
I'd say go for it. This API is not part of any Emacs release yet.

Re: Initial documentation for xwidgets

[Eli Zaretskii]

> From: joakim@verona.se
> Cc: emacs-devel@gnu.org
> Date: Fri, 12 Feb 2016 22:35:19 +0100
> 
> > Are you sure?  I cannot imagine I was that lucky.  There are some
> > functions I didn't document, some of them in xwidget.c, others in
> > xwidget.el -- did I decide correctly which ones should be documented
> > and which shouldn't?
> 
> I think you did a better job than I would have done. But let me have an
> extra look.

Thanks.

> >> - This fixme, I dont really have a good answer.
> >>   @c FIXME: What else can a URI specify in this context?
> >> The uri is just any ury webkit accepts, which isnt a very helpful
> >>   explanation of course.
> >
> > Examples could help.  Can you provide examples of URIs that are
> > neither URLs nor file names?

Please also try to give a few examples, I have a bad feeling about
what I wrote in that part.

> >> I guess people might have started tinkering with xwidget-osr.
> >> 
> >> What do you think, should I change this, or does it not matter?
> >
> > We can still change it, it's not too late.
> 
> Ok, I will change it then.
> 
> BTW, when will it be too late to make these kind of changes?

I don't know, it depends on the changes.

Re: Initial documentation for xwidgets

[Eli Zaretskii]

> Cc: emacs-devel@gnu.org
> From: Paul Eggert <eggert@cs.ucla.edu>
> Date: Fri, 12 Feb 2016 13:55:34 -0800
> 
> On 02/12/2016 01:40 PM, joakim@verona.se wrote:
> > Sorry, there was the proposed change to remove unused arguments from
> > make-xwidget as well. So two api changes.
> I'd say go for it. This API is not part of any Emacs release yet.

Yes, I agree.

Thanks.