all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* Gtk patch version 3, part 1
@ 2002-12-31  3:17 Jan D.
  2003-01-01 16:46 ` Richard Stallman
  2003-01-02  5:52 ` Eli Zaretskii
  0 siblings, 2 replies; 68+ messages in thread
From: Jan D. @ 2002-12-31  3:17 UTC (permalink / raw)


[-- Attachment #1: Type: text/plain, Size: 816 bytes --]

Hello.

Here is the third version of this patch.

I think I have fixed most things from the previous version.  Menus
should be faster, I notice a slight improvement, but it never was much
of a problem here.

The flicker in scrollbars should be gone.  Also, the bug for an empty
buffer is fixed.  Geometry problem and the undetachable popup menus
have been fixed.  Help for menus are in now.  A bunch of other bugs,
mostly related to menus, where fixed.

There is some documentation about widget names and how to customize fonts,
but there are some issues with GTK in this area.  Some things will not
be customizable (like the drop down menu in the file dialog), see
http://bugzilla.gnome.org/show_bug.cgi?id=101987.

Things on my todo list for the near future are ChangeLog and NEWS entry, and
GTK toolbar.

	Jan D.

[-- Attachment #2: emacs-diff-gtk.gz --]
[-- Type: application/gzip, Size: 71638 bytes --]

[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/emacs-devel

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
       [not found] <200212310414.gbv4et0u014643@stubby.bodenonline.com>
@ 2002-12-31  5:33 ` Phillip Garland
  2002-12-31 14:49   ` Jan D.
  2002-12-31 21:07 ` Phillip Garland
  1 sibling, 1 reply; 68+ messages in thread
From: Phillip Garland @ 2002-12-31  5:33 UTC (permalink / raw)
  Cc: emacs-devel

Hello,

I've compiled and ran version 3 of your GTK+ patch on a PPC GNU/Linux system with GTK+ 2.0.9.

There is one behavior that I find annoying and confusing. If I click on a menu, then move the mouse pointer to another menu, sometimes the menu name that I have moved to will become "highlighted", but the menu itself does not pop down. If I move the mouse again, hit a key, or click and hold a mouse button, the menu then does pop down. 

This behavior does not happen everytime I move between two menus with the mouse- sometimes when I move the mouse pointer to another menu, the menu seems to pop down immediately. As a user, I find this inconsistent and confusing because I feel unsure if popping the menu down requires 1 or 2 actions from me.

I tried a couple other GTK+ applications, but no others seemed to have this behavior.

~Phillip

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2002-12-31  5:33 ` Phillip Garland
@ 2002-12-31 14:49   ` Jan D.
  0 siblings, 0 replies; 68+ messages in thread
From: Jan D. @ 2002-12-31 14:49 UTC (permalink / raw)
  Cc: emacs-devel

[-- Attachment #1: Type: text/plain, Size: 1170 bytes --]

> Hello,
> 
> I've compiled and ran version 3 of your GTK+ patch on a PPC GNU/Linux system with GTK+ 2.0.9.
> 
> There is one behavior that I find annoying and confusing. If I click on a menu, then move the mouse pointer to another menu, sometimes the menu name that I have moved to will become "highlighted", but the menu itself does not pop down. If I move the mouse again, hit a key, or click and hold a mouse button, the menu then does pop down. 
> 

Funny I didn't see that, now that you mention it, it is obvious :-)
Anyway, this has to do with the fact that Emacs doesn't see GTK timers
so we have to make some special code to handle GTK timeouts, Xt have the
same problem.

As a comment to the signal handler discussion, these problems
would go away if Emacs could use a "normal" event loop (i.e. Xt/GTK/whatever)
instead of handling X events in a signal handler.  This is paritulary true
for GTK which delays some things untill it gets back to the event loop.
These never result in X events.  There is special handling for those cases
also in Emacs/GTK (gdk_window_process_all_updates for example).

Anyway, I've attached a fixed gtkutil.c.

Thanks,

	Jan D.



[-- Attachment #2: gtkutil.c --]
[-- Type: text/plain, Size: 71594 bytes --]

/* Functions for creating and updating GTK widgets.
   Copyright (C) 2002
   Free Software Foundation, Inc.

This file is part of GNU Emacs.

GNU Emacs is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.

GNU Emacs is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with GNU Emacs; see the file COPYING.  If not, write to
the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
Boston, MA 02111-1307, USA.  */

#include "config.h"

#ifdef USE_GTK
#include "lisp.h"
#include "xterm.h"
#include "blockinput.h"
#include "window.h"
#include "atimer.h"
#include "gtkutil.h"
#include <string.h>
#include <stdio.h>
#include <gdk/gdkkeysyms.h>

\f
/***********************************************************************
	   Menus and dialog functions.
 ***********************************************************************/

/* The name of menu items that can be used for citomization.  Since GTK
   RC files are very crude and primitive, we have to set this on all
   menu item names so a user can easily cutomize menu items.  */

#define MENU_ITEM_NAME "emacs-menuitem"


/* Linked list of all allocated struct xg_menu_cb_data.  Used for marking
   during GC.  The next member points to the items.  */
static xg_list_node xg_menu_cb_list;

/* Linked list of all allocated struct xg_menu_item_cb_data.  Used for marking
   during GC.  The next member points to the items.  */
static xg_list_node xg_menu_item_cb_list;

/* The timer for scroll bar repetition and menu bar timeouts.
   NULL if no timer is started.  */
static struct atimer *xg_timer;

/* The next two variables and functions are taken from lwlib.  */
static widget_value *widget_value_free_list;
static int malloc_cpt;

widget_value *
malloc_widget_value ()
{
  widget_value *wv;
  if (widget_value_free_list)
    {
      wv = widget_value_free_list;
      widget_value_free_list = wv->free_list;
      wv->free_list = 0;
    }
  else
    {
      wv = (widget_value *) malloc (sizeof (widget_value));
      malloc_cpt++;
    }
  memset (wv, 0, sizeof (widget_value));
  return wv;
}

/* this is analogous to free().  It frees only what was allocated
   by malloc_widget_value(), and no substructures.  */
void
free_widget_value (wv)
     widget_value *wv;
{
  if (wv->free_list)
    abort ();

  if (malloc_cpt > 25)
    {
      /* When the number of already allocated cells is too big,
	 We free it.  */
      free (wv);
      malloc_cpt--;
    }
  else
    {
      wv->free_list = widget_value_free_list;
      widget_value_free_list = wv;
    }
}

/*  Timer function called when a timeout occurs for xg_timer.
    This function processes all GTK events in a recursive event loop.
    This is done because GTK timer events are not seen by Emacs event
    detection, Emacs only looks for X events.  When a scroll bar has the
    pointer (detected by button press/release events below) an Emacs
    timer is started, and this function can then check if the GTK timer
    has expired by calling the GTK event loop.
    Also, when a menu is active, it has a small timeout before it
    pops down the sub menu under it.  */
static void
xg_process_timeouts (timer)
     struct atimer *timer;
{
  BLOCK_INPUT;
  /* Ideally we would like to just handle timer events, like the Xt version
     of this does in xterm.c, but there is no such feature in GTK.  */
  while (gtk_events_pending ())
    gtk_main_iteration ();
  UNBLOCK_INPUT;
}

/* Start the xg_timer with an interval of 0.1 seconds, if not already started.
   xg_process_timeouts is called when the timer expires.  The timer
   stared is continuous, i.e. runs until xg_stop_timer is called.  */
static void
xg_start_timer ()
{
  if (! xg_timer)
    {
      EMACS_TIME interval;
      EMACS_SET_SECS_USECS (interval, 0, 100000);
      xg_timer = start_atimer (ATIMER_CONTINUOUS,
                               interval,
                               xg_process_timeouts,
                               0);
    }
}

/* Stop the xg_timer if started.  */
static void
xg_stop_timer ()
{
  if (xg_timer)
    {
      cancel_atimer (xg_timer);
      xg_timer = 0;
    }
}

/* Insert NODE into linked LIST.  */
static void
xg_list_insert (xg_list_node *list, xg_list_node *node)
{
  xg_list_node *list_start = list->next;
  
  if (list_start) list_start->prev = node;
  node->next = list_start;
  node->prev = 0;
  list->next = node;
}

/* Remove NODE from linked LIST.  */
static void
xg_list_remove (xg_list_node *list, xg_list_node *node)
{
  xg_list_node *list_start = list->next;
  if (node == list_start)
    {
      list->next = node->next;
      if (list->next) list->next->prev = 0;
    }
  else
    {
      node->prev->next = node->next;
      if (node->next) node->next->prev = node->prev;
    }
}

/* Allocate and return a utf8 version of STR.  If STR is already
   utf8 or NULL, just return STR.
   If not, a new string is allocated and the caller must free the result
   with g_free().  */
static char*
get_utf8_string (str)
     char *str;
{
  char *utf8_str = str;
  
  /* If not UTF-8, try current locale.  */
  if (str && !g_utf8_validate (str, -1, NULL))
    utf8_str = g_locale_to_utf8 (str, -1, 0, 0, 0);

  return utf8_str;
}

/* Allocate and initialize CL_DATA if NULL, otherwise increase ref_count.
   F is the frame CL_DATA will be initialized for.

   Returns CL_DATA if CL_DATA is not NULL,  or a pointer to a newly
   allocated xg_menu_cb_data if CL_DATA is NULL.
   HIGHLIGHT_CB is the callback to call when entering/leaving menu items.  */
xg_menu_cb_data*
make_cl_data (cl_data, f, highlight_cb)
     xg_menu_cb_data *cl_data;
     FRAME_PTR f;
     GCallback highlight_cb;
{
  if (! cl_data)
    {
      cl_data = (xg_menu_cb_data*) xmalloc (sizeof (*cl_data));
      cl_data->f = f;
      cl_data->menu_bar_vector = f->menu_bar_vector;
      cl_data->menu_bar_items_used = f->menu_bar_items_used;
      cl_data->highlight_cb = highlight_cb;
      cl_data->ref_count = 0;

      xg_list_insert (&xg_menu_cb_list, &cl_data->ptrs);
    }

  cl_data->ref_count++;

  return cl_data;
}

/* Update CL_DATA with values from frame F and with HIGHLIGHT_CB.  */
static void
update_cl_data (cl_data, f, highlight_cb)
     xg_menu_cb_data *cl_data;
     FRAME_PTR f;
     GCallback highlight_cb;
{
  if (cl_data)
    {
      cl_data->f = f;
      cl_data->menu_bar_vector = f->menu_bar_vector;
      cl_data->menu_bar_items_used = f->menu_bar_items_used;
      cl_data->highlight_cb = highlight_cb;
    }
}

/* Decrease reference count for CL_DATA.
   If reference count is zero, free CL_DATA.  */
static void
unref_cl_data (cl_data)
     xg_menu_cb_data *cl_data;
{
  if (cl_data && cl_data->ref_count > 0)
    {
      cl_data->ref_count--;
      if (cl_data->ref_count == 0)
        {
          xg_list_remove (&xg_menu_cb_list, &cl_data->ptrs);
          xfree (cl_data);
        }
    }
}

/* Function that marks all lisp data during GC.  */
void
xg_mark_data ()
{
  xg_list_node *iter;

  for (iter = xg_menu_cb_list.next; iter; iter = iter->next)
    mark_object (&((xg_menu_cb_data *) iter)->menu_bar_vector);

  for (iter = xg_menu_item_cb_list.next; iter; iter = iter->next)
    {
      xg_menu_item_cb_data *cb_data = (xg_menu_item_cb_data *) iter;

      if (! NILP (cb_data->help))
        mark_object (&cb_data->help);
    }
}


/* Callback called when a menu item is destroyed.  Used to free data.
   W is the widget that is being destroyed (not used).
   CLIENT_DATA points to the xg_menu_item_cb_data associated with the W.  */
static void
menuitem_destroy_callback (w, client_data)
     GtkWidget *w;
     gpointer client_data;
{
  if (client_data)
    {
      xg_menu_item_cb_data *data = (xg_menu_item_cb_data*) client_data;
      xg_list_remove (&xg_menu_item_cb_list, &data->ptrs);
      xfree (data);
    }
}

/* Callback called when the pointer enters/leaves a menu item.
   W is the menu item.
   EVENT is either an enter event or leave event.
   CLIENT_DATA points to the xg_menu_item_cb_data associated with the W.

   Returns FALSE to tell GTK to keep processing this event.  */
static gboolean
menuitem_highlight_callback (w, event, client_data)
     GtkWidget *w;
     GdkEventCrossing *event;
     gpointer client_data;
{
  if (client_data)
    {
      xg_menu_item_cb_data *data = (xg_menu_item_cb_data*) client_data;
      gpointer call_data = event->type == GDK_LEAVE_NOTIFY ? 0 : client_data;
      
      if (! NILP (data->help) && data->cl_data->highlight_cb)
        {
          GtkCallback func = (GtkCallback) data->cl_data->highlight_cb;
          (*func) (w, call_data);
        }
    }

  return FALSE;
}

/* Callback called when a menu is destroyed.  Used to free data.
   W is the widget that is being destroyed (not used).
   CLIENT_DATA points to the xg_menu_cb_data associated with W.  */
static void
menu_destroy_callback (w, client_data)
     GtkWidget *w;
     gpointer client_data;
{
  unref_cl_data ((xg_menu_cb_data*) client_data);
}

/* Callback called when a menu does a grab or ungrab.  That means the
   menu has been activated or deactivated.
   Used to start a timer so the small timeout the menus in GTK uses before
   popping down a menu is seen by Emacs (see xg_process_timeouts above).
   W is the widget that does the grab (not used).
   UNGRAB_P is TRUE if this is an ungrab, FALSE if it is a grab.
   CLIENT_DATA is NULL (not used).  */
static void
menu_grab_cb (GtkWidget *widget,
              gboolean ungrab_p,
              gpointer client_data)
{
  /* Keep track of total number of grabs.  */
  static int cnt;

  if (ungrab_p) cnt--;
  else cnt++;

  if (cnt > 0 && ! xg_timer) xg_start_timer ();
  else if (cnt == 0 && xg_timer) xg_stop_timer ();
}


/* Make a GTK widget that contains both UTF8_LABEL and UTF8_KEY (both
   must be non-NULL) and can be inserted into a menu item.

   Returns the GtkHBox.  */
static GtkWidget*
make_widget_for_menu_item (utf8_label, utf8_key)
     char *utf8_label;
     char *utf8_key;
{
  GtkWidget *wlbl;
  GtkWidget *wkey;
  GtkWidget *wbox;
  
  wbox = gtk_hbox_new (FALSE, 0);
  wlbl = gtk_label_new_with_mnemonic (utf8_label);
  wkey = gtk_label_new (utf8_key);

  gtk_misc_set_alignment (GTK_MISC (wlbl), 0.0, 0.5);
  gtk_misc_set_alignment (GTK_MISC (wkey), 0.0, 0.5);
              
  gtk_box_pack_start (GTK_BOX (wbox), wlbl, TRUE, TRUE, 0);
  gtk_box_pack_start (GTK_BOX (wbox), wkey, FALSE, FALSE, 0);

  gtk_widget_set_name (wlbl, MENU_ITEM_NAME);
  gtk_widget_set_name (wkey, MENU_ITEM_NAME);

  return wbox;
}

/* Make and return a menu item widget with the key to the right.
   UTF8_LABEL is the text for the menu item (GTK uses UTF8 internally).
   UTF8_KEY is the text representing the key binding.
   ITEM is the widget_value describing the menu item.
   
   GROUP is an in/out parameter.  If the menu item to be created is not
   part of any radio menu group, *GROUP contains NULL on entry and exit.
   If the menu item to be created is part of a radio menu group, on entry
   *GROUP contains the group to use, or NULL if this is the first item
   in the group.  On exit, *GROUP contains the radio item group.

   Unfortunately, keys don't line up as nicely as in Motif,
   but the MacOS X version doesn't either, so I guess that is OK.  */
static GtkWidget*
make_menu_item (utf8_label, utf8_key, item, group)
     char *utf8_label;
     char *utf8_key;
     widget_value* item;
     GSList **group;
{
  GtkWidget *w;
  GtkWidget *wtoadd = 0;
  
  if (utf8_key)
    wtoadd = make_widget_for_menu_item (utf8_label, utf8_key);
  
  if (item->button_type == BUTTON_TYPE_TOGGLE)
    {
      *group = NULL;
      if (utf8_key) w = gtk_check_menu_item_new ();
      else w = gtk_check_menu_item_new_with_mnemonic (utf8_label);
      gtk_check_menu_item_set_active (GTK_CHECK_MENU_ITEM (w), item->selected);
    }
  else if (item->button_type == BUTTON_TYPE_RADIO)
    {
      if (utf8_key) w = gtk_radio_menu_item_new (*group);
      else w = gtk_radio_menu_item_new_with_mnemonic (*group, utf8_label);
      *group = gtk_radio_menu_item_get_group (GTK_RADIO_MENU_ITEM (w));
      if (item->selected)
        gtk_check_menu_item_set_active (GTK_CHECK_MENU_ITEM (w), TRUE);
    }
  else
    {
      *group = NULL;
      if (utf8_key) w = gtk_menu_item_new ();
      else w = gtk_menu_item_new_with_mnemonic (utf8_label);
    }
  
  if (wtoadd) gtk_container_add (GTK_CONTAINER (w), wtoadd);
  if (! item->enabled) gtk_widget_set_sensitive (w, FALSE);

  return w;
}

/* Return non-zero if NAME specifies a separator (GTK only has one
   separator type)  */
static int
xg_separator_p (char *name)
{
  return strcmp (name, "--") == 0
    || strcmp (name, "--:") == 0
    || strcmp (name, "---") == 0;
}

GtkWidget *xg_did_tearoff;

/* Callback invoked when a detached menu window is removed.  Here we
   delete the popup menu.
   WIDGET is the top level window that is removed (the parent of the menu).
   EVENT is the event that triggers the window removal.
   CLIENT_DATA points to the menu that is detached.

   Returns TRUE to tell GTK to stop processing this event.  */
static gboolean
tearoff_remove (widget, event, client_data)
     GtkWidget *widget;
     GdkEvent *event;
     gpointer client_data;
{
  gtk_widget_destroy (GTK_WIDGET (client_data));
  return TRUE;
}

/* Callback invoked when a menu is detached.  It sets the xg_did_tearoff
   variable.
   WIDGET is the GtkTearoffMenuItem.
   CLIENT_DATA is not used.  */ 
static void
tearoff_activate (widget, client_data)
     GtkWidget *widget;
     gpointer client_data;
{
  GtkWidget *menu = gtk_widget_get_parent (widget);
  if (! gtk_menu_get_tearoff_state (GTK_MENU (menu)))
    return;

  xg_did_tearoff = menu;
}

/* If a detach of a popup menu is done, this function should be called
   to keep the menu around until the detached window is removed.
   MENU is the top level menu for the popup,
   SUBMENU is the menu that got detached (that is MENU or a
   submenu of MENU), see the xg_did_tearoff variable.  */
void
xg_keep_popup (menu, submenu)
     GtkWidget *menu;
     GtkWidget *submenu;
{
  GtkWidget *p;

  /* Find the top widget for the detached menu.  */
  p = gtk_widget_get_toplevel (submenu);
    
  /* Delay destroying the menu until the detached menu is removed.  */
  g_signal_connect (p, "unmap_event", G_CALLBACK (tearoff_remove), menu);
}

int xg_debug = 0;

/* Create a menu item widget, and connect the callbacks.
   ITEM decribes the menu item.
   F is the frame the created menu belongs to.
   SELECT_CB is the callback to use when a menu item is selected.
   HIGHLIGHT_CB is the callback to call when entering/leaving menu items.
   CL_DATA points to the callback data to be used for this menu.
   GROUP is an in/out parameter.  If the menu item to be created is not
   part of any radio menu group, *GROUP contains NULL on entry and exit.
   If the menu item to be created is part of a radio menu group, on entry
   *GROUP contains the group to use, or NULL if this is the first item
   in the group.  On exit, *GROUP contains the radio item group.

   Returns the created GtkWidget.  */
static GtkWidget*
xg_create_one_menuitem (item, f, select_cb, highlight_cb, cl_data, group)
     widget_value* item;
     FRAME_PTR f;
     GCallback select_cb;
     GCallback highlight_cb;
     xg_menu_cb_data *cl_data;
     GSList **group;
{
  char *utf8_label;
  char *utf8_key;
  GtkWidget *w;
  xg_menu_item_cb_data *cb_data;

  utf8_label = get_utf8_string (item->name);
  utf8_key = get_utf8_string (item->key);

  w = make_menu_item (utf8_label, utf8_key, item, group);

  if (utf8_label && utf8_label != item->name) g_free (utf8_label);
  if (utf8_key && utf8_key != item->key) g_free (utf8_key);

  cb_data = xmalloc (sizeof (xg_menu_item_cb_data));

  xg_list_insert (&xg_menu_item_cb_list, &cb_data->ptrs);

  cb_data->unhighlight_id = cb_data->highlight_id = cb_data->select_id = 0;
  cb_data->help = item->help;
  cb_data->cl_data = cl_data;
  cb_data->call_data = item->call_data;
      
  g_signal_connect (w,
                    "destroy",
                    G_CALLBACK (menuitem_destroy_callback),
                    cb_data);

  /* Put cb_data in widget, so we can get at it when modifying menubar  */
  g_object_set_data (G_OBJECT (w), XG_ITEM_DATA, cb_data);

  /* final item, not a submenu  */
  if (item->call_data && ! item->contents)
    {
      if (select_cb)
        cb_data->select_id
          = g_signal_connect (w, "activate", select_cb, cb_data);
    }

  if (! NILP (item->help) && highlight_cb)
    {
      /* We use enter/leave notify instead of select/deselect because
         select/deselect doesn't go well with detached menus.  */
      cb_data->highlight_id
        = g_signal_connect (w,
                            "enter-notify-event",
                            G_CALLBACK (menuitem_highlight_callback),
                            cb_data);
      cb_data->unhighlight_id
        = g_signal_connect (w,
                            "leave-notify-event",
                            G_CALLBACK (menuitem_highlight_callback),
                            cb_data);
    }

  return w;
}

/* Create a full menu tree specified by DATA.
   F is the frame the created menu belongs to.
   SELECT_CB is the callback to use when a menu item is selected.
   DEACTIVATE_CB is the callback to use when a sub menu is not shown anymore.
   HIGHLIGHT_CB is the callback to call when entering/leaving menu items.
   POP_UP_P is non-zero if we shall create a popup menu.
   MENU_BAR_P is non-zero if we shall create a menu bar.
   ADD_TEAROFF_P is non-zero if we shall add a teroff menu item.  Ignored
   if MENU_BAR_P is non-zero.
   TOPMENU is the topmost GtkWidget that others shall be placed under.
   It may be NULL, in that case we create the appropriate widget
   (menu bar or menu item depending on POP_UP_P and MENU_BAR_P)
   CL_DATA is the callback data we shall use for this menu, or NULL
   if we haven't set the first callback yet.
   NAME is the name to give to the top level menu if this function
   creates it.  May be NULL to not set any name.

   Returns the top level GtkWidget.  This is TOPLEVEL if TOPLEVEL is
   not NULL.

   This function calls itself to create submenus.  */

static GtkWidget*
create_menus (data, f, select_cb, deactivate_cb, highlight_cb,
              pop_up_p, menu_bar_p, add_tearoff_p, topmenu, cl_data, name)
     widget_value* data;
     FRAME_PTR f;
     GCallback select_cb;
     GCallback deactivate_cb;
     GCallback highlight_cb;
     int pop_up_p;
     int menu_bar_p;
     int add_tearoff_p;
     GtkWidget *topmenu;
     xg_menu_cb_data *cl_data;
     char *name;
{
  widget_value* item;
  GtkWidget* wmenu = topmenu;
  GSList* group = NULL;

  if (! topmenu)
    {
      if (! menu_bar_p) wmenu = gtk_menu_new ();
      else wmenu = gtk_menu_bar_new ();

      /* Put cl_data on the top menu for easier access.  */
      cl_data = make_cl_data (cl_data, f, highlight_cb);
      g_object_set_data (G_OBJECT (wmenu), XG_FRAME_DATA, (gpointer)cl_data);
      g_signal_connect (wmenu, "destroy", menu_destroy_callback, cl_data);
      
      if (name)
        gtk_widget_set_name (wmenu, name);

      if (deactivate_cb)
        g_signal_connect (wmenu, "deactivate", deactivate_cb, 0);

      g_signal_connect (wmenu, "grab-notify", G_CALLBACK (menu_grab_cb), 0);
    }
  
  if (! menu_bar_p && add_tearoff_p)
    {
      GtkWidget *tearoff = gtk_tearoff_menu_item_new ();
      gtk_menu_shell_append (GTK_MENU_SHELL (wmenu), tearoff);

      g_signal_connect (tearoff, "activate",
                        G_CALLBACK (tearoff_activate), 0);
    }

  for (item = data; item; item = item->next)
    {
      GtkWidget *w;
      
      if (pop_up_p && !item->contents && !item->call_data
          && !xg_separator_p (item->name))
        {
          char *utf8_label;
          /* A title for a popup.  We do the same as GTK does when
             creating titles, but it does not look good.  */
          group = NULL;
          utf8_label = get_utf8_string (item->name);

          gtk_menu_set_title (GTK_MENU (wmenu), utf8_label);
          w = gtk_menu_item_new_with_mnemonic (utf8_label);
          gtk_widget_set_sensitive (w, FALSE);
          if (utf8_label && utf8_label != item->name) g_free (utf8_label);
        }
      else if (xg_separator_p (item->name))
        {
          group = NULL;
          /* GTK only have one separator type.  */
          w = gtk_separator_menu_item_new ();
        }
      else
        {
          w = xg_create_one_menuitem (item,
                                      f,
                                      item->contents ? 0 : select_cb,
                                      highlight_cb,
                                      cl_data,
                                      &group);

          if (item->contents)
            {
              GtkWidget *submenu = create_menus (item->contents,
                                                 f,
                                                 select_cb,
                                                 deactivate_cb,
                                                 highlight_cb,
                                                 0,
                                                 0,
                                                 1,
                                                 0,
                                                 cl_data,
                                                 0);
              gtk_menu_item_set_submenu (GTK_MENU_ITEM (w), submenu);
            }

          /* Assume "Help" is the last menu in the menubar.  */
          if (menu_bar_p && ! item->next)
            gtk_menu_item_set_right_justified (GTK_MENU_ITEM (w), TRUE);
        }

      gtk_menu_shell_append (GTK_MENU_SHELL (wmenu), w);
      gtk_widget_set_name (w, MENU_ITEM_NAME);
    }

  return wmenu;
}

/* Return the dialog title to use for a dialog of type KEY.
   This is the encoding used by lwlib.  We use the same for GTK.  */
static char*
get_dialog_title (char key)
{
  char *title = "";
  
  switch (key) {
  case 'E': case 'e':
    title = "Error";
    break;

  case 'I': case 'i':
    title = "Information";
    break;

  case 'L': case 'l':
    title = "Prompt";
    break;

  case 'P': case 'p':
    title = "Prompt";
    break;

  case 'Q': case 'q':
    title = "Question";
    break;
  }

  return title;
}

/* Create a popup dialog window.
   WV is a widget_value describing the dialog.
   SELECT_CB is the callback to use when a button has been pressed.
   DEACTIVATE_CB is the callback to use when the dialog pops down.

   Returns the GTK dialog widget.  */
static GtkWidget*
create_dialog (wv, select_cb, deactivate_cb)
     widget_value* wv;
     GCallback select_cb;
     GCallback deactivate_cb;
{
  char *title = get_dialog_title (wv->name[0]);
  int total_buttons = wv->name[1] - '0';
  int right_buttons = wv->name[4] - '0';
  int left_buttons;
  int button_nr = 0;
  int button_spacing = 10;
  GtkWidget *wdialog = gtk_dialog_new ();
  widget_value* item;
  GtkBox *cur_box;
  GtkWidget *wvbox;
  GtkWidget *whbox_up;
  GtkWidget *whbox_down;

  /* If the number of buttons is greater than 4, make two rows of buttons
     instead.  This looks better.  */
  int make_two_rows = total_buttons > 4;

  if (right_buttons == 0) right_buttons = total_buttons/2;
  left_buttons = total_buttons - right_buttons;

  gtk_window_set_title (GTK_WINDOW (wdialog), title);
  gtk_widget_set_name (wdialog, "emacs-dialog");

  cur_box = GTK_BOX (GTK_DIALOG (wdialog)->action_area);

  if (make_two_rows)
    {
      wvbox = gtk_vbox_new (TRUE, button_spacing);
      whbox_up = gtk_hbox_new (FALSE, 0);
      whbox_down = gtk_hbox_new (FALSE, 0);

      gtk_box_pack_start (cur_box, wvbox, FALSE, FALSE, 0);
      gtk_box_pack_start (GTK_BOX (wvbox), whbox_up, FALSE, FALSE, 0);
      gtk_box_pack_start (GTK_BOX (wvbox), whbox_down, FALSE, FALSE, 0);

      cur_box = GTK_BOX (whbox_up);
    }

  if (deactivate_cb)
    {
      g_signal_connect (wdialog, "close", deactivate_cb, 0);
      g_signal_connect (wdialog, "response", deactivate_cb, 0);
    }

  for (item = wv->contents; item; item = item->next)
    {
      char *utf8_label = get_utf8_string (item->value);
      GtkWidget *w;
      GtkRequisition req;

      if (strcmp (item->name, "message") == 0)
        {
          /* This is the text part of the dialog.  */
          w = gtk_label_new (utf8_label);
          gtk_box_pack_start (GTK_BOX (GTK_DIALOG (wdialog)->vbox),
                              gtk_label_new (""),
                              FALSE, FALSE, 0);
          gtk_box_pack_start (GTK_BOX (GTK_DIALOG (wdialog)->vbox), w,
                              TRUE, TRUE, 0);
          gtk_misc_set_alignment (GTK_MISC (w), 0.1, 0.5);

          /* Try to make dialog look better.  Must realize first so
             the widget can calculate the size it needs.  */
          gtk_widget_realize (w);
          gtk_widget_size_request (w, &req);
          gtk_box_set_spacing (GTK_BOX (GTK_DIALOG (wdialog)->vbox),
                               req.height);
	  if (strlen (item->value) > 0)
            button_spacing = 2*req.width/strlen (item->value);
        }
      else
        {
          /* This is one button to add to the dialog.  */
          w = gtk_button_new_with_mnemonic (utf8_label);
          if (! item->enabled)
            gtk_widget_set_sensitive (w, FALSE);
          if (select_cb)
            g_signal_connect (w, "clicked", select_cb, item->call_data);

          gtk_box_pack_start (cur_box, w, TRUE, TRUE, button_spacing);
          if (++button_nr == left_buttons)
            {
              if (make_two_rows)
                cur_box = GTK_BOX (whbox_down);
              else
                gtk_box_pack_start (cur_box,
                                    gtk_label_new (""),
                                    TRUE, TRUE,
                                    button_spacing);
            }
        }

     if (utf8_label && utf8_label != item->value)
       g_free (utf8_label);
    }

  return wdialog;
}

/* Create a menubar, popup menu or dialog, depending on the TYPE argument.
   TYPE can be "menubar", "popup" for popup menu, or "dialog" for a dialog
   with some text and buttons.
   F is the frame the created item belongs to.
   NAME is the name to use for the top widget.
   VAL is a widget_value structure describing items to be created.
   SELECT_CB is the callback to use when a menu item is selected or
   a dialog button is pressed.
   DEACTIVATE_CB is the callback to use when an item is deactivated.
   For a menu, when a sub menu is not shown anymore, for a dialog it is
   called when the dialog is popped down.
   HIGHLIGHT_CB is the callback to call when entering/leaving menu items.

   Returns the widget created.  */
GtkWidget*
xg_create_widget (type, name, f, val,
                  select_cb, deactivate_cb, highlight_cb)
     char* type;
     char* name;
     FRAME_PTR f;
     widget_value* val;
     GCallback select_cb;
     GCallback deactivate_cb;
     GCallback highlight_cb;
{
  GtkWidget *w = 0;
  if (strcmp (type, "dialog") == 0)
    {
      w = create_dialog (val, select_cb, deactivate_cb);
      gtk_window_set_transient_for (GTK_WINDOW (w),
                                    GTK_WINDOW (FRAME_GTK_OUTER_WIDGET (f)));
      gtk_window_set_destroy_with_parent (GTK_WINDOW (w), TRUE);

      if (w)
        gtk_widget_set_name (w, "emacs-dialog");
    }
  else if (strcmp (type, "menubar") == 0 || strcmp (type, "popup") == 0)
    {
      w = create_menus (val->contents,
                        f,
                        select_cb,
                        deactivate_cb,
                        highlight_cb,
                        strcmp (type, "popup") == 0,
                        strcmp (type, "menubar") == 0,
                        1,
                        0,
                        0,
                        name);
    }
  else
    {
      fprintf (stderr, "bad type in xg_create_widget: %s, doing nothing\n",
               type);
    }

  return w;
}

static const char*
xg_get_menu_item_label (witem)
     GtkMenuItem *witem;
{
  GtkLabel *wlabel = GTK_LABEL (gtk_bin_get_child (GTK_BIN (witem)));
  return gtk_label_get_label (wlabel);
}

static int
xg_item_label_same_p (witem, label)
     GtkMenuItem *witem;
     char *label;
{
  int is_same;
  char *utf8_label = get_utf8_string (label);
  
  is_same = strcmp (utf8_label, xg_get_menu_item_label (witem)) == 0;
  if (utf8_label != label) g_free (utf8_label);

  return is_same;
}

/* Remove widgets in LIST from container WCONT.  */
static void
remove_from_container (wcont, list)
     GtkWidget *wcont;
     GList *list;
{
  /* We must copy list because gtk_container_remove changes it.  */
  GList *clist = g_list_copy (list);
  GList *iter;

  for (iter = clist; iter; iter = g_list_next (iter))
    {
      GtkWidget *w = GTK_WIDGET (iter->data);

      /* Add a ref to w so we can explicitly destroy it later.  */
      gtk_widget_ref (w);
      gtk_container_remove (GTK_CONTAINER (wcont), w);
  
      /* If there is a menu under this widget that has been detached,
         there is a reference to it, and just removing w from the
         container does not destroy the submenu.  By explicitly
         destroying w we make sure the submenu is destroyed, thus
         removing the detached window also if there was one.  */
      gtk_widget_destroy (w);
    }
  g_list_free (clist);
}

/* Update the top level names in MENUBAR (i.e. not submenus).
   F is the frame the menu bar belongs to.
   LIST is a list with the current menu bar names (menu item widgets).
   VAL describes what the menu bar shall look like after the update.
   SELECT_CB is the callback to use when a menu item is selected.
   HIGHLIGHT_CB is the callback to call when entering/leaving menu items.

   This function calls itself to walk through the menu bar names.  */
static void
xg_update_menubar (menubar, f, list, val, select_cb, highlight_cb, cl_data)
     GtkWidget *menubar;
     FRAME_PTR f;
     GList *list;
     widget_value* val;
     GCallback select_cb;
     GCallback highlight_cb;
     xg_menu_cb_data *cl_data;
{
  if (! list && ! val)
    return;
  else if (list && ! val)
    {
      /* Item(s) have been removed.  Remove all remaining items from list.  */
      remove_from_container (menubar, list);

      /* All updated.  */
      val = 0;
      list = 0;
    }
  else if (! list && val)
    {
      /* Item(s) added.  Add all new items in one call.  */
      create_menus (val, f, select_cb, 0, highlight_cb,
                    0, 1, 0, menubar, cl_data, 0);

      /* All updated.  */
      val = 0;
      list = 0;
    }
  /* Below this neither list or val is NULL */
  else if (xg_item_label_same_p (GTK_MENU_ITEM (list->data), val->name))
    {
      /* This item is still the same, check next item.  */
      val = val->next;
      list = g_list_next (list);
    }
  else /* This item is changed.  */
    {
      GtkMenuItem *witem = GTK_MENU_ITEM (list->data);
      GtkMenuItem *witem2 = 0;
      int pos = 0;
      int val_in_menubar = 0;
      int list_in_new_menubar = 0;
      GList *list2;
      GList *iter;
      widget_value* cur;


      /* Get position number for witem.  */
      list2 = gtk_container_get_children (GTK_CONTAINER (menubar));
      for (iter = list2; iter; iter = g_list_next (iter))
        {
          if (list->data == iter->data) break;
          ++pos;
        }

      /* See if the changed entry (val) is present later in the menu bar  */
      for (iter = g_list_next (list);
           iter && ! val_in_menubar;
           iter = g_list_next (iter))
        {
          witem2 = GTK_MENU_ITEM (iter->data);
          val_in_menubar = xg_item_label_same_p (witem2, val->name);
        }

      /* See if the current entry (list) is present later in the
         specification for the new menu bar.  */
      for (cur = val; cur && ! list_in_new_menubar; cur = cur->next)
        list_in_new_menubar = xg_item_label_same_p (witem, cur->name);

      if (val_in_menubar && ! list_in_new_menubar)
        {
          /*  This corresponds to:
                Current:  A B C
                New:      A C
              Remove B.  */
          
          gtk_widget_ref (GTK_WIDGET (witem));
          gtk_container_remove (GTK_CONTAINER (menubar), GTK_WIDGET (witem));
          gtk_widget_destroy (GTK_WIDGET (witem));

          /* Must get new list since the old changed.  */
          list = gtk_container_get_children (GTK_CONTAINER (menubar));
          while (pos-- > 0) list = g_list_next (list);
        }
      else if (! val_in_menubar && ! list_in_new_menubar)
        {
          /*  This corresponds to:
                Current:  A B C
                New:      A X C
              Rename B to X.  This might seem to be a strange thing to do,
              since if there is a menu under B it will be totally wrong for X.
              But consider editing a C file.  Then there is a C-mode menu
              (corresponds to B above).
              If then doing C-x C-f the minibuf menu (X above) replaces the
              C-mode menu.  When returning from the minibuffer, we get
              back the C-mode menu.  Thus we do:
                Rename B to X (C-mode to minibuf menu)
                Rename X to B (minibuf to C-mode menu).
              If the X menu hasn't been invoked, the menu under B
              is up to date when leaving the minibuffer.  */
          GtkLabel *wlabel = GTK_LABEL (gtk_bin_get_child (GTK_BIN (witem)));
          char *utf8_label = get_utf8_string (val->name);
          
          gtk_label_set_text_with_mnemonic (wlabel, utf8_label);

          list = g_list_next (list);
          val = val->next;
        }
      else if (! val_in_menubar && list_in_new_menubar)
        {
          /*  This corresponds to:
                Current:  A B C
                New:      A X B C
              Insert X.  */

          GList *group = 0;
          GtkWidget *w = xg_create_one_menuitem (val,
                                                 f,
                                                 select_cb,
                                                 highlight_cb,
                                                 cl_data,
                                                 &group);

          gtk_widget_set_name (w, MENU_ITEM_NAME);
          gtk_menu_shell_insert (GTK_MENU_SHELL (menubar), w, pos);

          list = gtk_container_get_children (GTK_CONTAINER (menubar));
          while (pos-- > 0) list = g_list_next (list);
          list = g_list_next (list);
          val = val->next;
        }
      else /* if (val_in_menubar && list_in_new_menubar) */
        {
          /*  This corresponds to:
                Current:  A B C
                New:      A C B
              Move C before B  */

          gtk_widget_ref (GTK_WIDGET (witem2));
          gtk_container_remove (GTK_CONTAINER (menubar), GTK_WIDGET (witem2));
          gtk_menu_shell_insert (GTK_MENU_SHELL (menubar),
                                 GTK_WIDGET (witem2), pos);
          gtk_widget_unref (GTK_WIDGET (witem2));

          val = val->next;
          list = gtk_container_get_children (GTK_CONTAINER (menubar));
          while (pos-- > 0) list = g_list_next (list);
          list = g_list_next (list);
      }
      
    }

  /* Update the rest of the menu bar.  */
  xg_update_menubar (menubar, f, list, val, select_cb, highlight_cb, cl_data);
}

/* Update the menu item W so it corresponds to VAL.
   SELECT_CB is the callback to use when a menu item is selected.
   HIGHLIGHT_CB is the callback to call when entering/leaving menu items.
   CL_DATA is the data to set in the widget for menu invokation.  */
static void
xg_update_menu_item (val, w, select_cb, highlight_cb, cl_data)
     widget_value* val;
     GtkWidget *w;
     GCallback select_cb;
     GCallback highlight_cb;
     xg_menu_cb_data *cl_data;
{
  GtkWidget *wchild;
  GtkLabel *wlbl = 0;
  GtkLabel *wkey = 0;
  char *utf8_label;
  char *utf8_key;
  xg_menu_item_cb_data *cb_data;
  
  wchild = gtk_bin_get_child (GTK_BIN (w));  
  utf8_label = get_utf8_string (val->name);
  utf8_key = get_utf8_string (val->key);

  /* See if W is a menu item with a key.  See make_menu_item above.  */
  if (GTK_IS_HBOX (wchild))
    {
      GList *list = gtk_container_get_children (GTK_CONTAINER (wchild));

      wlbl = GTK_LABEL (list->data);
      wkey = GTK_LABEL (list->next->data);
      if (! utf8_key)
        {
          /* Remove the key and keep just the label.  */
          gtk_widget_ref (GTK_WIDGET (wlbl));
          gtk_container_remove (GTK_CONTAINER (w), wchild);
          gtk_container_add (GTK_CONTAINER (w), GTK_WIDGET (wlbl));
          wkey = 0;
        }
    }
  else /* Just a label.  */
    {
      wlbl = GTK_LABEL (wchild);

      /* Check if there is now a key.  */
      if (utf8_key)
        {
          GtkWidget *wtoadd = make_widget_for_menu_item (utf8_label, utf8_key);
          GList *list = gtk_container_get_children (GTK_CONTAINER (wtoadd));
          wlbl = GTK_LABEL (list->data);
          wkey = GTK_LABEL (list->next->data);

          gtk_container_remove (GTK_CONTAINER (w), wchild);
          gtk_container_add (GTK_CONTAINER (w), wtoadd);
        }
    }

  if (utf8_key && strcmp (utf8_key, gtk_label_get_label (wkey)) != 0)
    gtk_label_set_text (wkey, utf8_key);

  if (strcmp (utf8_label, gtk_label_get_label (wlbl)) != 0)
    gtk_label_set_text_with_mnemonic (wlbl, utf8_label);

  if (utf8_key != val->key) g_free (utf8_key);
  if (utf8_label != val->name) g_free (utf8_label);
  
  if (! val->enabled && GTK_WIDGET_SENSITIVE (w))
    gtk_widget_set_sensitive (w, FALSE);
  else if (val->enabled && ! GTK_WIDGET_SENSITIVE (w))
    gtk_widget_set_sensitive (w, TRUE);

  cb_data = (xg_menu_item_cb_data*) g_object_get_data (G_OBJECT (w),
                                                       XG_ITEM_DATA);
  if (cb_data)
    {
      cb_data->call_data = val->call_data;
      cb_data->help = val->help;
      cb_data->cl_data = cl_data;
      
      /* We assume the callback functions don't change.  */
      if (val->call_data && ! val->contents)
        {
          /* This item shall have a select callback.  */
          if (! cb_data->select_id)
            cb_data->select_id
              = g_signal_connect (w, "activate", select_cb, cb_data);
        }
      else if (cb_data->select_id)
        {
          g_signal_handler_disconnect (w, cb_data->select_id);
          cb_data->select_id = 0;
        }

      if (NILP (cb_data->help))
        {
          /* Shall not have help.  Remove if any existed previously.  */
          if (cb_data->highlight_id)
            {
              g_signal_handler_disconnect (w, cb_data->highlight_id);
              cb_data->highlight_id = 0;
            }
          if (cb_data->unhighlight_id)
            {
              g_signal_handler_disconnect (w, cb_data->unhighlight_id);
              cb_data->unhighlight_id = 0;
            }
        }
      else if (! cb_data->highlight_id && highlight_cb)
        {
          /* Have help now, but didn't previously.  Add callback.  */
          cb_data->highlight_id
            = g_signal_connect (w,
                                "enter-notify-event",
                                G_CALLBACK (menuitem_highlight_callback),
                                cb_data);
          cb_data->unhighlight_id
            = g_signal_connect (w,
                                "leave-notify-event",
                                G_CALLBACK (menuitem_highlight_callback),
                                cb_data);
        }
    }
}

/* Update the toggle menu item W so it corresponds to VAL.  */
static void
xg_update_toggle_item (val, w)
     widget_value* val;
     GtkWidget* w;
{
  gtk_check_menu_item_set_active (GTK_CHECK_MENU_ITEM (w), val->selected);
}

/* Update the radio menu item W so it corresponds to VAL.  */
static void
xg_update_radio_item (val, w)
     widget_value* val;
     GtkWidget* w;
{
  gtk_check_menu_item_set_active (GTK_CHECK_MENU_ITEM (w), val->selected);
}

/* Update the sub menu SUBMENU and all its children so it corresponds to VAL.
   SUBMENU may be NULL, in that case a new menu is created.
   F is the frame the menu bar belongs to.
   VAL describes the contents of the menu bar.
   SELECT_CB is the callback to use when a menu item is selected.
   DEACTIVATE_CB is the callback to use when a sub menu is not shown anymore.
   HIGHLIGHT_CB is the callback to call when entering/leaving menu items.
   CL_DATA is the call back data to use for any newly created items.

   Returns the updated submenu widget, that is SUBMENU unless SUBMENU
   was NULL.  */

static GtkWidget*
xg_update_submenu (submenu, f, val,
                   select_cb, deactivate_cb, highlight_cb, cl_data)
     GtkWidget *submenu;
     FRAME_PTR f;
     widget_value* val;
     GCallback select_cb;
     GCallback deactivate_cb;
     GCallback highlight_cb;
     xg_menu_cb_data *cl_data;
{
  GtkWidget *newsub = submenu;
  GList *list = 0;
  GList *iter;
  widget_value* cur;
  int has_tearoff_p = 0;
  GList* first_radio = 0;
  
  if (submenu)
    list = gtk_container_get_children (GTK_CONTAINER (submenu));
  
  for (cur = val, iter = list;
       cur && iter;
       iter = g_list_next (iter), cur = cur->next)
  {
    GtkWidget *w = GTK_WIDGET (iter->data);

    /* Skip tearoff items, they have no counterpart in val.  */
    if (GTK_IS_TEAROFF_MENU_ITEM (w))
      {
        has_tearoff_p = 1;
        iter = g_list_next (iter);
        if (iter) w = GTK_WIDGET (iter->data);
        else break;
      }

    /* Remember first radio button in a group.  If we get a mismatch in
       a radio group we must rebuild the whole group so that the connections
       in GTK becomes correct.  */
    if (cur->button_type == BUTTON_TYPE_RADIO && ! first_radio)
      first_radio = iter;
    else if (cur->button_type != BUTTON_TYPE_RADIO
             && ! GTK_IS_RADIO_MENU_ITEM (w))
      first_radio = 0;

    if (GTK_IS_SEPARATOR_MENU_ITEM (w))
      {
        if (! xg_separator_p (cur->name))
          break;
      }
    else if (GTK_IS_CHECK_MENU_ITEM (w))
      {
        if (cur->button_type != BUTTON_TYPE_TOGGLE)
          break;
        xg_update_toggle_item (cur, w);
        xg_update_menu_item (cur, w, select_cb, highlight_cb, cl_data);
      }
    else if (GTK_IS_RADIO_MENU_ITEM (w))
      {
        if (cur->button_type != BUTTON_TYPE_RADIO)
          break;
        xg_update_radio_item (cur, w);
        xg_update_menu_item (cur, w, select_cb, highlight_cb, cl_data);
      }
    else if (GTK_IS_MENU_ITEM (w))
      {
        GtkMenuItem *witem = GTK_MENU_ITEM (w);
        GtkWidget *sub;

        if (cur->button_type != BUTTON_TYPE_NONE ||
            xg_separator_p (cur->name))
          break;

        xg_update_menu_item (cur, w, select_cb, highlight_cb, cl_data);

        sub = gtk_menu_item_get_submenu (witem);
        if (sub && ! cur->contents)
          {
            /* Not a submenu anymore.  */
            gtk_widget_ref (sub);
            gtk_menu_item_remove_submenu (witem);
            gtk_widget_destroy (sub);
          }
        else if (cur->contents)
          {
            GtkWidget *nsub;

            nsub = xg_update_submenu (sub, f, cur->contents,
                                      select_cb, deactivate_cb,
                                      highlight_cb, cl_data);

            /* If this item just became a submenu, we must set it.  */
            if (nsub != sub)
              gtk_menu_item_set_submenu (witem, nsub);
          }
      }
    else
      {
        /* Structural difference.  Remove everything from here and down
           in SUBMENU.  */
        break;
      }
  }

  /* Remove widgets from first structual change.  */
  if (iter)
    {
      /* If we are adding new menu items below, we must remove from
         first radio button so that radio groups become correct.  */
      if (cur && first_radio) remove_from_container (submenu, first_radio);
      else remove_from_container (submenu, iter);
    }
  
  if (cur)
    {
      /* More items added.  Create them.  */
      newsub = create_menus (cur,
                             f,
                             select_cb,
                             deactivate_cb,
                             highlight_cb,
                             0,
                             0,
                             ! has_tearoff_p,
                             submenu,
                             cl_data,
                             0);
    }
    
  return newsub;
}

/* Update the MENUBAR.
   F is the frame the menu bar belongs to.
   VAL describes the contents of the menu bar.
   If DEEP_P is non-zero, rebuild all but the top level menu names in
   the MENUBAR.  If DEEP_P is zero, just rebuild the names in the menubar.
   SELECT_CB is the callback to use when a menu item is selected.
   DEACTIVATE_CB is the callback to use when a sub menu is not shown anymore.
   HIGHLIGHT_CB is the callback to call when entering/leaving menu items.  */
void
xg_modify_menubar_widgets (menubar, f, val, deep_p,
                           select_cb, deactivate_cb, highlight_cb)
     GtkWidget *menubar;
     FRAME_PTR f;
     widget_value* val;
     int deep_p;
     GCallback select_cb;
     GCallback deactivate_cb;
     GCallback highlight_cb;
{
  xg_menu_cb_data *cl_data;
  GList *list = gtk_container_get_children (GTK_CONTAINER (menubar));
  GList *iter;

  if (! list) return;
  
  cl_data = (xg_menu_cb_data*) g_object_get_data (G_OBJECT(menubar),
                                                  XG_FRAME_DATA);

  if (! deep_p)
    {
      widget_value* cur = val->contents;
      xg_update_menubar (menubar, f, list, cur,
                         select_cb, highlight_cb, cl_data);
    }
  else
    {
      widget_value* cur;

      /* Update all sub menus.
         We must keep the submenu names (GTK menu item widgets) since the
         X Window in the XEvent that activates the menu are those widgets.  */

      /* Update cl_data, menu_item_* may have changed.  */
      update_cl_data (cl_data, f, highlight_cb);

      for (cur = val->contents; cur; cur = cur->next)
        {
          GtkWidget *sub = 0;
          GtkWidget *newsub;
          GtkMenuItem *witem;

          /* Find sub menu that corresponds to val and update it.  */
          for (iter = list ; iter; iter = g_list_next (iter))
            {
              witem = GTK_MENU_ITEM (iter->data);
              if (xg_item_label_same_p (witem, cur->name))
                {
                  sub = gtk_menu_item_get_submenu (witem);
                  break;
                }
            }
          
          newsub = xg_update_submenu (sub,
                                      f,
                                      cur->contents,
                                      select_cb,
                                      deactivate_cb,
                                      highlight_cb,
                                      cl_data);
          /* sub may still be NULL.  If we just updated non deep and added
             a new menu bar item, it has no sub menu yet.  So we set the
             newly created sub menu under witem.  */
          if (newsub != sub)
            gtk_menu_item_set_submenu (witem, newsub);

        }
    }

  gtk_widget_show_all (menubar);
}

/* Make a geometry string and pass that to GTK.  It seems this is the
   only way to get geometry position right if the user explicitly
   asked for a position when starting Emacs.
   F is the frame we shall set geometry for.  */
static void
xg_set_geometry (f)
     FRAME_PTR f;
{
  if (f->output_data.x->size_hint_flags & USPosition)
  {
    int left = f->output_data.x->left_pos;
    int xneg = f->output_data.x->size_hint_flags & XNegative;
    int top = f->output_data.x->top_pos;
    int yneg = f->output_data.x->size_hint_flags & YNegative;
    char geom_str[32];
    
    if (xneg)
      left = -left;
    if (yneg)
      top = -top;

    sprintf (geom_str, "=%dx%d%c%d%c%d",
             PIXEL_WIDTH (f),
             PIXEL_HEIGHT (f) + FRAME_MENUBAR_HEIGHT (f),
             (xneg ? '-' : '+'), left,
             (yneg ? '-' : '+'), top);

    if (!gtk_window_parse_geometry (GTK_WINDOW (FRAME_GTK_OUTER_WIDGET (f)),
                                    geom_str))
      fprintf (stderr, "Failed to parse: '%s'\n", geom_str);
  }
}

     
/* Recompute all the widgets of frame F, when the menu bar has been
   changed.  Value is non-zero if widgets were updated.  */

int
xg_update_frame_menubar (f)
     FRAME_PTR f;
{
  struct x_output *x = f->output_data.x;
  GtkRequisition req;
  
  if (!x->menubar_widget || GTK_WIDGET_MAPPED (x->menubar_widget))
    return 0;

  BLOCK_INPUT;

  gtk_box_pack_start (GTK_BOX (x->vbox_widget), x->menubar_widget,
                      FALSE, FALSE, 0);
  gtk_box_reorder_child (GTK_BOX (x->vbox_widget), x->menubar_widget, 0);

  gtk_widget_show_all (x->menubar_widget);
  gtk_widget_size_request (x->menubar_widget, &req);

  FRAME_MENUBAR_HEIGHT (f) = req.height;
  gtk_window_resize (GTK_WINDOW (FRAME_GTK_OUTER_WIDGET (f)),
                     PIXEL_WIDTH (f), req.height + PIXEL_HEIGHT (f));
  gdk_window_process_all_updates ();
  x_wm_set_size_hint (f, 0, 0);

  /* If we are not mapped yet, set geometry once again, as window
     height now has changed.  */
  if (! GTK_WIDGET_MAPPED (FRAME_GTK_OUTER_WIDGET (f)))
    xg_set_geometry (f);
  
  SET_FRAME_GARBAGED (f);
  UNBLOCK_INPUT;
}

/* Get rid of the menu bar of frame F, and free its storage.
   This is used when deleting a frame, and when turning off the menu bar.  */

void
free_frame_menubar (f)
     FRAME_PTR f;
{
  struct x_output *x = f->output_data.x;

  if (x->menubar_widget)
    {
      BLOCK_INPUT;

      gtk_container_remove (GTK_CONTAINER (x->vbox_widget), x->menubar_widget);
       /* The menubar and its children shall be deleted when removed from
          the container.  */
      x->menubar_widget = 0;
      FRAME_MENUBAR_HEIGHT (f) = 0;

      /* base_height is now changed.  */
      x_wm_set_size_hint (f, 0, 0);
      SET_FRAME_GARBAGED (f);
      UNBLOCK_INPUT;
    }
}


\f
/***********************************************************************
                      Scrollbar functions
 ***********************************************************************/


/* Setting scrollbar values invokes the callback.  Use this variable
   to indicate that callback should do nothing.  */
int xg_ignore_gtk_scrollbar;

/* After we send a scroll bar event,  x_set_toolkit_scroll_bar_thumb will
   be called.  For some reason that needs to be debugged, it gets called
   with bad values.  Thus, we set this variable to ignore those calls.  */
int xg_ignore_next_thumb;

/* The cursor used for scroll bars.  We only have one cursor for all
   scroll bars.  */
static GdkCursor *xg_scrollbar_cursor;

/* SET_SCROLL_BAR_X_WINDOW assumes the second argument fits in
   32 bits.  But we want to store pointers, and they may be larger
   than 32 bits.  Keep a mapping from integer index to widget pointers
   to get around the 32 bit limitation.  */
static struct
{
  GtkWidget **widgets;
  int max_size;
  int used;
} id_to_widget = { 0, 0, 0 };

/* Grow this much every time we need to allocate more  */
#define ID_TO_WIDGET_INCR  32

/* Store the widget pointer W in id_to_widget and return the integer index.  */
static int
xg_store_widget_in_map (w)
     GtkWidget *w;
{
  int i;

  if (id_to_widget.max_size == id_to_widget.used)
    {
      int new_size = id_to_widget.max_size + ID_TO_WIDGET_INCR;

      id_to_widget.widgets = xrealloc (id_to_widget.widgets,
                                       sizeof (GtkWidget *)*new_size);

      for (i = id_to_widget.max_size; i < new_size; ++i)
        id_to_widget.widgets[i] = 0;
      id_to_widget.max_size = new_size;
    }

  /* Just loop over the array and find a free place.  After all,
     how many scrollbars are we creating?  Should be a small number.
     The check above guarantees we will find a free place.  */
  for (i = 0; i < id_to_widget.max_size; ++i)
    {
      if (! id_to_widget.widgets[i])
        {
          id_to_widget.widgets[i] = w;
          ++id_to_widget.used;

          return i;
        }
    }

  /* Should never end up here  */
  abort ();
}

/* Remove pointer at IDX from id_to_widget.
   Called when scrollbar is destroyed.  */
static void
xg_remove_widget_from_map (idx)
     int idx;
{
  if (idx < id_to_widget.max_size && id_to_widget.widgets[idx] != 0)
    {
      id_to_widget.widgets[idx] = 0;
      --id_to_widget.used;
    }
}

/* Get the widget pointer at IDX from id_to_widget. */
static GtkWidget*
xg_get_widget_from_map (idx)
     int idx;
{
  if (idx < id_to_widget.max_size && id_to_widget.widgets[idx] != 0)
    return id_to_widget.widgets[idx];

  return 0;
}

/* Callback invoked when scrollbar WIDGET is destroyed.
   DATA is the index into id_to_widget for WIDGET.
   We free pointer to last scrollbar value here and remove the index.  */
static void
xg_gtk_scroll_destroy (widget, data)
     GtkWidget *widget;
     gpointer data;
{
  gpointer p;
  int id = (int)data;
  
  p = g_object_get_data (G_OBJECT (widget), XG_LAST_SB_DATA);
  if (p) xfree (p);
  xg_remove_widget_from_map (id);
}

/* Callback for button press/release events.  Used to start timer so that
   the scroll bar repetition timer in GTK gets handeled.
   WIDGET is the scroll bar widget the event is for (not used).
   EVENT contains the event.
   USER_DATA is 0 (not used).

   Returns FALSE to tell GTK that it shall continue propagate the event
   to widgets.  */
static gboolean
scroll_bar_button_cb (widget, event, user_data)
     GtkWidget *widget;
     GdkEventButton *event;
     gpointer user_data;
{
  if (event->type == GDK_BUTTON_PRESS && ! xg_timer)
    xg_start_timer ();
  else if (event->type == GDK_BUTTON_RELEASE && xg_timer)
    xg_stop_timer ();

  return FALSE;
}

/* Create a scrollbar widget for frame F.  Store the scrollbar
   in BAR.
   SCROLL_CALLBACK is the callback to invoke when the value of the
   bar changes.
   SCROLL_BAR_NAME is the name we use for the scroll bar.  Can be used
   to set resources for the widget.  */
void
xg_create_scroll_bar (f, bar, scroll_callback, scroll_bar_name)
     FRAME_PTR f;
     struct scroll_bar *bar;
     GCallback scroll_callback;
     char *scroll_bar_name;
{
  GtkWidget *wscroll;
  GtkObject *vadj;
  int scroll_id;
  
  /* Page, step increment values are not so important here, they
     will be corrected in x_set_toolkit_scroll_bar_thumb. */
  vadj = gtk_adjustment_new (XG_SB_MIN, XG_SB_MIN, XG_SB_MAX,
                             0.1, 0.1, 0.1);

  wscroll = gtk_vscrollbar_new (GTK_ADJUSTMENT (vadj));
  gtk_widget_set_name (wscroll, scroll_bar_name);
  gtk_range_set_update_policy (GTK_RANGE (wscroll), GTK_UPDATE_CONTINUOUS);
  
  scroll_id = xg_store_widget_in_map (wscroll);
  
  g_signal_connect (vadj,
                    "value-changed",
                    scroll_callback,
                    (gpointer)bar);
  g_signal_connect (wscroll,
                    "destroy",
                    G_CALLBACK (xg_gtk_scroll_destroy),
                    (gpointer)scroll_id);

  /* Connect to button press and button release to detect if any scroll bar
     has the pointer.  */
  g_signal_connect (wscroll,
                    "button-press-event",
                    G_CALLBACK (scroll_bar_button_cb),
                    (gpointer)1);
  g_signal_connect (wscroll,
                    "button-release-event",
                    G_CALLBACK (scroll_bar_button_cb),
                    0);
  
  gtk_fixed_put (GTK_FIXED (f->output_data.x->edit_widget),
                 wscroll, 0, 0);

  /* Create the cursor for scrollbars unless already created.  */
  if (! xg_scrollbar_cursor)
    xg_scrollbar_cursor = gdk_cursor_new (GDK_LEFT_PTR);
        
  /* Set the cursor to an arrow.  */
  {
    GList *children = gdk_window_peek_children (wscroll->window);
    gdk_window_set_cursor (wscroll->window, xg_scrollbar_cursor);

    /* The scroll bar widget has more than one GDK window (had to look at
       the source to figure this out), and there is no way to set cursor
       on widgets in GTK.  So we must set the cursor for all GDK windows.  */
    for ( ; children; children = g_list_next (children))
      gdk_window_set_cursor (GDK_WINDOW (children->data), xg_scrollbar_cursor);
  }

  SET_SCROLL_BAR_X_WINDOW (bar, scroll_id);
}

/* Make the scrollbar represented by SCROLLBAR_ID visible.  */
void
xg_show_scroll_bar (scrollbar_id)
     int scrollbar_id;
{
  GtkWidget *w = xg_get_widget_from_map (scrollbar_id);
  if (w)
    gtk_widget_show (w);
}

/* Remove the scrollbar represented by SCROLLBAR_ID from the frame F.  */
void
xg_remove_scroll_bar (f, scrollbar_id)
     FRAME_PTR f;
     int scrollbar_id;
{
  GtkWidget *w = xg_get_widget_from_map (scrollbar_id);
  if (w)
    {
      gtk_widget_destroy (w);
      SET_FRAME_GARBAGED (f);
    }
}


/* Update the position of the vertical scrollbar represented by SCROLLBAR_ID
   in frame F.
   TOP/LEFT are the new pixel positions where the bar shall appear.
   WIDTH, HEIGHT is the size in pixels the bar shall have.  */
void
xg_update_scrollbar_pos (f, scrollbar_id, top, left, width, height)     
     FRAME_PTR f;
     int scrollbar_id;
     int top;
     int left;
     int width;
     int height;
{
    GtkWidget *wscroll = xg_get_widget_from_map (scrollbar_id);

    if (wscroll)
      {
        int gheight = max (height, 1);

        gtk_fixed_move (GTK_FIXED (f->output_data.x->edit_widget),
                        wscroll, left, top);

        gtk_widget_set_size_request (wscroll, width, gheight);

        /* Must force out update so wscroll gets the resize.
           Otherwise, the gdk_window_clear clears the old window size.  */
        gdk_window_process_all_updates ();

        /* The scroll bar doesn't explicitly redraw the whole window
           when a resize occurs.  Since the scroll bar seems to be fixed
           in width it doesn't fill the space reserved, so we must clear
           the whole window.  */
        gdk_window_clear (wscroll->window);

        /* Since we are not using a pure gtk event loop, we must force out
           pending update events with this call.  */
        gdk_window_process_all_updates ();

        SET_FRAME_GARBAGED (f);
        cancel_mouse_face (f);
      }
}

/* Set the thumb size and position of scroll bar BAR.  We are currently
   displaying PORTION out of a whole WHOLE, and our position POSITION.  */
void
xg_set_toolkit_scroll_bar_thumb (bar, portion, position, whole)
     struct scroll_bar *bar;
     int portion, position, whole;
{
  GtkWidget *wscroll = xg_get_widget_from_map (SCROLL_BAR_X_WINDOW (bar));

  FRAME_PTR f = XFRAME (WINDOW_FRAME (XWINDOW (bar->window)));

  BLOCK_INPUT;
  if (wscroll && ! xg_ignore_next_thumb)
    {
      GtkAdjustment* adj;
      gdouble shown;
      gdouble top;
      int size, value;
      
      adj = gtk_range_get_adjustment (GTK_RANGE (wscroll));

      if (whole <= 0)
        top = 0, shown = 1;
      else
        {
          shown = (gdouble) portion / whole;
          top = (gdouble) position / whole;
        }

      size = shown * whole;
      size = min (size, whole);
      size = max (size, 1);

      value = top * whole;
      value = min (value, whole - size);
      value = max (value, XG_SB_MIN);

      adj->upper = max (whole, size);
      adj->page_size = (int)size;

      /* Assume a page increment is about 95% of the page size  */
      adj->page_increment = (int) (0.95*adj->page_size);

      /* Assume all lines are equal.  */
      adj->step_increment = portion / max (1, FRAME_HEIGHT (f));

      /* gtk_range_set_value invokes the callback.  Set
         ignore_gtk_scrollbar to make the callback do nothing  */
      xg_ignore_gtk_scrollbar = 1;
      gtk_range_set_value (GTK_RANGE (wscroll), (gdouble)value);
      xg_ignore_gtk_scrollbar = 0;
    }

  /* Make sure the scrollbar is redrawn with new thumb  */
  gtk_widget_queue_draw (wscroll);
  gdk_window_process_all_updates ();
  xg_ignore_next_thumb = 0;
  UNBLOCK_INPUT;
}

\f
/***********************************************************************
    General functions for creating widgets, resizing, events, e.t.c.
 ***********************************************************************/


/* Function to handle resize of our widgets.  Since Emacs has some layouts
   that does not fit well with GTK standard containers, we do most layout
   manually.
   F is the frame to resize.
   PIXELWIDTH, PIXELHEIGHT is the new size in pixels.  */
void
xg_resize_widgets (f, pixelwidth, pixelheight)
     FRAME_PTR f;
     int pixelwidth, pixelheight;
{
  int mbheight = FRAME_MENUBAR_HEIGHT (f);
  int rows = PIXEL_TO_CHAR_HEIGHT (f, pixelheight - mbheight);
  int columns = PIXEL_TO_CHAR_WIDTH (f, pixelwidth);
  
  if (FRAME_GTK_WIDGET (f)
      && (columns != FRAME_WIDTH (f) || rows != FRAME_HEIGHT (f)
          || pixelwidth != PIXEL_WIDTH (f) || pixelheight != PIXEL_HEIGHT (f)))
    {
      struct x_output *x = f->output_data.x;
      GtkAllocation all;

      all.y = mbheight;
      all.x = 0;

      all.width = pixelwidth;
      all.height = pixelheight - mbheight;

      gtk_widget_size_allocate (x->edit_widget, &all);
      gdk_window_process_all_updates ();

      change_frame_size (f, rows, columns, 0, 1, 0);
      SET_FRAME_GARBAGED (f);
      cancel_mouse_face (f);
    }
}


/* Update our widget size to be COLS/ROWS characters for frame F.  */
void
xg_frame_set_char_size (f, cols, rows)
     FRAME_PTR f;
     int cols;
     int rows;
{
  int pixelheight = CHAR_TO_PIXEL_HEIGHT (f, rows) + FRAME_MENUBAR_HEIGHT (f);
  int pixelwidth = CHAR_TO_PIXEL_WIDTH (f, cols);

  /* Take into account the size of the scrollbar.  Always use the
     number of columns occupied by the scroll bar here otherwise we
     might end up with a frame width that is not a multiple of the
     frame's character width which is bad for vertically split
     windows.  */
  f->output_data.x->vertical_scroll_bar_extra
    = (!FRAME_HAS_VERTICAL_SCROLL_BARS (f)
       ? 0
       : (FRAME_SCROLL_BAR_COLS (f)
          * FONT_WIDTH (f->output_data.x->font)));

  x_compute_fringe_widths (f, 0);

  /* Must resize our top level widget.  Font size may have changed,
     but not rows/cols.  */
  gtk_window_resize (GTK_WINDOW (FRAME_GTK_OUTER_WIDGET (f)),
                     pixelwidth, pixelheight);
  xg_resize_widgets (f, pixelwidth, pixelheight);
}

/* Convert an X Window WSESC to its corresponding GtkWidget.
   Must be done like this, because GtkWidget:s can have "hidden"
   X Window that aren't accessible.

   Return 0 if no widget match WDESC.  */
GtkWidget*
xg_win_to_widget (wdesc)
     Window wdesc;
{
  gpointer gdkwin;
  GtkWidget *gwdesc = 0;

  BLOCK_INPUT;
  gdkwin = gdk_xid_table_lookup (wdesc);
  if (gdkwin)
    {
      GdkEvent event;
      event.any.window = gdkwin;
      gwdesc = gtk_get_event_widget (&event);
    }
  
  UNBLOCK_INPUT;
  return gwdesc;
}

/* Fill in the GdkColor C so that it represents PIXEL.
   W is the widget that color will be used for.  Used to find colormap.  */
static void
xg_pix_to_gcolor (w, pixel, c)
     GtkWidget *w;
     unsigned long pixel;
     GdkColor *c;
{
  GdkColormap *map = gtk_widget_get_colormap (w);
  gdk_colormap_query_color (map, pixel, c);
}

/* Create and set up the GTK widgets for frame F.
   Return 0 if creation failed, non-zero otherwise.  */
int
xg_create_frame_widgets (f)
     FRAME_PTR f;
{
  GtkWidget *wtop;
  GtkWidget *wvbox;
  GtkWidget *wfixed;
  GdkColor bg;
  int i;

  BLOCK_INPUT;

  wtop = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  wvbox = gtk_vbox_new (FALSE, 0);
  wfixed = gtk_fixed_new ();  /* Must have this to place scrollbars  */
  
  if (! wtop || ! wvbox || ! wfixed)
    {
      if (wtop) gtk_widget_destroy (wtop);
      if (wvbox) gtk_widget_destroy (wvbox);
      if (wfixed) gtk_widget_destroy (wfixed);

      return 0;
    }

  /* Use same names as the Xt port does.  I.e. Emacs.pane.emacs by default */
  gtk_widget_set_name (wtop, EMACS_CLASS);
  gtk_widget_set_name (wvbox, "pane");
  gtk_widget_set_name (wfixed, SDATA (Vx_resource_name));
  
  FRAME_GTK_OUTER_WIDGET (f) = wtop;
  FRAME_GTK_WIDGET (f) = wfixed;
  f->output_data.x->vbox_widget = wvbox;
  
  gtk_fixed_set_has_window (GTK_FIXED (wfixed), TRUE);

  gtk_widget_set_size_request (wfixed,
                               PIXEL_WIDTH (f),
                               PIXEL_HEIGHT (f));
  
  gtk_container_add (GTK_CONTAINER (wtop), wvbox);
  gtk_box_pack_end (GTK_BOX (wvbox), wfixed, TRUE, TRUE, 0);
  
  gtk_widget_set_double_buffered (wvbox, FALSE);
  gtk_widget_set_double_buffered (wfixed, FALSE);
  gtk_widget_set_double_buffered (wtop, FALSE);
  
  /* GTK documents says use gtk_window_set_resizable.  But then a user
     can't shrink the window from its starting size.  */
  gtk_window_set_policy (GTK_WINDOW (wtop), TRUE, TRUE, TRUE);
  gtk_window_set_wmclass (GTK_WINDOW (wtop),
                          SDATA (Vx_resource_name),
                          SDATA (Vx_resource_class));
   
  /* Convert our geometry parameters into a geometry string
     and specify it.
     GTK will itself handle calculating the real position this way.  */
  xg_set_geometry (f);

  gtk_widget_add_events (wfixed,
                         GDK_POINTER_MOTION_MASK
                         | GDK_EXPOSURE_MASK
                         | GDK_BUTTON_PRESS_MASK
                         | GDK_BUTTON_RELEASE_MASK
                         | GDK_KEY_PRESS_MASK
                         | GDK_ENTER_NOTIFY_MASK
                         | GDK_LEAVE_NOTIFY_MASK
                         | GDK_FOCUS_CHANGE_MASK
                         | GDK_STRUCTURE_MASK
                         | GDK_VISIBILITY_NOTIFY_MASK);

  /* Must realize the windows so the X window gets created.  It is used
     by callers of this function.  */
  gtk_widget_realize (wfixed);
  FRAME_X_WINDOW (f) = GTK_WIDGET_TO_X_WIN (wfixed);

  /* Since GTK clears its window by filling with the background color,
     we must keep X and GTK background in sync.  */
  xg_pix_to_gcolor (wfixed, f->output_data.x->background_pixel, &bg);
  gtk_widget_modify_bg (wfixed, GTK_STATE_NORMAL, &bg);
  
  /* GTK does not set any border, and they look bad with GTK.  */
  f->output_data.x->border_width = 0;
  f->output_data.x->internal_border_width = 0;
  UNBLOCK_INPUT;

  return 1;
}

/* Set the normal size hints for the window manager, for frame F.
   FLAGS is the flags word to use--or 0 meaning preserve the flags
   that the window now has.
   If USER_POSITION is nonzero, we set the User Position
   flag (this is useful when FLAGS is 0).  */
void
x_wm_set_size_hint (f, flags, user_position)
     FRAME_PTR f;
     long flags;
     int user_position;
{
  if (FRAME_GTK_OUTER_WIDGET (f))
  {
    /* Must use GTK routines here, otherwise GTK resets the size hints
       to its own defaults.  */
    GdkGeometry size_hints;
    gint hint_flags = 0;
    int base_width, base_height;
    int min_rows = 0, min_cols = 0;
    int win_gravity = f->output_data.x->win_gravity;
    
    if (flags)
      {
        memset (&size_hints, 0, sizeof (size_hints));
        f->output_data.x->size_hints = size_hints;
        f->output_data.x->hint_flags = hint_flags;
      }
     else
       flags = f->output_data.x->size_hint_flags;
    
    size_hints = f->output_data.x->size_hints;
    hint_flags = f->output_data.x->hint_flags;

    hint_flags |= GDK_HINT_RESIZE_INC | GDK_HINT_MIN_SIZE;
    size_hints.width_inc = FONT_WIDTH (f->output_data.x->font);
    size_hints.height_inc = f->output_data.x->line_height;

    hint_flags |= GDK_HINT_BASE_SIZE;
    base_width = CHAR_TO_PIXEL_WIDTH (f, 0);
    base_height = CHAR_TO_PIXEL_HEIGHT (f, 0) + FRAME_MENUBAR_HEIGHT (f);

    check_frame_size (f, &min_rows, &min_cols);

    size_hints.base_width = base_width;
    size_hints.base_height = base_height;
    size_hints.min_width  = base_width + min_cols * size_hints.width_inc;
    size_hints.min_height = base_height + min_rows * size_hints.height_inc;

    
    /* These currently have a one to one mapping with the X values, but I
       don't think we should rely on that.  */
    hint_flags |= GDK_HINT_WIN_GRAVITY;
    size_hints.win_gravity = 0;
    if (win_gravity == NorthWestGravity)
      size_hints.win_gravity = GDK_GRAVITY_NORTH_WEST;
    else if (win_gravity == NorthGravity)
      size_hints.win_gravity = GDK_GRAVITY_NORTH;
    else if (win_gravity == NorthEastGravity)
      size_hints.win_gravity = GDK_GRAVITY_NORTH_EAST;
    else if (win_gravity == WestGravity)
      size_hints.win_gravity = GDK_GRAVITY_WEST;
    else if (win_gravity == CenterGravity)
      size_hints.win_gravity = GDK_GRAVITY_CENTER;
    else if (win_gravity == EastGravity)
      size_hints.win_gravity = GDK_GRAVITY_EAST;
    else if (win_gravity == SouthWestGravity)
      size_hints.win_gravity = GDK_GRAVITY_SOUTH_WEST;
    else if (win_gravity == SouthGravity)
      size_hints.win_gravity = GDK_GRAVITY_SOUTH;
    else if (win_gravity == SouthEastGravity)
      size_hints.win_gravity = GDK_GRAVITY_SOUTH_EAST;
    else if (win_gravity == StaticGravity)
      size_hints.win_gravity = GDK_GRAVITY_STATIC;

    if (flags & PPosition) hint_flags |= GDK_HINT_POS;
    if (flags & USPosition) hint_flags |= GDK_HINT_USER_POS;
    if (flags & USSize) hint_flags |= GDK_HINT_USER_SIZE;

    if (user_position)
      {
        hint_flags &= ~GDK_HINT_POS;
        hint_flags |= GDK_HINT_USER_POS;
      }

    BLOCK_INPUT;

    gtk_window_set_geometry_hints (GTK_WINDOW (FRAME_GTK_OUTER_WIDGET (f)),
                                   FRAME_GTK_OUTER_WIDGET (f),
                                   &size_hints,
                                   hint_flags);

    f->output_data.x->size_hints = size_hints;
    f->output_data.x->hint_flags = hint_flags;
    UNBLOCK_INPUT;
  }
}

/* Change background color of a frame.
   Since GTK uses the background colour to clear the window, we must
   keep the GTK and X colors in sync.
   F is the frame to change,
   BG is the pixel value to change to.  */
void
xg_set_background_color (f, bg)
     FRAME_PTR f;
     unsigned long bg;
{
  if (FRAME_GTK_WIDGET (f))
    {
      GdkColor gdk_bg;

      BLOCK_INPUT;
      xg_pix_to_gcolor (FRAME_GTK_WIDGET (f), bg, &gdk_bg);
      gtk_widget_modify_bg (FRAME_GTK_WIDGET (f), GTK_STATE_NORMAL, &gdk_bg);
      UNBLOCK_INPUT;
    }
}


\f
/***********************************************************************
                      Initializing
 ***********************************************************************/
void
xg_initialize ()
{
  GType type;
  GObjectClass *oclass;
  GtkBindingSet *binding_set;

  xg_ignore_gtk_scrollbar = 0;
  xg_ignore_next_thumb = 0;
  xg_scrollbar_cursor = 0;
  xg_did_tearoff = 0;

  xg_menu_cb_list.prev = xg_menu_cb_list.next =
    xg_menu_item_cb_list.prev = xg_menu_item_cb_list.next = 0;
}

#endif /* USE_GTK */

[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/emacs-devel

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
       [not found] <200212311545.gbvfjt0u023298@stubby.bodenonline.com>
@ 2002-12-31 18:06 ` Phillip Garland
  0 siblings, 0 replies; 68+ messages in thread
From: Phillip Garland @ 2002-12-31 18:06 UTC (permalink / raw)
  Cc: emacs-devel

Thanks. That seems to fix the problem when I am not running emacs under gdb. I still see this when I am running emacs under gdb with the supplied .gdbinit file..

~Phillip


On Tue, 31 Dec 2002, Jan D. wrote:

> > Hello,
> > 
> > I've compiled and ran version 3 of your GTK+ patch on a PPC GNU/Linux system with GTK+ 2.0.9.
> > 
> > There is one behavior that I find annoying and confusing. If I click on a menu, then move the mouse pointer to another menu, sometimes the menu name that I have moved to will become "highlighted", but the menu itself does not pop down. If I move the mouse again, hit a key, or click and hold a mouse button, the menu then does pop down. 
> > 
> 
> Funny I didn't see that, now that you mention it, it is obvious :-)
> Anyway, this has to do with the fact that Emacs doesn't see GTK timers
> so we have to make some special code to handle GTK timeouts, Xt have the
> same problem.
> 
> As a comment to the signal handler discussion, these problems
> would go away if Emacs could use a "normal" event loop (i.e. Xt/GTK/whatever)
> instead of handling X events in a signal handler.  This is paritulary true
> for GTK which delays some things untill it gets back to the event loop.
> These never result in X events.  There is special handling for those cases
> also in Emacs/GTK (gdk_window_process_all_updates for example).
> 
> Anyway, I've attached a fixed gtkutil.c.
> 
> Thanks,
> 
> 	Jan D.
> 
> 
> 

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
       [not found] <200212310414.gbv4et0u014643@stubby.bodenonline.com>
  2002-12-31  5:33 ` Phillip Garland
@ 2002-12-31 21:07 ` Phillip Garland
  2002-12-31 23:59   ` Jan D.
  1 sibling, 1 reply; 68+ messages in thread
From: Phillip Garland @ 2002-12-31 21:07 UTC (permalink / raw)
  Cc: emacs-devel

Hello,

With the new GTK+ patch, some of the file selection dialog boxes are broken for me. For example, if I want to diff 2 files by choosing the "Two Files..." item from the "Compare (Ediff)" submenu of the "Tools" menu, the file selection dialog box pops ups, and I am able to navigate through directories using the directory listing box on the left, but all the files in the file listing box on the right are greyed out, and I am unable to select any of them with the mouse. The text box does not work either- when I position the mouse cursor in the text box, I am unable to type in it.

This glitch occurs with items from the "Compare (Ediff)" "Merge", and "Apply Patch" submenus of the "Tools" menu, and "Insert File..." from the "File" menu. 

The file selection dialog boxes for "Open File..." and PCL-CVS do work correctly.

~Phillip

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2002-12-31 21:07 ` Phillip Garland
@ 2002-12-31 23:59   ` Jan D.
  0 siblings, 0 replies; 68+ messages in thread
From: Jan D. @ 2002-12-31 23:59 UTC (permalink / raw)
  Cc: emacs-devel

> Hello,
> 
> With the new GTK+ patch, some of the file selection dialog boxes are broken for me. For example, if I want to diff 2 files by choosing the "Two Files..." item from the "Compare (Ediff)" submenu of the "Tools" menu, the file selection dialog box pops ups, and I am able to navigate through directories using the directory listing box on the left, but all the files in the file listing box on the right are greyed out, and I am unable to select any of them with the mouse. The text box does not work either- when I position the mouse cursor in the text box, I am unable to type in it.
> 
> This glitch occurs with items from the "Compare (Ediff)" "Merge", and "Apply Patch" submenus of the "Tools" menu, and "Insert File..." from the "File" menu. 

Yes, I misunderstood the mustmatch parameter.  Will be corrected in the
next patch or when checking in.

Thanks,

	Jan D.

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2002-12-31  3:17 Gtk patch version 3, part 1 Jan D.
@ 2003-01-01 16:46 ` Richard Stallman
  2003-01-01 18:48   ` Jan D.
  2003-01-02 15:47   ` Kim F. Storm
  2003-01-02  5:52 ` Eli Zaretskii
  1 sibling, 2 replies; 68+ messages in thread
From: Richard Stallman @ 2003-01-01 16:46 UTC (permalink / raw)
  Cc: emacs-devel

+ @cindex GTK customize, @file{~/.gtkrc-2.0} file

This is too long for an index entry.  Also, they
don't belong in the same entry.  They should be two entries.

  See documents at
+ @uref{http://www.gtk.org/} for that.

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.

    +   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.

The word "resources" is an ordinary noun, so don't capitailze it.
It should be "etc.", not "e.t.c."

+   For dialogs a GtkDialog is used.

Please avoid the passive voice, here and everywhere, unless
it is absolutely necessary.

    + @example
    + widget_class "GtkWindow.GtkVBox.GtkFixed.GtkVScrollbar" style "my_style"
    + @end example

That line is very long.  It might work ok if you use @smallexample
instead of @example.  Please do that for all the examples in the
section; inconsistency looks bad.

Can this be written as two lines?

+   So the two full paths above are in Emacs the same as:

That's not very clear language.  How about

    Thus, for Emacs you can write the two examples above as:

if that is what you mean.

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-01 16:46 ` Richard Stallman
@ 2003-01-01 18:48   ` Jan D.
  2003-01-02  1:10     ` Eric Gillespie
                       ` (3 more replies)
  2003-01-02 15:47   ` Kim F. Storm
  1 sibling, 4 replies; 68+ messages in thread
From: Jan D. @ 2003-01-01 18:48 UTC (permalink / raw)
  Cc: emacs-devel

> 
> + @cindex GTK customize, @file{~/.gtkrc-2.0} file
> 
> This is too long for an index entry.  Also, they
> don't belong in the same entry.  They should be two entries.

Okay, I just copied the layout from these index entries at the top of the
file:
@cindex X resources, @file{~/.Xdefaults} file
@cindex X resources, @file{~/.Xresources} file

> 
>   See documents at
> + @uref{http://www.gtk.org/} for that.
> 
> 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"?

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

>     +   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?

> The word "resources" is an ordinary noun, so don't capitailze it.
> It should be "etc.", not "e.t.c."

Changed.

> 
> +   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.

>     + @example
>     + widget_class "GtkWindow.GtkVBox.GtkFixed.GtkVScrollbar" style "my_style"
>     + @end example
> 
> That line is very long.  It might work ok if you use @smallexample
> instead of @example.  Please do that for all the examples in the
> section; inconsistency looks bad.
> 
> Can this be written as two lines?

It must be one line in the ~/.gtkrc-2.0 file, so I would like to avoid
changing it.

> +   So the two full paths above are in Emacs the same as:
> 
> That's not very clear language.  How about
> 
>     Thus, for Emacs you can write the two examples above as:
> 
> if that is what you mean.

Yes it is, thanks.

	Jan D.

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-01 18:48   ` Jan D.
@ 2003-01-02  1:10     ` Eric Gillespie
  2003-01-02  7:57       ` Jan D.
  2003-01-02  5:56     ` Eli Zaretskii
                       ` (2 subsequent siblings)
  3 siblings, 1 reply; 68+ messages in thread
From: Eric Gillespie @ 2003-01-02  1:10 UTC (permalink / raw)


"Jan D." <jan.h.d@swipnet.se> writes:

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

That isn't really a good idea.  That directory might be anywhere:
/usr/share, /usr/local/share, /usr/pkg/share, etc, and it isn't
necessarily in the same prefix as emacs (on my systems, it is in
/usr/pkg but emacs is in /usr/local).  The URL you want to refer
to is:

http://developer.gnome.org/doc/API/2.0/gtk/gtk-Resource-Files.html

It's nigh-impossible for a naive user to navigate from
http://www.gtk.org/ to that document.  Also, i think it satisfies
Richard's suggestion (that the document may be included on a
user's system).

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

I think it is better to list it here.

> >     + @example
> >     + widget_class "GtkWindow.GtkVBox.GtkFixed.GtkVScrollbar" style "my_sty
> le"
> >     + @end example

[...]

> It must be one line in the ~/.gtkrc-2.0 file, so I would like to avoid
> changing it.

No, it doesn't have to be on one line.  All whitespace is treated
equally in gtkrc files.  I just tested this in my .gtkrc-2.0.

--  
Eric Gillespie <*> epg@pretzelnet.org

Build a fire for a man, and he'll be warm for a day.  Set a man on
fire, and he'll be warm for the rest of his life. -Terry Pratchett

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2002-12-31  3:17 Gtk patch version 3, part 1 Jan D.
  2003-01-01 16:46 ` Richard Stallman
@ 2003-01-02  5:52 ` Eli Zaretskii
  2003-01-02  8:05   ` Jan D.
  1 sibling, 1 reply; 68+ messages in thread
From: Eli Zaretskii @ 2003-01-02  5:52 UTC (permalink / raw)
  Cc: emacs-devel


On Tue, 31 Dec 2002, Jan D. wrote:

> There is some documentation about widget names and how to customize fonts,
> but there are some issues with GTK in this area.

I think the "Gtk*" names in this fragment (and also elsewhere):

> +   The top level widget is a GtkWindow that contains a GtkVBox.
> + The GtkVBox contains the GtkMenuBar and a GtkFixed widget.  The vertical
> + scroll bars, GtkVScrollbar, are contained in the GtkFixed widget.
> + The text you write in Emacs is drawn in the GtkFixed widget.

should have the @code markup, as they are programming symbols.

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-01 18:48   ` Jan D.
  2003-01-02  1:10     ` Eric Gillespie
@ 2003-01-02  5:56     ` Eli Zaretskii
  2003-01-02  8:07       ` Jan D.
  2003-01-03  3:32       ` Richard Stallman
  2003-01-03  3:30     ` Richard Stallman
  2003-01-03  3:32     ` Richard Stallman
  3 siblings, 2 replies; 68+ messages in thread
From: Eli Zaretskii @ 2003-01-02  5:56 UTC (permalink / raw)
  Cc: emacs-devel


On Wed, 1 Jan 2003, Jan D. wrote:

> >     + @example
> >     + widget_class "GtkWindow.GtkVBox.GtkFixed.GtkVScrollbar" style "my_style"
> >     + @end example
> > 
> > That line is very long.  It might work ok if you use @smallexample
> > instead of @example.  Please do that for all the examples in the
> > section; inconsistency looks bad.
> > 
> > Can this be written as two lines?
> 
> It must be one line in the ~/.gtkrc-2.0 file, so I would like to avoid
> changing it.

Any line in an @example that is longer than about 61 characters will 
trigger overfull hbox in TeX.  Any line in @smallexample that is longer 
than 64 characters will do the same.  So it's advisable to break long 
lines into two, even if they must be a single line in actual usage.  You 
can always say in a side note that the line must not be broken.

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-02  1:10     ` Eric Gillespie
@ 2003-01-02  7:57       ` Jan D.
  2003-01-03 19:46         ` Eric Gillespie
  0 siblings, 1 reply; 68+ messages in thread
From: Jan D. @ 2003-01-02  7:57 UTC (permalink / raw)



> "Jan D." <jan.h.d@swipnet.se> writes:
>
>> If the second, can I refer to /usr/share/gtk-doc, where the GTK
>> documentation is usually installed?
>
> That isn't really a good idea.  That directory might be anywhere:
> /usr/share, /usr/local/share, /usr/pkg/share, etc, and it isn't
> necessarily in the same prefix as emacs (on my systems, it is in
> /usr/pkg but emacs is in /usr/local).  The URL you want to refer
> to is:
>
> http://developer.gnome.org/doc/API/2.0/gtk/gtk-Resource-Files.html
>
> It's nigh-impossible for a naive user to navigate from
> http://www.gtk.org/ to that document.  Also, i think it satisfies
> Richard's suggestion (that the document may be included on a
> user's system).

Okay.

>
>> It is given by the GTK documentation, is it OK to just refer to that?
>
> I think it is better to list it here.

Won't that be a duplication of what is in that URL above?

>
>>>     + @example
>>>     + widget_class "GtkWindow.GtkVBox.GtkFixed.GtkVScrollbar" style 
>>> "my_sty
>> le"
>>>     + @end example
>
> [...]
>
>> It must be one line in the ~/.gtkrc-2.0 file, so I would like to avoid
>> changing it.
>
> No, it doesn't have to be on one line.  All whitespace is treated
> equally in gtkrc files.  I just tested this in my .gtkrc-2.0.

That is good to know!  I'll split the line then.

Thanks,
	Jan D.

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-02  5:52 ` Eli Zaretskii
@ 2003-01-02  8:05   ` Jan D.
  2003-01-02 17:24     ` Eli Zaretskii
  2003-01-03  3:31     ` Richard Stallman
  0 siblings, 2 replies; 68+ messages in thread
From: Jan D. @ 2003-01-02  8:05 UTC (permalink / raw)



torsdagen den 2 januari 2003 kl 06.52 skrev Eli Zaretskii:

>
> On Tue, 31 Dec 2002, Jan D. wrote:
>
>> There is some documentation about widget names and how to customize fonts,
>> but there are some issues with GTK in this area.
>
> I think the "Gtk*" names in this fragment (and also elsewhere):
>
>> +   The top level widget is a GtkWindow that contains a GtkVBox.
>> + The GtkVBox contains the GtkMenuBar and a GtkFixed widget.  The vertical
>> + scroll bars, GtkVScrollbar, are contained in the GtkFixed widget.
>> + The text you write in Emacs is drawn in the GtkFixed widget.
>
> should have the @code markup, as they are programming symbols.

But is @code valid in the context of a configuration file?  You won't
find these names in the Emacs code.

	Jan D.

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-02  5:56     ` Eli Zaretskii
@ 2003-01-02  8:07       ` Jan D.
  2003-01-03  3:32       ` Richard Stallman
  1 sibling, 0 replies; 68+ messages in thread
From: Jan D. @ 2003-01-02  8:07 UTC (permalink / raw)


> Any line in an @example that is longer than about 61 characters will
> trigger overfull hbox in TeX.  Any line in @smallexample that is longer
> than 64 characters will do the same.  So it's advisable to break long
> lines into two, even if they must be a single line in actual usage.  You
> can always say in a side note that the line must not be broken.

Thanks for the figures, but now that Eric Gillespie pointed out that
the line can indeed be broken, I wil do that.

	Jan D.

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-01 16:46 ` Richard Stallman
  2003-01-01 18:48   ` Jan D.
@ 2003-01-02 15:47   ` Kim F. Storm
  2003-01-03  3:31     ` Richard Stallman
  1 sibling, 1 reply; 68+ messages in thread
From: Kim F. Storm @ 2003-01-02 15:47 UTC (permalink / raw)
  Cc: jan.h.d

Richard Stallman <rms@gnu.org> writes:

>   See documents at
> + @uref{http://www.gtk.org/} for that.
> 
> 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.

Richard,
Could you please clarify the second part of this statement?

I agree that simply refering to a web site isn't good, but IMO it
should be perfectly ok to refer to a specific document on the web
(giving its complete URL.)

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-02  8:05   ` Jan D.
@ 2003-01-02 17:24     ` Eli Zaretskii
  2003-01-03  3:31     ` Richard Stallman
  1 sibling, 0 replies; 68+ messages in thread
From: Eli Zaretskii @ 2003-01-02 17:24 UTC (permalink / raw)
  Cc: emacs-devel

> Date: Thu, 2 Jan 2003 09:05:51 +0100
> From: "Jan D." <jan.h.d@swipnet.se>
> >
> >> +   The top level widget is a GtkWindow that contains a GtkVBox.
> >> + The GtkVBox contains the GtkMenuBar and a GtkFixed widget.  The vertical
> >> + scroll bars, GtkVScrollbar, are contained in the GtkFixed widget.
> >> + The text you write in Emacs is drawn in the GtkFixed widget.
> >
> > should have the @code markup, as they are programming symbols.
> 
> But is @code valid in the context of a configuration file?

Yes.  It is customary to use @code even for menu items, just to make
them stand out in print.

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-01 18:48   ` Jan D.
  2003-01-02  1:10     ` Eric Gillespie
  2003-01-02  5:56     ` Eli Zaretskii
@ 2003-01-03  3:30     ` Richard Stallman
  2003-01-03 12:39       ` Alfred M. Szmidt
  2003-01-03 22:42       ` Robert J. Chassell
  2003-01-03  3:32     ` Richard Stallman
  3 siblings, 2 replies; 68+ messages in thread
From: Richard Stallman @ 2003-01-03  3:30 UTC (permalink / raw)
  Cc: emacs-devel

    > 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!

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-02  8:05   ` Jan D.
  2003-01-02 17:24     ` Eli Zaretskii
@ 2003-01-03  3:31     ` Richard Stallman
  1 sibling, 0 replies; 68+ messages in thread
From: Richard Stallman @ 2003-01-03  3:31 UTC (permalink / raw)
  Cc: emacs-devel

    >> + scroll bars, GtkVScrollbar, are contained in the GtkFixed widget.
    >> + The text you write in Emacs is drawn in the GtkFixed widget.
    >
    > should have the @code markup, as they are programming symbols.

    But is @code valid in the context of a configuration file?

@code is for any symbol name or command name that would appear in any
kind of code.  It is not specifically for Emacs Lisp.

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-02 15:47   ` Kim F. Storm
@ 2003-01-03  3:31     ` Richard Stallman
  2003-01-03 19:50       ` Eric Gillespie
  0 siblings, 1 reply; 68+ messages in thread
From: Richard Stallman @ 2003-01-03  3:31 UTC (permalink / raw)
  Cc: jan.h.d

    I agree that simply refering to a web site isn't good, but IMO it
    should be perfectly ok to refer to a specific document on the web
    (giving its complete URL.)

Whether the URL is to the precise page or the front page isn't the
issue.  Neither one is the right thing to do here.  Either way, the
reference is to a location not on the user's own machine.

We should always refer to a documentation file that is (or
could/should be) on the user's *own machine*.  

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-02  5:56     ` Eli Zaretskii
  2003-01-02  8:07       ` Jan D.
@ 2003-01-03  3:32       ` Richard Stallman
  1 sibling, 0 replies; 68+ messages in thread
From: Richard Stallman @ 2003-01-03  3:32 UTC (permalink / raw)
  Cc: jan.h.d

    Any line in an @example that is longer than about 61 characters will 
    trigger overfull hbox in TeX.  Any line in @smallexample that is longer 
    than 64 characters will do the same.

The font used in @smallexample is considerably smaller than the one
for @example--I am sure the difference in capacity is more than just 3
characters.

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-01 18:48   ` Jan D.
                       ` (2 preceding siblings ...)
  2003-01-03  3:30     ` Richard Stallman
@ 2003-01-03  3:32     ` Richard Stallman
  3 siblings, 0 replies; 68+ messages in thread
From: Richard Stallman @ 2003-01-03  3:32 UTC (permalink / raw)
  Cc: emacs-devel

    Okay, I just copied the layout from these index entries at the top of the
    file:
    @cindex X resources, @file{~/.Xdefaults} file
    @cindex X resources, @file{~/.Xresources} file

I will fix those too.
Thanks.

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-03  3:30     ` Richard Stallman
@ 2003-01-03 12:39       ` Alfred M. Szmidt
  2003-01-04  4:20         ` Richard Stallman
  2003-01-03 22:42       ` Robert J. Chassell
  1 sibling, 1 reply; 68+ messages in thread
From: Alfred M. Szmidt @ 2003-01-03 12:39 UTC (permalink / raw)
  Cc: jan.h.d

       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?

Very outdated info pages exist.  GTK uses (from what I gather) HTML
files that get generated from SGML files.

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-02  7:57       ` Jan D.
@ 2003-01-03 19:46         ` Eric Gillespie
  0 siblings, 0 replies; 68+ messages in thread
From: Eric Gillespie @ 2003-01-03 19:46 UTC (permalink / raw)


"Jan D." <jan.h.d@swipnet.se> writes:

> Won't that be a duplication of what is in that URL above?

Not exactly.  While the raw information would be the same, you
won't find the list of which emacs elements to customize with X
resources and which to customize with gtkrc on gtk.org.
Re-formulating the information to give the emacs user exactly
what she means would be a valuable form of duplication.  I don't
think the text you currently have in this part of the manual is
far off from what is needed; it just needs to be expanded a bit.

--  
Eric Gillespie <*> epg@pretzelnet.org

Build a fire for a man, and he'll be warm for a day.  Set a man on
fire, and he'll be warm for the rest of his life. -Terry Pratchett

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-03  3:31     ` Richard Stallman
@ 2003-01-03 19:50       ` Eric Gillespie
       [not found]         ` <E18Ufn2-0003pp-00@fencepost.gnu.org>
  0 siblings, 1 reply; 68+ messages in thread
From: Eric Gillespie @ 2003-01-03 19:50 UTC (permalink / raw)


Richard Stallman <rms@gnu.org> writes:

> We should always refer to a documentation file that is (or
> could/should be) on the user's *own machine*.

That isn't really feasible in this case.  There is no standard
location where this document would be installed.  Worse, the
document we are describing isn't even end-user documentation.
Such beast does not yet exist :(.

--  
Eric Gillespie <*> epg@pretzelnet.org

Build a fire for a man, and he'll be warm for a day.  Set a man on
fire, and he'll be warm for the rest of his life. -Terry Pratchett

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-03  3:30     ` Richard Stallman
  2003-01-03 12:39       ` Alfred M. Szmidt
@ 2003-01-03 22:42       ` Robert J. Chassell
  2003-01-04  0:48         ` Kim F. Storm
  2003-01-04 18:26         ` Eric Gillespie
  1 sibling, 2 replies; 68+ messages in thread
From: Robert J. Chassell @ 2003-01-03 22:42 UTC (permalink / raw)


       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).

Yes.  If it is not on your machine, you may not be able to access it:

 * The site may be down, as I find happens with the places I reference.

 * Your Internet service provider may have suffered a hardware
   failure, as mine did on 31 Dec 2002.

 * Getting something on the net may be inconvenient or expensive.  I
   was just talking to one of my my brothers-in-law: for him to get
   an update is expensive.  It takes time to download an update.
   

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

The /usr/share/doc/ documents are so much less convenient than Texinfo
documents.  For one, the Texinfo documents go into Info, which is
still, after 15 years, the single most efficient of the online
documentation formats (since you can navigate using regexps).  For
two, Texinfo documents go into HTML.  For three, Texinfo documents can
be typeset and printed, from DVI, PS, or PDF formatted files.

/usr/share/doc/ documents tend to be either text or HTML, both of
which have been superceded by better formats.  (HTML was superceded by
a format developed before CERN started using it.  Of course, the
people at CERN never thought that their format would be used for more
than the equivalent of 1980s Apple Hypertext Cards, which is why they
did not insist on an efficient language.  It never occurred to the
managers at CERN that anyone would want to reference another page of
the same document; all documents would be one page long!)

   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.

Yes: please remember, when people look up a reference, you have to
think of them as being in `encyclopedia mode'.  They want the
information.  A link to another document on their machine is likely to
be perceived as a hinderance.  (A link to a document that they cannot
get to, because it is on another machine and they are off the
Internet, is likely to be perceived as a failure of the
documentation.)

-- 
    Robert J. Chassell                         Rattlesnake Enterprises
    http://www.rattlesnake.com                  GnuPG Key ID: 004B4AC8
    http://www.teak.cc                             bob@rattlesnake.com

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-03 22:42       ` Robert J. Chassell
@ 2003-01-04  0:48         ` Kim F. Storm
  2003-01-04  2:55           ` Luc Teirlinck
                             ` (3 more replies)
  2003-01-04 18:26         ` Eric Gillespie
  1 sibling, 4 replies; 68+ messages in thread
From: Kim F. Storm @ 2003-01-04  0:48 UTC (permalink / raw)
  Cc: emacs-devel

"Robert J. Chassell" <bob@rattlesnake.com> writes:

>        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).
> 
> Yes.  If it is not on your machine, you may not be able to access it:

Well if it is not on your machine -- you definitely cannot access it 
without accessing the Internet.

I don't argue that if there is a document on your -- and everyone
else's -- local machines that can be referenced, we should do that.

But I really don't see how we can assume that a specific file is
always available.  Some systems even come without man-pages ...

If we cannot rely on having a local file, we have two options:

- include the necessary documentation in the emacs distribution [meaning
  that we may have to (re)write that documentation ourselves], or

- reference an existing document (in whatever format it is available in)
  with the appropriate URL.

The first option still costs you something (when downloading and
storing emacs on your local machine), and it may be time-consuming to
write the necessary documentation.

The second option has the potential risks of non-availability that you
mention, and it *may* also costs a few cents to access the URL (although
flat-rate Internet access is getting pretty common in many places).

IMHO, referencing a URL is at least as good as referencing a local
file which we cannot be sure is available (or don't know where it's
located even if it exists)...

Having said that, I agree that Texinfo is a superior format for
online docs!

> Yes: please remember, when people look up a reference, you have to
> think of them as being in `encyclopedia mode'.  They want the
> information.  A link to another document on their machine is likely to
> be perceived as a hinderance.  

If it is a link which they can click on with mouse-2 and have it
opened in an emacs buffer, in a browser or in some other viewer, I
think most users will be happy with that.

>                                (A link to a document that they cannot
> get to, because it is on another machine and they are off the
> Internet, is likely to be perceived as a failure of the
> documentation.)

I disagree!  Regarding a user's inability to access the Internet as a
documentation failure seems quite far-fetched to me.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-04  0:48         ` Kim F. Storm
@ 2003-01-04  2:55           ` Luc Teirlinck
  2003-01-04  3:58             ` Luc Teirlinck
                               ` (3 more replies)
  2003-01-04  7:20           ` Texinfo/info: scrolling images (Re: Gtk patch version 3, part 1) Karl Eichwalder
                             ` (2 subsequent siblings)
  3 siblings, 4 replies; 68+ messages in thread
From: Luc Teirlinck @ 2003-01-04  2:55 UTC (permalink / raw)
  Cc: emacs-devel

Kim Storm wrote:

   - include the necessary documentation in the emacs distribution [meaning
     that we may have to (re)write that documentation ourselves], or

I do not understand.  Why would it need to be rewritten?  Is GTK and
its documentation free software?  If we want it in the superior
Texinfo format, of course, but what if we are (reluctantly) willing to
use the html files as they are?  That is all the URL would provide
anyway.  The document does not seem to be that huge.  I took a look at
it.  Over a slow internet connection.  Plenty of "10k read stalled".
Forever.  Interrupt transfer. Try again...  More of the same.  No fun.
Note also that with an URL, you first have to remember to connect to
the internet before you can double-click with mouse 2.  Depending on
the situation, getting connected can take a non-trivial amount of
time.

I actually have the documents in /usr/share/doc.  If I did not and
needed them, I guess that in the worst case I could use wget to get
things on my own machine.  Do the GTK people not provide more
convenient ways than using wget?  I could not find any on the site.

Anyway, why not just include it in the Emacs distribution?
Alternative solutions might be searching for the documentation in the
user's file system or having the location provided by the user in some
Emacs variable.

Any of this as an intermediate solution until somebody finds the time
to write a suitable Texinfo documentation.

Sincerely,

Luc.

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-04  2:55           ` Luc Teirlinck
@ 2003-01-04  3:58             ` Luc Teirlinck
  2003-01-04  4:17               ` Luc Teirlinck
  2003-01-04 13:11             ` Jan D.
                               ` (2 subsequent siblings)
  3 siblings, 1 reply; 68+ messages in thread
From: Luc Teirlinck @ 2003-01-04  3:58 UTC (permalink / raw)
  Cc: storm

>From my previous message:

   Do the GTK people not provide more
   convenient ways than using wget?  I could not find any on the site.

That is because I did not look very well:

A packaged verion of this tutorial is available from
ftp://ftp.gtk.org/pub/gtk/tutorial which contains the tutorial in
various different formats. This package is primary for those people
wanting to have the tutorial available for offline reference and for
printing.

Sincerely,

Luc.

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-04  3:58             ` Luc Teirlinck
@ 2003-01-04  4:17               ` Luc Teirlinck
  2003-01-04 13:30                 ` Jan D.
  0 siblings, 1 reply; 68+ messages in thread
From: Luc Teirlinck @ 2003-01-04  4:17 UTC (permalink / raw)
  Cc: storm

>From my previous message:

   A packaged verion of this tutorial is available from
   ftp://ftp.gtk.org/pub/gtk/tutorial which contains the tutorial in
   various different formats. This package is primary for those people
   wanting to have the tutorial available for offline reference and for
   printing.

I believe I failed to make clear that this is quoted literally from
the GTK site and not my own remarks.

Sincerely,

Luc.

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-03 12:39       ` Alfred M. Szmidt
@ 2003-01-04  4:20         ` Richard Stallman
  2003-01-04 13:40           ` Alfred M. Szmidt
  0 siblings, 1 reply; 68+ messages in thread
From: Richard Stallman @ 2003-01-04  4:20 UTC (permalink / raw)
  Cc: jan.h.d

    Very outdated info pages exist.  GTK uses (from what I gather) HTML
    files that get generated from SGML files.

What exactly is the format?  Is it Docbook?

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Texinfo/info: scrolling images (Re: Gtk patch version 3, part 1)
  2003-01-04  0:48         ` Kim F. Storm
  2003-01-04  2:55           ` Luc Teirlinck
@ 2003-01-04  7:20           ` Karl Eichwalder
  2003-01-11 19:50             ` Stefan Monnier
  2003-01-04 23:44           ` Gtk patch version 3, part 1 Richard Stallman
  2003-01-05 13:23           ` Robert J. Chassell
  3 siblings, 1 reply; 68+ messages in thread
From: Karl Eichwalder @ 2003-01-04  7:20 UTC (permalink / raw)
  Cc: emacs-devel

storm@cua.dk (Kim F. Storm) writes:

> Having said that, I agree that Texinfo is a superior format for
> online docs!

As usual, it depends ;) As it stands, it's somehow related to monospaced
fonts (info viewer like Emacs must obey hardcoded line breaks) and, more
important, the info file format still lack image support.  Aside: Emacs
cannot scroll incline images properly--or did something change in CVS
head the last 2 month in the area? (Cf. etc/TODO.)

> If it is a link which they can click on with mouse-2 and have it
> opened in an emacs buffer, in a browser or in some other viewer, I
> think most users will be happy with that.

BTW, you'd better use @uref instead of @url.  Further, why not
providing both locations at the same time, a local and a remote
reference?

-- 
ke@suse.de (work) / keichwa@gmx.net (home):              |
http://www.gnu.franken.de/ke/                            |      ,__o
Free Translation Project:                                |    _-\_<,
http://www.iro.umontreal.ca/contrib/po/HTML/             |   (*)/'(*)

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-04  2:55           ` Luc Teirlinck
  2003-01-04  3:58             ` Luc Teirlinck
@ 2003-01-04 13:11             ` Jan D.
  2003-01-04 14:55               ` Alfred M. Szmidt
  2003-01-05 18:33               ` Richard Stallman
  2003-01-04 15:51             ` Alex Schroeder
  2003-01-04 23:44             ` Richard Stallman
  3 siblings, 2 replies; 68+ messages in thread
From: Jan D. @ 2003-01-04 13:11 UTC (permalink / raw)


> 
> I do not understand.  Why would it need to be rewritten?  Is GTK and
> its documentation free software?  If we want it in the superior
> Texinfo format, of course, but what if we are (reluctantly) willing to
> use the html files as they are?  That is all the URL would provide
> anyway.  The document does not seem to be that huge.  I took a look at
> it.  Over a slow internet connection.  Plenty of "10k read stalled".
> Forever.  Interrupt transfer. Try again...  More of the same.  No fun.

That is what I mean, rewritten to texinfo.  I think this is a must
for Emacs documentation.

> Anyway, why not just include it in the Emacs distribution?

There is the problem of keeping it up to date.  I know the format
for GTK resources changed a bit from 1.2 to 2.0 (added font_name),
I haven't looked if 2.2 has any changes. 
Who knows what 2.4 will look like?

	Jan D.

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-04  4:17               ` Luc Teirlinck
@ 2003-01-04 13:30                 ` Jan D.
  2003-01-04 16:16                   ` Luc Teirlinck
  0 siblings, 1 reply; 68+ messages in thread
From: Jan D. @ 2003-01-04 13:30 UTC (permalink / raw)


> 
>    A packaged verion of this tutorial is available from
>    ftp://ftp.gtk.org/pub/gtk/tutorial which contains the tutorial in
>    various different formats. This package is primary for those people
>    wanting to have the tutorial available for offline reference and for
>    printing.
> 
> I believe I failed to make clear that this is quoted literally from
> the GTK site and not my own remarks.

I think the API reference is a better starting point for documentation
in Emacs, as the tutorial leaves out some important things, like
base, engine, fontset, font_name, include, etc.

	Jan D.

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-04  4:20         ` Richard Stallman
@ 2003-01-04 13:40           ` Alfred M. Szmidt
  2003-01-04 16:04             ` Alex Schroeder
                               ` (2 more replies)
  0 siblings, 3 replies; 68+ messages in thread
From: Alfred M. Szmidt @ 2003-01-04 13:40 UTC (permalink / raw)
  Cc: jan.h.d

       Very outdated info pages exist.  GTK uses (from what I gather) HTML
       files that get generated from SGML files.

   What exactly is the format?  Is it Docbook?

No, it is not Docbook, it uses `linuxdoc' (no idea what that is).  To
quote the first page I found about this format:

 "Linuxdoc-SGML is a text-formatting package based on SGML (Standard
 Generalized Markup Language), which allows you to produce LaTeX,
 groff, HTML, and plain ASCII (via groff) documents from a single
 source. Texinfo support is forthcoming; due to the flexible nature of
 SGML many other target formats are possible."

 "This system is tailored for writing technical software
 documentation, an example of which are the Linux HOWTO
 documents. However, there is nothing Linux-specific about this
 package; it can be used for many other types of documentation on many
 other systems. The name is simply derived from its use for the Linux
 HOWTO documents. It should be useful for all kinds of printed and
 online documentation."

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-04 13:11             ` Jan D.
@ 2003-01-04 14:55               ` Alfred M. Szmidt
  2003-01-05 18:33               ` Richard Stallman
  1 sibling, 0 replies; 68+ messages in thread
From: Alfred M. Szmidt @ 2003-01-04 14:55 UTC (permalink / raw)
  Cc: emacs-devel

   That is what I mean, rewritten to texinfo.  I think this is a must
   for Emacs documentation.

I don't really think there is a need to rewrite it, if you can convert
it to texinfo.  And then the info pages should be distributed by
default with the project.

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-04  2:55           ` Luc Teirlinck
  2003-01-04  3:58             ` Luc Teirlinck
  2003-01-04 13:11             ` Jan D.
@ 2003-01-04 15:51             ` Alex Schroeder
  2003-01-04 23:44             ` Richard Stallman
  3 siblings, 0 replies; 68+ messages in thread
From: Alex Schroeder @ 2003-01-04 15:51 UTC (permalink / raw)


Luc Teirlinck <teirllm@dms.auburn.edu> writes:

> I actually have the documents in /usr/share/doc.  If I did not and
> needed them, I guess that in the worst case I could use wget to get
> things on my own machine.  Do the GTK people not provide more
> convenient ways than using wget?  I could not find any on the site.

Is the documentation not in DocBook format, so that we can generate
texinfo files from it (eventhough they were not of the greatest
quality last time I looked).

Alex.

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-04 13:40           ` Alfred M. Szmidt
@ 2003-01-04 16:04             ` Alex Schroeder
  2003-01-04 17:43             ` Raja R Harinath
  2003-01-04 18:30             ` Eric Gillespie
  2 siblings, 0 replies; 68+ messages in thread
From: Alex Schroeder @ 2003-01-04 16:04 UTC (permalink / raw)


"Alfred M. Szmidt" <ams@kemisten.nu> writes:

> No, it is not Docbook, it uses `linuxdoc' (no idea what that is).  To
> quote the first page I found about this format:
>
>  "Linuxdoc-SGML is a text-formatting package based on SGML (Standard
>  Generalized Markup Language), which allows you to produce LaTeX,
>  groff, HTML, and plain ASCII (via groff) documents from a single
>  source. Texinfo support is forthcoming; due to the flexible nature of
>  SGML many other target formats are possible."

