[GNC-dev] Mouse usage in Gnucash

[Frank H. Ellenberger]

Hi all,

my main concern was against the use of '<emphasis role="bold">Fat
text</emphasis>', where more specific docbook elements exist. In
between I have no strong opinion about "Left click" vs. "click
Button1". It seems "Button n" makes the things gratuitous complex.
Perhaps we should include a short common snippet "Conventions in this
document" at the beginning of both docs, explaining we assume a
right-hand configured mouse.

Am So., 13. Okt. 2019 um 05:44 Uhr schrieb David Cousens
<davidcousens at bigpond.com>:
>
> Thanks Tommy,
>
> The gnome developers guide is a useful read in any case apart from the mouse
> specific issues. They seem to settle on the primary and secondary
> descriptions in one place and then use the left-click right-click etc,
> particularly in the glossary
> (https://developer.gnome.org/gdp-style-guide/2.32/gdp-style-guide.html#gnome-glossary-user-actions)
> description of user actions. It may be useful to link to this from the wiki
> on udpdating the documentation( see below). Perhaps a glossary may be a
> useful place to eventually include references/crossreferences  to alternate
> actions.
>
> The current docbook glossary

Which?

> is not terribly useful for html documents as it
> simply displays a popup with the glossary term in it rather than the
> definition part of the glossary entry which would be really useful. That
> behavior could be altered by using some custon xslt processing in the build
> but I don't have any expertise in that as yet.

1. For docbook/xml there is no build.
2. In theory it could be done in the xslt directory, which is mostly a
two decades old copy of yelps xslt with a few modifications or updates
- who knows. The versioned subdir is the official docbook xslt.

> At present the glossary
> exists only in the guide and not the help manual. There is a way of making a
> common glossary available in both but it will require some alteration of the
> build structure. I am avoiding that at the moment because I think it is more
> important to update the documentation in a few areas where there were new
> features in V3 and I don't have the expertise in the cmake and xslt
> processing to do it easily at the moment.

Right, that is a separate task.

> This section is a pretty good guide to usage in developments and the
> organization of GTK3
> https://developer.gnome.org/hig-book/unstable/input-mouse.html.en
> particularly the table of mouse and keyboard equivalents.

You saw also https://developer.gnome.org/hig-book/unstable/note-on-gnome3.html.en
? It is a GTK2 doc. They did until now not release a HIG3.

> The GDK reference manual refers to Button 1,2,3 with 1 Left 2 Middle and 3
> Right but that is more related to  usage in coding than in user
> documentation.
>
> There is no style guide in the Gnome documentation guide sense but there is
> the wiki on updating documentation
> (https://wiki.gnucash.org/wiki/Documentation_Update_Instructions) but it
> doesn't refer to mouse interaction descrptions.
>
> My inclination is to stay with left click, right click  descriptions as for
> a two button mouse for the moment. It is probably more important to be
> consistent rather than totally compliant with being as general as possible.
> I think some general  reference to the GTK3 input-mouse.html document would
> be useful as all the intefaces are based on it as well as
> https://developer.gnome.org/hig/stable/pointer-and-touch-input.html.en bu
> that is problematical as these are external references.

It is no problem to define
<!ENTITY url-gnm-dev "https://developer.gnome.org/"> <!-- Append the
desired topic -->
in gnc-docbookx.dtd. I am collecting others used in the texts: gnu
wikipedia as orgs, alphavantage, yahoo as coms...

> If it is desired to change this a global search and replace can always be
> used and much of the current documentation uses a left click, right click
> convention

yes

> David

Frank