2.0.0 beta 3 local html links in sketches not working

[bperrybap]

This was tested using Linux Mint 20.1 mate on Arduino 2.0.0 beta 3

In the 1.8.x ide you can have clickable links in a sketch.
While they are not directly clickable in 2.0.0 beta 3 (that is another issue) some can "work" by clicking on the new tooltip.
Ignoring the less usable way of bringing up links on 2.0.0 beta 3, there is an issue for links to local files.

html links to local files no longer work.
use of local files is very useful to provide local documentation that can be reached though clickable links in sketches.

Here is an example of what used to work on the pre 2.0 ide.

file://./docs/README.html

This would bring up a browser on the local file.

The root directory for local files was relative to the sketch location.
So if the sketch was shipped with the library, the location would be

{sketchbookdir}/libraries/{libraryname}/examples/{sketchname}/

In the specific case of my hd44780 library the location used by README.html file in the "Documentation" example sketch would be:

{sketchbookdir}/libraries/hd44780/examples/Documentation/docs/README.html

An easy way to test this is to install the hd44780 library, bring up the Documenation example sketch and try to click on the local readme link in the sketch.

--- bill

[bperrybap]

If I run an strace on the ide it reports:

root ERROR Fail to open 'file://./docs/README.html':

The file definitely exists.

Perhaps the 2.0.0 beta 3 IDE is not using the same base/root directory for local files?

If so, it should be fixed to work the same as the previous IDEs.

[pert]

Hi @bperrybap. Thanks for giving Arduino IDE 2.x a try!

My understanding is that relative paths in URI using the file scheme are not valid per the official specification. You might find that some tools support them, but you should not count on it:

File Uri Scheme and Relative Files

I see that valid absolute paths are supported, but that they open in the editor rather than in the browser. Of course, absolute paths are not useful for this use case.

Both these behaviors are the same in VS Code.

[bperrybap]

pert:
My understanding is that relative paths in URI using the file scheme are not valid per the official specification.

Relative links/paths are supported for "file" type URIs.
There is even text describing over the years in various updates to the RFCs desribing how they are handled in some specific cases like for DOS file paths that include driver letters.

Web Browsers have and still handle it correctly.

Over the years, I have seen lots of lazy programmers doing lots of hand waving and not properly support relative paths for local file references claiming it isn't something that is supported.
This includes the gnome developers who claim that file managers don't even have a current working directory location.
(ALL processes have a working directory, they are just not properly setting it up and using it correctly)
There are several path related issues in nautilus, nemo, caja, etc.... where they are not correctly handling paths which causes certain clickable executables to fail.
It all worked years ago, but over the years it broke, and the new, typically younger, authors don't want to address it to fix it, and even have some misconceptions about the working directory of a process.

You might find that some tools support them, but you should not count on it:
File Uri Scheme and Relative Files - Stack Overflow

Yes, I have seen that many s/w developers have started to punt on it and are not getting it correct.
relative paths should be supported. It is part of the RFC - in some cases by reference to another RFC.
When it isn't it supported correctly, it is a bug that should be resolved.

For the Arduino IDE, this worked correctly on the pre 2.0 IDE, so we should make sure it works the same way on the 2.0 IDE as well.
It is a very useful and powerful feature to be able to have a user bring up locally provided/included documentation using the IDE from links inside a sketch.
There is no other way to ship documentation with a library and have the user be able to easily access it directly from the IDE.

Without this capability users have to use a file manager and know the paths where everything is located and then navigate down to where the file is located to bring it up.
That is a bar that is too high for most Arduino users.
Even for those that wouldn't have a issue with it, it becomes how to you let them know it even exists and tell them where it can be found?

I'm sure this is trivial to fix. More than likely the process is not looking for the file in the correct location or is starting the browser in the wrong working directory location due to it not properly handling the relative location which should be relative to the sketch location.

Worst case the IDE could compute a full path and hand that off to whatever sub process brings up the browser to handle the links.

I guess I need to create a github issue for this and start lobbying to get this fixed.

--- bill

[bperrybap]

The github issue for this is here as issue #227

IDE does not bring up local file links in sketches when using relative URLs.

--- bill

[pert]

Thanks @bperrybap!

[bperrybap]

I added a zip file to the issue that can be used to demonstrate the issue and verify that the issue has been fixed.

Unfortunately, the issue has been changed / downgraded from my initial status of "bug" to "enhancement".