I thought this was just the old name for docbook.  Searching for
"linuxdoc docbook" on Google found many messages that explain how to
convert one into the other, so eventhough they are not the same, they
can be converted into each other.

Alex.

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-04 13:30                 ` Jan D.
@ 2003-01-04 16:16                   ` Luc Teirlinck
  2003-01-04 16:39                     ` Jan D.
  2003-01-05 18:33                     ` Richard Stallman
  0 siblings, 2 replies; 68+ messages in thread
From: Luc Teirlinck @ 2003-01-04 16:16 UTC (permalink / raw)
  Cc: emacs-devel

Jan D. wrote:
   
   I think the API reference is a better starting point for documentation
   in Emacs, as the tutorial leaves out some important things, like
   base, engine, fontset, font_name, include, etc.

Sorry, I misunderstood which document you were referring to.  I agree
that manuals are better for documentation than tutorials, which tend
to be incomplete.  I do not seem to have the API reference in
/usr/share/doc, only the tutorial, which is why I assumed that was what
you were referring to.

Anyway, if the document can be automatically converted to Texinfo, as
Alfred and Alex suggest and if GTK were willing to distribute the
Texinfo form with the project, then that completely solves the
problem anyway.

Sincerely,

Luc.

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-04 16:16                   ` Luc Teirlinck
@ 2003-01-04 16:39                     ` Jan D.
  2003-01-04 18:00                       ` Luc Teirlinck
  2003-01-05 18:33                     ` Richard Stallman
  1 sibling, 1 reply; 68+ messages in thread
