Re: including system icons in help docs

[Shaun McCance <shaunm gnome org>]

On Thu, 2020-04-30 at 11:03 +1000, Michael Gratton wrote:
> Hi all,
>
> Is it possible to include system icons in Yelp docs without shipping
> a 
> copy of them?
>
> Per[0], Geary's help manual needs to refer to accessing a secondary 
> menu button, but that doesn't have a text label in the UI, just the 
> standard icon (i.e. currently `︙`). So it would be better to show
> the 
> icon in the docs instead/as well. I could just ship the Adwaita icon 
> SVG, but the icon actually used in the UI like will change depending
> on 
> the current configured desktop icon theme, so it would be better to
> use 
> the icon loaded from the system.
>
> I don't suppose there is a system-icon URI scheme that I could use
> for 
> the icon's source, is there? If so, would that also work if the docs 
> end up being published to the GNOME docs site?

Hi Mike,

This is something we've talked about, but never done. There are a lot
of advantages, such as smaller docs footprint, always up-to-date icons,
and potentially icon recoloring.

It would be possible to do it in Yelp, but then there's the question of
what happens when you publish the docs elsewhere. We could maybe make
the new Pintail-based docs site support it (preferably without making
build machines have themes and the rest of the stack installed). But if
you do a simple build with e.g. yelp-build, either you ship the icons
as a fallback, or you have broken docs. Perhaps some folks are ok with
their docs only being usable in Yelp and on help.gnome.org.

I think it's worth looking into more, but I don't see myself having
time to look into it myself any time soon.

--
Shaun