Eli Zaretskii <eliz@gnu.org> writes:

>
> can you rephrase the last sentence not to use passive tense, please?
>
> But BASE-URI is not an &optional argument above.
>
> And also, this sentence is unnecessarily complex because you state the
> reason before the goal.  It is much better to do it the other way
> around, and while at that, make 2 simple sentences out of one complex
> one:
>
>   Optional argument @var{base-uri}, which should be a string,
>   specifies the location of the web resource.  It defaults to
>   @samp{about:blank}.
>
> (Of course, now this begs the question: what does it mean "web
> resource" for HTML text?  How about answering that in the text?)
>
> The second part is either unnecessary or too terse.  if it is
> important to explain that, please elaborate how temporary files are
> relevant here.
>
> The "plain text" part seems to contradict the text in the manual,
> which says it will be rendered as HTML markup?
>
> "will be" is confusing: why the future tense?
>
> Also, what kind of Lisp type is that?

It should be a string, thanks, I've resolved the concerns you listed
above.

> And I think explaining the importance of "fetching resources" would be
> beneficiary here.

I documented it in the manual the best I could.  I'm no web developer,
and the WebKitGTK documentation is vague on this subject, so I can't
think of anything better.

> And finally, "is treated as equivalent" is better reworded as "and
> defaults to ...", which is our style in these cases.

Thanks, done.

>> +  if (NILP (base_uri))
>> +    base_uri = build_string ("about:blank");
>> +  CHECK_STRING (base_uri);
>
> That last line should better be under 'else', right?

Done, thanks.

>> +  base_uri = ENCODE_UTF_8 (base_uri);

> Is it a good idea to produce non-ASCII URIs?

I personally think it's not, but the uuencoding of the URI is done by
WebKitGTK, which expects strings passed as the `uri' parameter to be
encoded as UTF-8 as opposed to uuencoded.

>> +  text = ENCODE_UTF_8 (text);
>> +  xw = XXWIDGET (xwidget);
>> +
>> +#ifdef USE_GTK
>> +  data = SSDATA (text);
>> +  uri = SSDATA (base_uri);
>> +  webview = WEBKIT_WEB_VIEW (xw->widget_osr);
>> +
>> +  block_input ();
>> +  webkit_web_view_load_html (webview, data, uri);
>> +  unblock_input ();
>> +#endif

> Hmm... if we only use TEXT and BASE-URI in the GTK build, why do we
> encode them in the other builds?  Isn't that a waste of cycles?  IOW,
> what does this function do if USE_GTK is not defined?

This feature isn't supported on macOS, but it's my hope that someone
will port it to macOS in short order.