From: Jan D. @ 2003-01-04 16:39 UTC (permalink / raw)


Luc Teirlinck wrote:
> Jan D. wrote:
>    
>    I think the API reference is a better starting point for documentation
>    in Emacs, as the tutorial leaves out some important things, like
>    base, engine, fontset, font_name, include, etc.
> 
> Sorry, I misunderstood which document you were referring to.  I agree
> that manuals are better for documentation than tutorials, which tend
> to be incomplete.  I do not seem to have the API reference in
> /usr/share/doc, only the tutorial, which is why I assumed that was what
> you were referring to.

When I installed GTK in prefix, the API documents got installed in 
prefix/share/gtk-doc, not prefix/share/doc.  I would have looked in 
prefix/share/doc first also.


	Jan D.

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-04 13:40           ` Alfred M. Szmidt
  2003-01-04 16:04             ` Alex Schroeder
@ 2003-01-04 17:43             ` Raja R Harinath
  2003-01-04 18:30             ` Eric Gillespie
  2 siblings, 0 replies; 68+ messages in thread
From: Raja R Harinath @ 2003-01-04 17:43 UTC (permalink / raw)


Hi,

"Alfred M. Szmidt" <ams@kemisten.nu> writes:

>        Very outdated info pages exist.  GTK uses (from what I gather) HTML
>        files that get generated from SGML files.
>
>    What exactly is the format?  Is it Docbook?
>
> No, it is not Docbook, it uses `linuxdoc' (no idea what that is).  To
> quote the first page I found about this format:

Are you sure?  I have a CVS version of GTK+ check out, and 

  head gtk+/docs/reference/gdk/gdk-docs.sgml

gives:

   <?xml version="1.0"?>
   <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                  "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
   <!ENTITY gdk-General SYSTEM "xml/general.xml">
   <!ENTITY gdk-Bitmaps-and-Pixmaps SYSTEM "xml/pixmaps.xml">
   <!ENTITY gdk-Images SYSTEM "xml/images.xml">
   <!ENTITY gdk-GdkRGB SYSTEM "xml/rgb.xml">
   <!ENTITY gdk-Pixbufs SYSTEM "xml/pixbufs.xml">
   <!ENTITY gdk-Colormaps-and-Colors SYSTEM "xml/colors.xml">
   <!ENTITY gdk-Fonts SYSTEM "xml/fonts.xml">

Anything that uses 'gtk-doc' uses DocBook.

- Hari
-- 
Raja R Harinath ------------------------------ harinath@cs.umn.edu

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-04 16:39                     ` Jan D.
@ 2003-01-04 18:00                       ` Luc Teirlinck
  2003-01-04 19:46                         ` Luc Teirlinck
  0 siblings, 1 reply; 68+ messages in thread
