File > Example menu should make sketchbook library overrides apparent

[PaulStoffregen]

Arduino provides a powerful feature for users to override any library, by simply placing a copy in their sketchbook libraries folder, which is typically Documents/Arduino/libraries.

Sometimes users do this to solve a problem, or by following steps on a website or tutorial, and then later (months, years...) forget they've got a copy installed there. Sometimes they're not even aware this will override any other library with the same name.

In Arduino 1.6.3, we added messages when compiling, to advise users of conflicts, with specific info about which copy of the library Arduino is using and which others it's ignoring. That mostly solved the worst troubles.

However, the File > Examples menu doesn't clearly show users they've overridden a built-in or custom library. This can be terribly confusing when a user doesn't realize they long-ago put a copy in that location. For example, here's a recent forum conversation which took several replies to resolve.

https://forum.pjrc.com/threads/33185-Audio-Library-examples-issue

I know the presentation in Arduino's GUI is a sensitive issue. I'm hoping we can consider adding info to the File > Examples menu to specifically show users when one of their sketchbook libraries is overriding any other library. I'm willing to work on a patch, and I'm looking for feedback regarding what sort of changes to the menu would be acceptable for Arduino?

[per1234]

Separate the File > Examples menu into 4 sections, based on location:

• Built-in Examples - {IDE installation folder}/examples
• Built-in Libraries - {IDE installation folder}/libraries
• Board Specific Libraries - hardware folder of the currently selected board
• Sketchbook Libraries - {sketchbook folder}/libraries

This means that Built-in libraries updated with Library Manager will move to the Sketchbook Libraries section but this could be fixed(and also fix #4064) by changing Library Manager to install updates of Built-in libraries to Arduino15/libraries and putting libraries from that location in the Built-in Libraries section.

As is already done, if there are multiple copies of a library then the examples shown follow the override precedence rules.

Document the folder(s) that Library Manager and Sketch > Include Library > Add .ZIP Library install to and explain the override system at https://www.arduino.cc/en/Reference/Libraries.

[PaulStoffregen]

Another usability problem I'm seeing repeatedly while helping people is they do not understand the File > Examples menu changes depending on which board they have selected. If they try to open an example from a tutorial, but that option doesn't appear in the menu, there's no visual que or hint to let them know they should make sure the correct board is selected.

[per1234]

That would be another benefit of my idea for having a Board Specific Libraries section of the File > Examples menu. That might not be the best wording to use for the section heading but something along those lines.

It might be more clear if the section heading used the boards package name as shown in Boards Manager. For example, when the "Arduino/Genuino Uno" board is selected, the boards specific File > Examples section heading would be Arduino AVR Boards Libraries. Of course this could lead to overly long section headings.

[per1234]

Actually better to use the name value from platform.txt or if that's missing then it could be generated by the vendor and architecture folder names of the package.