Re: Gtk patch version 3, part 1

[Richard Stallman]

    > It is not good to refer to a web site for documentation purposes.
    > Please refer to something that can be included in the user's machine.

    Do you mean "that the user can include into his machine" or "something
    that might be on the users machine already"?

I mean something that ought to be on the user's machine
(though any given user may or may not have installed it, of course).

    If the second, can I refer to /usr/share/gtk-doc, where the GTK
    documentation is usually installed?

Yes, but isn't there an Info file for GTK?

    >     +   Note that this is only for customizing specific GTK widget 
features.
    >     + To customize Emacs font, background, faces e.t.c., use the normal
    >     + X Resources, see @ref{Resources}.
    > 
    > To make this useful, it is important to be at least a little more
    > specific about which aspects to customize through GTK and which
    > through X resources.  If you can do this clearly with a description,
    > that is fine; otherwise you could use a list.

    It is given by the GTK documentation, is it OK to just refer to that?

A brief explicit concrete list would be much better than a
cross-reference.  When something is directly relevant for the user's
understanding, using a cross reference is considerably less convenient
for the user.

    > +   For dialogs a GtkDialog is used.
    > 
    > Please avoid the passive voice, here and everywhere, unless
    > it is absolutely necessary.

    How about

      Dialogs in Emacs are GtkDialog widgets.

Exactly!