From: Luc Teirlinck @ 2003-01-04 18:00 UTC (permalink / raw)
  Cc: emacs-devel

Jan D. wrote:
   
   When I installed GTK in prefix, the API documents got installed in 
   prefix/share/gtk-doc, not prefix/share/doc.  I would have looked in 
   prefix/share/doc first also.

On my system (Red Hat 7.2) I not only do not have a
usr/share/gtk-doc (I have a usr/share/gtkhtml, but that seems to be
something completely different), find / -name '*gtk-doc' fails to find
anything.  I gather from what you say, however that it "should" be
there and that if I upgraded to the latest GTK version it would be
there.

Anyway, if we can get Texinfo files, all of this seems irrelevant.

Sincerely,

Luc.

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-03 22:42       ` Robert J. Chassell
  2003-01-04  0:48         ` Kim F. Storm
@ 2003-01-04 18:26         ` Eric Gillespie
  1 sibling, 0 replies; 68+ messages in thread
From: Eric Gillespie @ 2003-01-04 18:26 UTC (permalink / raw)


"Robert J. Chassell" <bob@rattlesnake.com> writes:

> Yes.  If it is not on your machine, you may not be able to
> access it:

[...]

That may be so, but the fact remains that something is better
than nothing.  We can duplicate all the end-user information from
this document (bad idea), or we can make the cross-reference to
the URL with a note saying that this document mayb be available
on your system in $prefix/share/gtk-doc/html/gtk where $prefix is
the prefix gtk was installed to.

--  
Eric Gillespie <*> epg@pretzelnet.org

Build a fire for a man, and he'll be warm for a day.  Set a man on
fire, and he'll be warm for the rest of his life. -Terry Pratchett

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-04 13:40           ` Alfred M. Szmidt
  2003-01-04 16:04             ` Alex Schroeder
  2003-01-04 17:43             ` Raja R Harinath
