Calc's ENCODEURL, FILTERXML and WEBSERVICE functions

Hello All,

Please could somebody with technical knowledge of these three functions help me?

I have been upgrading their descriptions in the Calc Functions Wiki area (https://wiki.documentfoundation.org/Documentation/Calc_Functions/ENCODEURL, https://wiki.documentfoundation.org/Documentation/Calc_Functions/FILTERXML and https://wiki.documentfoundation.org/Documentation/Calc_Functions/WEBSERVICE).

I am not an expert on these functions but have extended the descriptions beyond the explanations given in the Help by a combination of code inspection and experimentation.

Would it be possible for somebody who has expertise in this area to review these three wiki pages from a technical perspective? Is what I have written technically correct? Have I missed anything that might be significant to a user who is looking for more background? (Please don't think I'm looking for somebody to find typos - there may be some, but we can resolve those without wasting any of a developer's valuable time!)

On a specific point, do we need to declare the versions of XML and XPath that are relevant for FILTERXML? If so, can somebody confirm what they are?

Thanks in advance.

Regards,

Steve Fanning (LibreOffice Documentation Team)

Greetings:
For the ENCOREURL function, the given URL returns an empty page as in

For the other two functions, I will also share my review comments.
Thank you-Dev

Hi Steve,

https://wiki.documentfoundation.org/Documentation/Calc_Functions/ENCODEURL

Just some remarks.

URL is not Universal Resource Locator but Uniform Resource Locator.
URI is Uniform Resource Identifier.
See also https://en.wikipedia.org/wiki/URL and
https://en.wikipedia.org/wiki/Uniform_Resource_Identifier

I find it a tad unfortunate that the first example of ENCODEURL() uses
a valid URI to encode it, i.e.
=ENCODEURL("https://www.libreoffice.org/")
that produces "https%3A%2F%2Fwww%2Elibreoffice%2Eorg%2F".
ENCODEURL() is more used on path components or query parameter arguments
that are appended to the path.

Also, using the libreoffice.org site should be avoided for examples as
when loaded
a) it generates quite some traffic
b) the result is overly complex

Rather use https://example.org/ instead that's made and reserved for,
well, examples, and delivers a short page if someone tries out.

Using actual queries for FILTERXML() is of course fine to demonstrate
functionality, with examples that keep the result not overly complex.

For ENCODEURL() "Additional details" "URL is constructed from a limited
set of characters" ... maybe also link to
https://datatracker.ietf.org/doc/html/rfc3986 the "Uniform Resource
Identifier (URI): Generic Syntax", and "A few special characters" should
be replaced by "A few reserved characters" linking to
https://datatracker.ietf.org/doc/html/rfc3986/#section-2.2 (Reserved
Characters)

https://wiki.documentfoundation.org/Documentation/Calc_Functions/FILTERXML
https://wiki.documentfoundation.org/Documentation/Calc_Functions/WEBSERVICE

The WEBSERVICE() example for "Accessing non-XML data" probably should
also be changed to https://example.org/ to not deliver the
"exceptionally long, multi-line string" ...

In "Accessing XML data" the example lacks the protocol scheme and //
before host component, i.e. https://

On a specific point, do we need to declare the versions of XML and XPath
that are relevant for FILTERXML? If so, can somebody confirm what they are?

I don't think the versions are somewhere nailed.

  Eike

Hi Steve,

I have just read the three wiki pages you mentioned and I could not find
any issues with them. IMO they're very thorough and well written.

In the WEBSERVICE page, section "Accessing non-XML data", I would add the
following:

Many thanks to Dev, Eike and Rafael for your helpful comments, they are much appreciated.

I have updated the ENCODEURL page and hopefully addressed all significant points (although I may have ignored the odd typographical change to retain consistency with the many other pages in this part of the wiki).

I decided that the tabular format for examples wasn't working on this page, some of the URLs were just too long. I've removed it but hopefully that won't detract from the usefulness of the page.

Please let me know if you are still unhappy with anything on the ENCODEURL page.

I will address the other two pages over the next couple of days.

Regards,

Steve

Hi Rafael,

With regards to differences between the Calc Functions Wiki and the corresponding Help pages...

You are correct that there is currently a significant difference in the content of the help pages and the wiki pages for SOME of Calc's functions. We need to work out how the users can be made aware of the extra content on the wiki but I don't think there is a great rush to solve this particular issue. We should give possible solutions some proper thought before making any changes to the help; meanwhile we will continue to improve the 500+ wiki pages.

Perhaps we could discuss at a future Documentation Team meeting? (After this week I expect to be able to attend our Thursday evening meetings a little more frequently).

Regards,

Steve

Hi Steve,

I agree with you. There's no rush to make a decision on this topic. It'll
be a great topic for discussion in the upcoming meeting.

However I haven't been able to attend our Thursdays meetings due to other
appointments I have at work. Hope I'll be able to attend the next one.

Cheers,
Rafael

Please do not make any massive help page changes after beta1 release of
7.2, because that makes it hard to be localized in time for a 7.2 release.

The 7.2 release in itself requires a big effort from the l10n community
with many new help strings and help updates.

Lp, m.

V V tor., 8. jun. 2021 ob 22:24 je oseba Rafael Lima <
rafael.palma.lima@gmail.com> napisala:

I have finished updating the FILTERXML and WEBSERVICE wiki pages.

I hope that I have implemented the suggested changes satisfactorily. I think that I have addressed the spirit of all comments, although I changed the proposed detail in some cases.

Thanks again for the helpful comments. Please let me know if you are still unhappy with anything on any of the three pages.

Regards,

Steve

Hi Steve,

I have finished updating the FILTERXML and WEBSERVICE wiki pages.

Yup, look better now, thanks.

  Eike