I think that is ok to ship with known issues and/or bugs. Just not critical or high priority ones.

While I would agree that this issue is not a critical capability that should stop the delivery of a release,
IMO, this issue is a low priority bug not a feature request as it is not requesting a new feature or capability, but rather reporting and asking for the restoration of a capability that worked in the pre 2.0 IDE that is no longer working.

There could even be high priority feature requests that rise above low level bugs like this and that is also ok.
But I don't agree that this issue is a feature request.

BTW, pert, it looks like they do have some priority tags but they don't seem to be used on all the issues. i.e. like some bugs or enhancements use it and some don't.
Is this just an oversight (lack of entering it) ? Seems like having a priority it is pretty important.

IMO, Issue tracking and priorities of issues, is an area where the old google code repository and other sites like bitbucket handle issues and their tracking/searching/sorting better than github.

--- bill

[pert]

I added a zip file to the issue that can be used to demonstrate the issue and verify that the issue has been fixed.

Thanks! I think it's very helpful to provide a demonstration of the issue to allow developers to get straight to the investigation and fix.

But I don't agree that this issue is a feature request.

For the last couple years of maintaining the previous Arduino IDE repository's issue tracker, my approach has been that if the reporting party considers it to be a defect, then I put the bug label on it, and if they consider it to be a request for an enhancement, then I put the enhancement label on it. That has worked really well for me. With GitHub's issue template system, we can even have these labels automatically added according to which template the user picks.

I have not been in a position to take as active a role in the issue tracker maintenance with the new repository. It's a bit crowded at the moment and as the saying goes "too many cooks...". I'm hoping that eventually I'll be able to step in with my same role and approach in the new repository (while carrying on in the old one of course).

it looks like they do have some priority tags but they don't seem to be used on all the issues. i.e. like some bugs or enhancements use it and some don't.
Is this just an oversight (lack of entering it) ? Seems like having a priority it is pretty important.

The priority labels are brand new. I proposed them because I have found them to be very useful for my own personal projects. It remains to be seen whether they will end up to be useful for Arduino's repositories repositories, where multiple people are collaborating all the time.

I don't think it's really feasible for the relatively unskilled maintainer (e.g., me) who does the initial triage to assign priorities, so I put this responsibility on some of the more higher level administrators and developers. So it's expected that the labels will only be added once they have had the opportunity to take a look at the issue.

In my own repositories, I decided there was no need for a "medium" priority label since that can be indicated by not adding a priority label. With the collaborative projects I decided that there should be high, medium, and low priority labels and the lack of a priority label will indicate that no priority has been assigned yet.

IMO, Issue tracking and priorities of issues, is an area where the old google code repository and other sites like bitbucket handle issues and their tracking/searching/sorting better than github.

I have not found anything to complain about with GitHub's issue tracker system. I spend a lot of time using Jira and I can definitively say that GitHub's system is far superior. I don't have experience with Google Code or BitBucket other than as someone browsing the issues and maybe submitting one or two over the years so I can't really compare.

[bperrybap]

I agree with you about the assigning of types and priorities.

If I understand you correctly, it seems sad that the main Arduino.cc developers didn't on their own see the need for having some sort of priority assignment for issues.

Observations like this further reinforces my concern that s/w development and project management practices are slowly falling down hill into lower and lower standards of methodologies and operation.
(Just look at what Google did yesterday with the WebView update it pushed out)

--- bill

---

About git repositories:

I really miss the google code repository back when it is was still active. It was really nice.
It had lots of issue tracking capabilities that don't exist on github that were very useful for project management.

When Google Code went down, I initially moved to bitbucket over github for my Arduino libraries due to some capabilities that are not available on github.

One the capabilities that does not exist on github is issue priorities.
Google code also had the ability to create custom fields with the ability to sort based on them.
It also would let you control who could set or even see certain fields.
github has tags but that is primitive in comparison and does not offer sorting capabilities.

For example, there is no way to do something simple like sort just your bugs based on a priority which is something you can do on bitbucket.

I will say that since atlassian took over bitbucket, there are some changes, that, IMO, make the bitbucket site a bit less "nice".

--- bill

[pert]

The only Arduino repository I'm aware of that had priority labels before I started my initiative over the last few weeks is the the Arduino Create Agent repository.

Most of the Arduino repositories just use the default set of labels GitHub provides.

I have added these priority labels to all the Arduino tooling repositories. That should serve as a fairly large scale experiment to determine whether they will be utilized and provide value.