@ 2003-01-04 18:30             ` Eric Gillespie
  2003-01-04 19:25               ` Alfred M. Szmidt
  2 siblings, 1 reply; 68+ messages in thread
From: Eric Gillespie @ 2003-01-04 18:30 UTC (permalink / raw)


"Alfred M. Szmidt" <ams@kemisten.nu> writes:

> No, it is not Docbook, it uses `linuxdoc' (no idea what that is).  To
> quote the first page I found about this format:

This is not true.  Perhaps older versions used linuxdoc (gtk is
notoriously bad for leaving old documentation lying around where
people can find it), but the GNOME and GTK projects have
standardized on docbook.

>  "Linuxdoc-SGML is a text-formatting package based on SGML (Standard

Furthermore GTK and GNOME use XML, not SGML.

--  
Eric Gillespie <*> epg@pretzelnet.org

Build a fire for a man, and he'll be warm for a day.  Set a man on
fire, and he'll be warm for the rest of his life. -Terry Pratchett

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
       [not found]         ` <E18Ufn2-0003pp-00@fencepost.gnu.org>
@ 2003-01-04 18:34           ` Eric Gillespie
  2003-01-05 18:33             ` Richard Stallman
  0 siblings, 1 reply; 68+ messages in thread
From: Eric Gillespie @ 2003-01-04 18:34 UTC (permalink / raw)
  Cc: emacs-devel

