Reg. use of stock icons inline

[Sindhu S <sindhus live in>]

Hi all,

As a part of the OPW internship, I have taken up the task of updating
gedit help pages. I came across an instance of usage of stock icon
being used inline (that is, within paragraphs) along with help content
as part of the instructions to users.[1]

While it's very helpful to include screenshots of UI to help user
locate the right icon, particularly those that by default have no text
or a button that sets it's label from some user selectable value, this
practise breaks the line spacing in the paragraph and thus affects
readability. UI icon screenshots are not particularly user or
accessibility friendly and most importantly not theme agnostic. Hence
defeating one of the goals of GNOME Documentation team: GNOME help
must be written to be consistent across GNOME programs.

Solution 1: Mallard supports style tags for menu and menuitems which
can be used to mark up <gui> tags instead of the instructions to press
toolbar icons.

Solution 2: If however, the screenshot cannot be done without, we can use:

<figure>
  <title>Mallard Logo</title>
  <desc>a question-mark-shaped duck head in a circle.</desc>
  <media type="image" src="mallard-logo.png"/>
</figure>

This example uses the image as the focus and description tag could be
used to place help instructions associated with the image. Though,
this puts too much emphasis on the screenshot and thus requiring the
screenshot to be a full window for aesthetics sake than a little piece
of it. Could you suggest something more subtle and effective? :)

Thank you.

-Sindhu

[1] https://git.gnome.org/browse/gedit/tree/help/C/gedit-view-open-files-in-sidepane.page