[assuming this was supposed to go to the list]

Richard Stallman <rms@gnu.org> writes:

>     That isn't really feasible in this case.  There is no standard
>     location where this document would be installed.
> 
> That seems like quite a problem.

It is a problem, but only a minor one.

> 						      Worse, the
>     document we are describing isn't even end-user documentation.
>     Such beast does not yet exist :(.
> 
> Are you saying that this particular end-user documentation has not yet
> been written for GTK?

What i am saying is that there is *no* end user documentation
for gtk.  I believe all the raw information is available in the
API docs to which we have been referring in this thread, but no
one has yet made the effort to extract the information relevant
to end users and form it into useful end-user documentation.

That would be a valuable project for someone to take on.  Just
make sure this document is installed on the system so emacs can
refer to it :).

--  
Eric Gillespie <*> epg@pretzelnet.org

Build a fire for a man, and he'll be warm for a day.  Set a man on
fire, and he'll be warm for the rest of his life. -Terry Pratchett

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-04 18:30             ` Eric Gillespie
@ 2003-01-04 19:25               ` Alfred M. Szmidt
  0 siblings, 0 replies; 68+ messages in thread
From: Alfred M. Szmidt @ 2003-01-04 19:25 UTC (permalink / raw)
  Cc: emacs-devel

   > No, it is not Docbook, it uses `linuxdoc' (no idea what that is).
   > To quote the first page I found about this format:

   This is not true.  Perhaps older versions used linuxdoc (gtk is
   notoriously bad for leaving old documentation lying around where
   people can find it), but the GNOME and GTK projects have
   standardized on docbook.

Then I had to be looking at some old copy.

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-04 18:00                       ` Luc Teirlinck
@ 2003-01-04 19:46                         ` Luc Teirlinck
  2003-01-04 21:02                           ` Eric Gillespie
  0 siblings, 1 reply; 68+ messages in thread
From: Luc Teirlinck @ 2003-01-04 19:46 UTC (permalink / raw)
  Cc: jan.h.d

>From my previous message:

   On my system (Red Hat 7.2) I not only do not have a
   usr/share/gtk-doc (I have a usr/share/gtkhtml, but that seems to be
   something completely different), find / -name '*gtk-doc' fails to find
   anything.

Actually, I take this partially back.  I have access to two computers
with a Red Hat 7.2 system on it.  The one that has no
/usr/share/gtk-doc is one that came pre-installed with the computer I
purchased.  I installed Red Hat 7.2 myself on the other.  The Red Hat
I installed myself does have /usr/share/gtk-doc.

Sincerely,

Luc.

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-04 19:46                         ` Luc Teirlinck
@ 2003-01-04 21:02                           ` Eric Gillespie
  2003-01-04 21:55                             ` Luc Teirlinck
  0 siblings, 1 reply; 68+ messages in thread
From: Eric Gillespie @ 2003-01-04 21:02 UTC (permalink / raw)


Luc Teirlinck <teirllm@dms.auburn.edu> writes:

> >From my previous message:
> 
>    On my system (Red Hat 7.2) I not only do not have a
>    usr/share/gtk-doc (I have a usr/share/gtkhtml, but that seems to be
>    something completely different), find / -name '*gtk-doc' fails to find
>    anything.
> 
> Actually, I take this partially back.  I have access to two computers
> with a Red Hat 7.2 system on it.  The one that has no
> /usr/share/gtk-doc is one that came pre-installed with the computer I
> purchased.  I installed Red Hat 7.2 myself on the other.  The Red Hat
> I installed myself does have /usr/share/gtk-doc.

It's funny that today, as we're talking about this, i see that
NetBSD has changed gtk and related packages to install the
documentation in share/doc/html/$package rather than
share/gtk-doc/html/$package.  This only reinforces the point that
the emacs manual cannot really rely on this document's location
even if it is installed on the system.

--  
Eric Gillespie <*> epg@pretzelnet.org

Build a fire for a man, and he'll be warm for a day.  Set a man on
fire, and he'll be warm for the rest of his life. -Terry Pratchett

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-04 21:02                           ` Eric Gillespie
@ 2003-01-04 21:55                             ` Luc Teirlinck
  2003-01-04 22:54                               ` Eric Gillespie
  0 siblings, 1 reply; 68+ messages in thread
From: Luc Teirlinck @ 2003-01-04 21:55 UTC (permalink / raw)
  Cc: emacs-devel

Eric Gillespie wrote:

   It's funny that today, as we're talking about this, i see that
   NetBSD has changed gtk and related packages to install the
   documentation in share/doc/html/$package rather than
   share/gtk-doc/html/$package.  This only reinforces the point that
   the emacs manual cannot really rely on this document's location
   even if it is installed on the system.

But would that problem not go away, if the documentation were
converted to Texinfo format, which can be done automatically, and if
GTK would install those in one of the standard places that info looks
at?

Sincerely,

Luc.

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-04 21:55                             ` Luc Teirlinck
@ 2003-01-04 22:54                               ` Eric Gillespie
  0 siblings, 0 replies; 68+ messages in thread
From: Eric Gillespie @ 2003-01-04 22:54 UTC (permalink / raw)


Luc Teirlinck <teirllm@dms.auburn.edu> writes:

> But would that problem not go away, if the documentation were
> converted to Texinfo format, which can be done automatically,
> and if GTK would install those in one of the standard places
> that info looks at?

It would.  Better still would be to write end-user documentation
and convert that into Texinfo.

--  
Eric Gillespie <*> epg@pretzelnet.org

Build a fire for a man, and he'll be warm for a day.  Set a man on
fire, and he'll be warm for the rest of his life. -Terry Pratchett

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-04  0:48         ` Kim F. Storm
  2003-01-04  2:55           ` Luc Teirlinck
  2003-01-04  7:20           ` Texinfo/info: scrolling images (Re: Gtk patch version 3, part 1) Karl Eichwalder
@ 2003-01-04 23:44           ` Richard Stallman
  2003-01-05 13:23           ` Robert J. Chassell
  3 siblings, 0 replies; 68+ messages in thread
From: Richard Stallman @ 2003-01-04 23:44 UTC (permalink / raw)
  Cc: emacs-devel

    But I really don't see how we can assume that a specific file is
    always available.  Some systems even come without man-pages ...

That is not a real issue.  Documentation files can refer to other
documentation files; whether any of these files is installed on the
machine is the user's own issue.

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-04  2:55           ` Luc Teirlinck
                               ` (2 preceding siblings ...)
  2003-01-04 15:51             ` Alex Schroeder
@ 2003-01-04 23:44             ` Richard Stallman
  2003-01-06  0:17               ` Eric Gillespie
  3 siblings, 1 reply; 68+ messages in thread
From: Richard Stallman @ 2003-01-04 23:44 UTC (permalink / raw)
  Cc: storm

People seem to be arguing about a question that isn't real.

When information is directly relevant to the topic, a cross reference
to another manual (or even another section) is inconvenient for the
user.  It is much better to duplicate a small amount of information
than to ask the user to find it elsewhere.

The Emacs Manual should tell people enough information that they can
customize Emacs.

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-04  0:48         ` Kim F. Storm
                             ` (2 preceding siblings ...)
  2003-01-04 23:44           ` Gtk patch version 3, part 1 Richard Stallman
@ 2003-01-05 13:23           ` Robert J. Chassell
  2003-01-05 16:00             ` Kim F. Storm
  3 siblings, 1 reply; 68+ messages in thread
From: Robert J. Chassell @ 2003-01-05 13:23 UTC (permalink / raw)
  Cc: emacs-devel

   > Yes.  If it is not on your machine, you may not be able to access it:

   Well if it is not on your machine -- you definitely cannot access it
   without accessing the Internet.

That is false!  I do not access over the Internet most of the material
that is not on my machine.  You must be living in a rich and different
world!  Mostly, I get software and documentation from CDs.  It would
take me over 500 hours to download the Debian CDs that I use.

We must rely on `having a local file', meaning a file that is a part
of a standard distribution, and either on a user's machine, or less
conveniently, on a CD or other inexpensive transport media.

This means that we must continue to write documentation and provide it
to the user.

    Some systems even come without man-pages ...

and some come without Info.

As a child, I enjoyed a cartoon in which the hero purchased an
inexpensive, second-hand car that drove very quietly down the steep
hill from the car dealership ....  but the car refused to go up the
next hill ...  our cartoon hero then discovered that the car lacked an
engine ....

An instance of Emacs without documentation is as broken as a car
without a motor.  The people who make distributions without man-pages
and Info are as crooked as the worst second-hand car salesmen.


   > Yes: please remember, when people look up a reference, you have to
   > think of them as being in `encyclopedia mode'.  They want the
   > information.  A link to another document on their machine is likely to
   > be perceived as a hinderance.

   If it is a link which they can click on with mouse-2 and have it
   opened in an emacs buffer, in a browser or in some other viewer, I
   think most users will be happy with that.

No, in my rather extensive experience, people are not happy with that.
After they learn about incremental search and regexps, and the
convenience of proper documentation, most people I know prefer it.

Unfortunately, many contemporary people have learned from interfaces
that were thrown out a quarter century ago by people who had
experience then.  These people have not learned by using decent
software, so they still think that computers are `better typewriters',
and that documentation should be as awkward as you find in man pages
or Web pages or in PDF documents.  That failure is a fault of the
suppliers and schools that persist on using trailing edge technology.

You harm everyone by saying that `most users will be happy with an
awkward interface' when you the truth is that `most users will be
happy with a 1960s user interface so long as they don't know that an
even better interface has been available for more than a generation'.


   > (A link to a document that they cannot
   > get to, because it is on another machine and they are off the
   > Internet, is likely to be perceived as a failure of the
   > documentation.)

   I disagree!  Regarding a user's inability to access the Internet as a
   documentation failure seems quite far-fetched to me.

Again, it appears to me that you are living in a limited world of
intelligent and well connected geeks.  In my experience, I have found
that most people do not think of documentary `help' as meaning that
they have to get off the telephone with me, plug the computer into the
telephone line, dial the connection, and then pay for the download
time on a per minute basis.  They think they should be able to run the
help function, and find out what they did wrong.

For example -- and I will not tell you who among my relatives made
this mistake less than two weeks ago -- you need to tell GNU where you
are located if you want to see which stars are visible at your current
time and location....

--
    Robert J. Chassell                         Rattlesnake Enterprises
    http://www.rattlesnake.com                  GnuPG Key ID: 004B4AC8
    http://www.teak.cc                             bob@rattlesnake.com

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-05 16:00             ` Kim F. Storm
@ 2003-01-05 15:46               ` Alfred M. Szmidt
  2003-01-05 16:38               ` Robert J. Chassell
  1 sibling, 0 replies; 68+ messages in thread
From: Alfred M. Szmidt @ 2003-01-05 15:46 UTC (permalink / raw)
  Cc: emacs-devel

   What's wrong about specifying a URL where you can access it?

The user is being forced to connect to the internet just to be able to
read the documentation, thats whats wrong.  This can be inconvinet,
expensive or just plain impossible.

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-05 13:23           ` Robert J. Chassell
@ 2003-01-05 16:00             ` Kim F. Storm
  2003-01-05 15:46               ` Alfred M. Szmidt
  2003-01-05 16:38               ` Robert J. Chassell
  0 siblings, 2 replies; 68+ messages in thread
From: Kim F. Storm @ 2003-01-05 16:00 UTC (permalink / raw)
  Cc: emacs-devel

"Robert J. Chassell" <bob@rattlesnake.com> writes:

>    > Yes.  If it is not on your machine, you may not be able to access it:
> 
>    Well if it is not on your machine -- you definitely cannot access it
>    without accessing the Internet.
> 
> That is false!  I do not access over the Internet most of the material
> that is not on my machine.  You must be living in a rich and different
> world!  Mostly, I get software and documentation from CDs.  It would
> take me over 500 hours to download the Debian CDs that I use.

The basic statement is not false!  If the document is not on your
machine, you cannot access it locally.  If I have to choose between
swapping CDs or visiting a URL, I'd choose the URL.  But if the file
you need is on a CD of yours, why didn't you install it locally in the
first place?

I'm arguing about files which ARE NOT AVAILABLE LOCALLY.

What's wrong about specifying a URL where you can access it?
As a user, you are free(!) to follow or ignore the URL.

> We must rely on `having a local file', meaning a file that is a part
> of a standard distribution, and either on a user's machine, or less
> conveniently, on a CD or other inexpensive transport media.

I fully agree that having an local, well-written info file is much
better than having to rely on a remote HTML or PDF document.

But in my experience, you cannot rely on any specific documentation to
be available locally -- unless you include that documentation as part
of your own software distribution -- and even in that case, there's no
guarantee that whoever puts your software into a distribution will
also include the docs....

> 
> This means that we must continue to write documentation and provide it
> to the user.
> 

Exactly!  The real issue is to write the necessary documentation and
include it in the emacs distribution.

Until that's done, I don't see what's wrong with supplying a URL
where you can find the  "best docs currently available" .

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-05 16:00             ` Kim F. Storm
  2003-01-05 15:46               ` Alfred M. Szmidt
@ 2003-01-05 16:38               ` Robert J. Chassell
  2003-01-06  0:33                 ` Kim F. Storm
  1 sibling, 1 reply; 68+ messages in thread
From: Robert J. Chassell @ 2003-01-05 16:38 UTC (permalink / raw)
  Cc: emacs-devel

   "Robert J. Chassell" <bob@rattlesnake.com> writes:

   >    > Yes.  If it is not on your machine, you may not be able to access it:
   > 
   >    Well if it is not on your machine -- you definitely cannot access it
   >    without accessing the Internet.
   > 
   > That is false!  I do not access over the Internet most of the material
   > that is not on my machine.  You must be living in a rich and different
   > world!  Mostly, I get software and documentation from CDs.  It would
   > take me over 500 hours to download the Debian CDs that I use.

   The basic statement is not false!  If the document is not on your
   machine, you cannot access it locally.  

That is not true!  I can and often do access documents and programs
locally that are not on my machine.  I put in a CD.  A CD is less
convenient than accessing the document on my machine, but it is local.

   ... If I have to choose between swapping CDs or visiting a URL, I'd
   choose the URL.

This means you have a fast and inexpensive Internet connection.  I
envy you.  

If I have a choice between spending a great deal of time visiting a
URL or spending one-hundreth that time downloading from a local CD, I
use the CD.

   But if the file you need is on a CD of yours, why didn't you
   install it locally in the first place?

Because I don't know that I want it -- often I don't know that the
document exists.  The only part of my Debian CD set that is on my
local machine is the table of contents.

   I'm arguing about files which ARE NOT AVAILABLE LOCALLY.

   What's wrong about specifying a URL where you can access it?
   As a user, you are free(!) to follow or ignore the URL.

Because you should plan to create documents that can be made available
locally.  If you specify a URL, a GNU distributor is not likely to put
that document on a CD or on a hard drive.  The distributor probably
does not ever know about the document.

If you create a situation in which the document fails to reach the
user, you have told the user you do not think it worth providing
resources to them.

   I fully agree that having an local, well-written info file is much
   better than having to rely on a remote HTML or PDF document.

That is the whole point.  If you make it a policy that a remote
document substitutes for a local document, then everyone loses.

This is because many of the GNU distributors and hackers have cheap,
convenient, and fast Internet access for themselves and do not have
correspondents who live in Bennington, VT, USA or in Cameroon, in
Africa, correspondents whose Internet connections are slow and
expensive.  Such distributors and hackers often have no reason to
think of the rest of us.  


   But in my experience, you cannot rely on any specific documentation to
   be available locally -- unless you include that documentation as part
   of your own software distribution -- and even in that case, there's no
   guarantee that whoever puts your software into a distribution will
   also include the docs....

That is true; but the key point is that whoever puts your software
into a distribution is much more likely to include documentation if
you provide it to them than if you do not provide it to them.

   Exactly!  The real issue is to write the necessary documentation and
   include it in the emacs distribution.

   Until that's done, I don't see what's wrong with supplying a URL
   where you can find the  "best docs currently available" .

It is very wrong supply a URL rather than the documentation to which
it points.  The reason is that supplying just the URL reduces the
motivation many people have to create local documentation.  I possess
the contents of URLs on my local machine:  often it is in an
inefficient HTML format rather than plain text or Texinfo, but it
better than none.  None is what you are actually talking about for
many people if the document is not part of a CD distribution or on a
local hard disk.

-- 
    Robert J. Chassell                         Rattlesnake Enterprises
    http://www.rattlesnake.com                  GnuPG Key ID: 004B4AC8
    http://www.teak.cc                             bob@rattlesnake.com

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-04 13:11             ` Jan D.
  2003-01-04 14:55               ` Alfred M. Szmidt
@ 2003-01-05 18:33               ` Richard Stallman
  1 sibling, 0 replies; 68+ messages in thread
From: Richard Stallman @ 2003-01-05 18:33 UTC (permalink / raw)
  Cc: emacs-devel

It's not a matter of rewriting the GTK documentation.  The point is to
write what the Emacs user specifically needs to know.  The part of the
Emacs manual that talks about customizing Xlib and the Lucid widgets
isn't the same as anything in the manuals for X or Xt.  They don't
do this job; they do their jobs.  It's the same for GTK.

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-04 16:16                   ` Luc Teirlinck
  2003-01-04 16:39                     ` Jan D.
@ 2003-01-05 18:33                     ` Richard Stallman
  1 sibling, 0 replies; 68+ messages in thread
From: Richard Stallman @ 2003-01-05 18:33 UTC (permalink / raw)
  Cc: jan.h.d

    Anyway, if the document can be automatically converted to Texinfo, as
    Alfred and Alex suggest and if GTK were willing to distribute the
    Texinfo form with the project, then that completely solves the
    problem anyway.

They don't necessarily need to distribute the Texinfo file; it is
enough if they have makefile targets to produce Info and DVI files
from their source files.

But none of that substitutes for writing the text that needs to be in
the Emacs manual.  Pointing to GTK documentation is good for telling
the user where to find more info about GTK, but the essential points
about customizing Emacs should be given in the Emacs manual, focusing
specifically on Emacs, addressed to Emacs users.

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-04 18:34           ` Eric Gillespie
@ 2003-01-05 18:33             ` Richard Stallman
  2003-01-06  0:19               ` Eric Gillespie
  0 siblings, 1 reply; 68+ messages in thread
From: Richard Stallman @ 2003-01-05 18:33 UTC (permalink / raw)
  Cc: emacs-devel

    What i am saying is that there is *no* end user documentation
    for gtk.  I believe all the raw information is available in the
    API docs to which we have been referring in this thread, but no
    one has yet made the effort to extract the information relevant
    to end users and form it into useful end-user documentation.

    That would be a valuable project for someone to take on.

I agree.  In fact, it may be hard for us to figure out what to say in
the Emacs manual without official end-user documentation to get the
information from.  I hope someone knows enough to be able to figure
out what we should say in the Emacs manual.

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-04 23:44             ` Richard Stallman
@ 2003-01-06  0:17               ` Eric Gillespie
  2003-01-06 17:13                 ` Richard Stallman
  2003-01-06 19:52                 ` Alex Schroeder
  0 siblings, 2 replies; 68+ messages in thread
From: Eric Gillespie @ 2003-01-06  0:17 UTC (permalink / raw)


Richard Stallman <rms@gnu.org> writes:

> People seem to be arguing about a question that isn't real.

The question is real.  The emacs manual needs information about
how to customize the gtk widgets, yes, but it is not the place to
document the gtkrc syntax, any more than it is the place to
document the syntax of X resources.  For this, a cross-reference
is valuable.

--  
Eric Gillespie <*> epg@pretzelnet.org

Build a fire for a man, and he'll be warm for a day.  Set a man on
fire, and he'll be warm for the rest of his life. -Terry Pratchett

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-05 18:33             ` Richard Stallman
@ 2003-01-06  0:19               ` Eric Gillespie
  0 siblings, 0 replies; 68+ messages in thread
From: Eric Gillespie @ 2003-01-06  0:19 UTC (permalink / raw)


Richard Stallman <rms@gnu.org> writes:

> I agree.  In fact, it may be hard for us to figure out what to
> say in the Emacs manual without official end-user documentation
> to get the information from.  I hope someone knows enough to be
> able to figure out what we should say in the Emacs manual.

Having real end-user documentation for gtk would be valuable,
yes.  But as i said before, the raw information is available.  So
figuring out what to say in the emacs manual is not difficult.

--  
Eric Gillespie <*> epg@pretzelnet.org

Build a fire for a man, and he'll be warm for a day.  Set a man on
fire, and he'll be warm for the rest of his life. -Terry Pratchett

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-05 16:38               ` Robert J. Chassell
@ 2003-01-06  0:33                 ` Kim F. Storm
  0 siblings, 0 replies; 68+ messages in thread
From: Kim F. Storm @ 2003-01-06  0:33 UTC (permalink / raw)
  Cc: emacs-devel

"Robert J. Chassell" <bob@rattlesnake.com> writes:

> This means you have a fast and inexpensive Internet connection.  I
> envy you.

I actually have a fairly expensive, reasonably fast Internet connection.
But it is flat-rate, so it doesn't cost me _extra_ to download a document.

I don't mind finding documentation on the Internet (I'm spoiled, I
know), but of course, I use the local documentation whenever it's
available, and if it's an info file I can read with emacs, that's my
favourite method.

In any case, I don't see any reason to continue this discussion.
Let's write some documentation instead :-)


-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-06  0:17               ` Eric Gillespie
@ 2003-01-06 17:13                 ` Richard Stallman
  2003-01-06 19:52                 ` Alex Schroeder
  1 sibling, 0 replies; 68+ messages in thread
From: Richard Stallman @ 2003-01-06 17:13 UTC (permalink / raw)
  Cc: emacs-devel

    The question is real.  The emacs manual needs information about
    how to customize the gtk widgets, yes, but it is not the place to
    document the gtkrc syntax, any more than it is the place to
    document the syntax of X resources.  For this, a cross-reference
    is valuable.

We should handle this case like the X resources case: show precisely
what to do for Emacs.  A cross-reference to the GTK doc for those who
would like more information would be useful to add.

I wrote to the GTK developers asking them to add Info targets to
their makefile.  By and by, there should be an Info file we can
reference.

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Gtk patch version 3, part 1
  2003-01-06  0:17               ` Eric Gillespie
  2003-01-06 17:13                 ` Richard Stallman
@ 2003-01-06 19:52                 ` Alex Schroeder
  1 sibling, 0 replies; 68+ messages in thread
From: Alex Schroeder @ 2003-01-06 19:52 UTC (permalink / raw)


Eric Gillespie <epg@pretzelnet.org> writes:

> The question is real.  The emacs manual needs information about
> how to customize the gtk widgets, yes, but it is not the place to
> document the gtkrc syntax, any more than it is the place to
> document the syntax of X resources.  For this, a cross-reference
> is valuable.

But this exactly what we do in the Emacs manual, and I like it!  See
the node Font Specification Options for an example.

Alex.

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Texinfo/info: scrolling images (Re: Gtk patch version 3, part 1)
  2003-01-04  7:20           ` Texinfo/info: scrolling images (Re: Gtk patch version 3, part 1) Karl Eichwalder
@ 2003-01-11 19:50             ` Stefan Monnier
  2003-01-11 21:03               ` Robert J. Chassell
  0 siblings, 1 reply; 68+ messages in thread
From: Stefan Monnier @ 2003-01-11 19:50 UTC (permalink / raw)
  Cc: Kim F. Storm

> > Having said that, I agree that Texinfo is a superior format for
> > online docs!
> 
> As usual, it depends ;) As it stands, it's somehow related to monospaced
> fonts (info viewer like Emacs must obey hardcoded line breaks) and, more
> important, the info file format still lack image support.

TeXinfo != info


	Stefan

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Texinfo/info: scrolling images (Re: Gtk patch version 3, part 1)
  2003-01-11 19:50             ` Stefan Monnier
@ 2003-01-11 21:03               ` Robert J. Chassell
  2003-01-12  5:05                 ` Karl Eichwalder
  0 siblings, 1 reply; 68+ messages in thread
From: Robert J. Chassell @ 2003-01-11 21:03 UTC (permalink / raw)


   > more important, the info file format still lack image support.

Actually, Info has enjoyed image support from its beginning -- I
remember vividly creating images for Info for the Texinfo manual.  
See File: texinfo, Node: Tree Structuring

The images are built from plain ASCII characters, of course, but they
are there.

Images, even those built from plain ASCII, are a danger.  This is
because Texinfo is designed for a wide variety of output formats, not
only for fast computers and high resolution typset printing.  Texinfo
is designed for listening.

If you drive a car, you are `situationally blind' and should not look
at images in a document, but only listen to it.  If you are
permanently blind, you may be able to feel an image, if you have the
right kind of output equipment, but more likely, you will listen to
it.  

Remember, in its `Emacspeak' variation, GNU Emacs provides a complete
auditory environment for a typical personal computer.  A normal PC
requires no additional cards or parts besides an audio card (which
most modern PCs already have).  Both the `flite' and its Emacs
interface `eflite' are in Debian (and other distributions) and provide
the requisit text-to-voice driver for Emacspeak.

People who have good vision and don't think if using their computers
in theirscars often think images are wonderful.  The use too many of
them.  And they design documents that don't hear well.

-- 
    Robert J. Chassell                         Rattlesnake Enterprises
    http://www.rattlesnake.com                  GnuPG Key ID: 004B4AC8
    http://www.teak.cc                                     bob@gnu.org

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Texinfo/info: scrolling images (Re: Gtk patch version 3, part 1)
  2003-01-11 21:03               ` Robert J. Chassell
@ 2003-01-12  5:05                 ` Karl Eichwalder
  2003-01-12 14:41                   ` Robert J. Chassell
  0 siblings, 1 reply; 68+ messages in thread
From: Karl Eichwalder @ 2003-01-12  5:05 UTC (permalink / raw)
  Cc: emacs-devel

"Robert J. Chassell" <bob@rattlesnake.com> writes:

> The images are built from plain ASCII characters, of course, but they
> are there.

That's something different.  lilypond authors want to document music
scores and at times I want to talk about graphical interfaces
(screenshots).   ASCII representations of such images are a) different
from the graphical ones and b) highly time consuming to "draw".

At other places, scrolling images is also very important: I'd like to
look at a scan and an OCRed text side by side, that's just 1 example.

> If you drive a car, you are `situationally blind' and should not look
> at images in a document, but only listen to it.

I'm not a car driver anymore ;) OTOH, please note I don't ask you to
drop a feature that helps blind users.  Enhance info in a manner that it
can hold alternative representations of the same contents (ASCII image,
audio variant, graphical image).

> People who have good vision and don't think if using their computers
> in theirscars often think images are wonderful.  The use too many of
> them.  And they design documents that don't hear well.

Yes, point taken.  I'm pretty sure it isn't that difficult to please
_all_ the emacs users.

-- 
ke@suse.de (work) / keichwa@gmx.net (home):              |
http://www.gnu.franken.de/ke/                            |      ,__o
Free Translation Project:                                |    _-\_<,
http://www.iro.umontreal.ca/contrib/po/HTML/             |   (*)/'(*)

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Texinfo/info: scrolling images (Re: Gtk patch version 3, part 1)
  2003-01-12  5:05                 ` Karl Eichwalder
@ 2003-01-12 14:41                   ` Robert J. Chassell
  2003-01-13 20:41                     ` Texinfo/info: scrolling images Karl Eichwalder
  0 siblings, 1 reply; 68+ messages in thread
From: Robert J. Chassell @ 2003-01-12 14:41 UTC (permalink / raw)



   "Robert J. Chassell" <bob@rattlesnake.com> writes:

   > The images are built from plain ASCII characters, of course, but they
   > are there.

Karl Eichwalder <keichwa@gmx.net> responds:

   That's something different.  lilypond authors want to document music
   scores and at times I want to talk about graphical interfaces
   (screenshots).   ASCII representations of such images are a) different
   from the graphical ones and b) highly time consuming to "draw".

Yes, the ASCII representations are often different.  In the case of
music, I think you would want to use the `letter' notation that (if I
remember Lilypond rightly) users type in order to input information so
that Lilypond can create the nicely typeset output that it produces.

The design question is:

    to what should you listen when you should not or cannot view the
    typeset output and do not have or should not use a haptic `feel
    pad'?

And yes, the ASCII representations are highly time consuming to
"draw".  This is a major motivation for you to use a format such as
Texinfo that requires such representations.

Without the motivation, sighted people tend to write only for sighted
readers who are not situationally blind.  This is why LaTeX is not
used as the basis for Texinfo.  We tried to make the change more than
a decade ago.  I made many experiments.  

Yes, you can write a LaTeX `deep-representation' file that produces
good Info `surface-expression' output.  But -- and this is the problem
-- often enough, people do not write such files.  Instead, they use
LaTeX' marvelous typesetting capabilities to create papers that
typeset nicely, and which are impossible for someone reading over a
slow connection or who is listening.  XML and DocBook suffer the same
failing.

   At other places, scrolling images is also very important: I'd like to
   look at a scan and an OCRed text side by side, that's just 1 example.

I agree, that is an important action.  At the same time, please
remember that the blind are major users of OCR.  Please design your
system so that you can listen to a scan and to an OCRed text, as well
as look at them.

   > If you drive a car, you are `situationally blind' and should not look
   > at images in a document, but only listen to it.

   I'm not a car driver anymore ;) 

That may be very good (I don't know your personal situation; but it
would be good for the rest of us if fewer people drove cars).
Unfortunately, many other people do drive.  Others work in factories
where they are supposed to be paying attention to their work.

   Enhance info in a manner that it can hold alternative
   representations of the same contents ...

If you really mean Texinfo, this feature has existed for more than a
decade.  What is wrong with the current feature?

If you mean to enhance the GNU Emacs Info reader to provide highly
typeset images for some viewers -- that is a good idea so long as
sighted, non-driving viewers do not write their documentation so that
it cannot be read by a blind person or over a very slow line (even
though I mostly enjoy a reasonably fast connection, sometimes it is
very, very slow).

Info could be made more like W3M mode in Emacs 21.  W3M is a Web
browsing mode in which you can toggle images on or off.  

-- 
    Robert J. Chassell                         Rattlesnake Enterprises
    http://www.rattlesnake.com                  GnuPG Key ID: 004B4AC8
    http://www.teak.cc                                     bob@gnu.org

^ permalink raw reply	[flat|nested] 68+ messages in thread

* Re: Texinfo/info: scrolling images
  2003-01-12 14:41                   ` Robert J. Chassell
@ 2003-01-13 20:41                     ` Karl Eichwalder
  0 siblings, 0 replies; 68+ messages in thread
From: Karl Eichwalder @ 2003-01-13 20:41 UTC (permalink / raw)
  Cc: emacs-devel

"Robert J. Chassell" <bob@rattlesnake.com> writes:

> Yes, the ASCII representations are often different.  In the case of
> music, I think you would want to use the `letter' notation that (if I
> remember Lilypond rightly) users type in order to input information so
> that Lilypond can create the nicely typeset output that it produces.

Yes, but the goal is to describe and document how the TeX'ed version
will look in the end; thus you want to say something as follows:

    Enter "e" "g" "e" and the score will look (that's my own
    invention--maybe, it's wrong):

    ----------
    ----------
    ----------
    -----o----
    ---o---o--

>    Enhance info in a manner that it can hold alternative
>    representations of the same contents ...
>
> If you really mean Texinfo, this feature has existed for more than a
> decade.  What is wrong with the current feature?

No, I mean the info format.  Like HTML has ALT atributes and DocBook has
<mediaobject> that can hold an object in various formats, info can do
something similar:

    On a graphical device it can display an _graphical_ image and

    -- when running Emacs/info within an xterm -- it can display the
    ASCII representation of the image.

> If you mean to enhance the GNU Emacs Info reader to provide highly
> typeset images for some viewers -- that is a good idea so long as
> sighted, non-driving viewers do not write their documentation so that
> it cannot be read by a blind person or over a very slow line (even
> though I mostly enjoy a reasonably fast connection, sometimes it is
> very, very slow).

Yes, that's what I mean.

> Info could be made more like W3M mode in Emacs 21.  W3M is a Web
> browsing mode in which you can toggle images on or off.  

Exactly :)  Unfortunately, I cannot help with coding.

-- 
ke@suse.de (work) / keichwa@gmx.net (home):              |
http://www.gnu.franken.de/ke/                            |      ,__o
Free Translation Project:                                |    _-\_<,
http://www.iro.umontreal.ca/contrib/po/HTML/             |   (*)/'(*)

^ permalink raw reply	[flat|nested] 68+ messages in thread

end of thread, other threads:[~2003-01-13 20:41 UTC | newest]

Thread overview: 68+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2002-12-31  3:17 Gtk patch version 3, part 1 Jan D.
2003-01-01 16:46 ` Richard Stallman
2003-01-01 18:48   ` Jan D.
2003-01-02  1:10     ` Eric Gillespie
2003-01-02  7:57       ` Jan D.
2003-01-03 19:46         ` Eric Gillespie
2003-01-02  5:56     ` Eli Zaretskii
2003-01-02  8:07       ` Jan D.
2003-01-03  3:32       ` Richard Stallman
2003-01-03  3:30     ` Richard Stallman
2003-01-03 12:39       ` Alfred M. Szmidt
2003-01-04  4:20         ` Richard Stallman
2003-01-04 13:40           ` Alfred M. Szmidt
2003-01-04 16:04             ` Alex Schroeder
2003-01-04 17:43             ` Raja R Harinath
2003-01-04 18:30             ` Eric Gillespie
2003-01-04 19:25               ` Alfred M. Szmidt
2003-01-03 22:42       ` Robert J. Chassell
2003-01-04  0:48         ` Kim F. Storm
2003-01-04  2:55           ` Luc Teirlinck
2003-01-04  3:58             ` Luc Teirlinck
2003-01-04  4:17               ` Luc Teirlinck
2003-01-04 13:30                 ` Jan D.
2003-01-04 16:16                   ` Luc Teirlinck
2003-01-04 16:39                     ` Jan D.
2003-01-04 18:00                       ` Luc Teirlinck
2003-01-04 19:46                         ` Luc Teirlinck
2003-01-04 21:02                           ` Eric Gillespie
2003-01-04 21:55                             ` Luc Teirlinck
2003-01-04 22:54                               ` Eric Gillespie
2003-01-05 18:33                     ` Richard Stallman
2003-01-04 13:11             ` Jan D.
2003-01-04 14:55               ` Alfred M. Szmidt
2003-01-05 18:33               ` Richard Stallman
2003-01-04 15:51             ` Alex Schroeder
2003-01-04 23:44             ` Richard Stallman
2003-01-06  0:17               ` Eric Gillespie
2003-01-06 17:13                 ` Richard Stallman
2003-01-06 19:52                 ` Alex Schroeder
2003-01-04  7:20           ` Texinfo/info: scrolling images (Re: Gtk patch version 3, part 1) Karl Eichwalder
2003-01-11 19:50             ` Stefan Monnier
2003-01-11 21:03               ` Robert J. Chassell
2003-01-12  5:05                 ` Karl Eichwalder
2003-01-12 14:41                   ` Robert J. Chassell
2003-01-13 20:41                     ` Texinfo/info: scrolling images Karl Eichwalder
2003-01-04 23:44           ` Gtk patch version 3, part 1 Richard Stallman
2003-01-05 13:23           ` Robert J. Chassell
2003-01-05 16:00             ` Kim F. Storm
2003-01-05 15:46               ` Alfred M. Szmidt
2003-01-05 16:38               ` Robert J. Chassell
2003-01-06  0:33                 ` Kim F. Storm
2003-01-04 18:26         ` Eric Gillespie
2003-01-03  3:32     ` Richard Stallman
2003-01-02 15:47   ` Kim F. Storm
2003-01-03  3:31     ` Richard Stallman
2003-01-03 19:50       ` Eric Gillespie
     [not found]         ` <E18Ufn2-0003pp-00@fencepost.gnu.org>
2003-01-04 18:34           ` Eric Gillespie
2003-01-05 18:33             ` Richard Stallman
2003-01-06  0:19               ` Eric Gillespie
2003-01-02  5:52 ` Eli Zaretskii
2003-01-02  8:05   ` Jan D.
2003-01-02 17:24     ` Eli Zaretskii
2003-01-03  3:31     ` Richard Stallman
     [not found] <200212311545.gbvfjt0u023298@stubby.bodenonline.com>
2002-12-31 18:06 ` Phillip Garland
     [not found] <200212310414.gbv4et0u014643@stubby.bodenonline.com>
2002-12-31  5:33 ` Phillip Garland
2002-12-31 14:49   ` Jan D.
2002-12-31 21:07 ` Phillip Garland
2002-12-31 23:59   ` Jan D.

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.