From federico Thu Oct 1 12:30:35 -0400 1998 From: Federico Mena Quintero To: gnome-hackers@nuclecu.unam.mx Subject: Musings on what is needed for a gnome-libs 1.0 Hello, Some of us think that the core Gnome libraries are in a state such that looking for a 1.0 release soon is not out of the question. We sat down and went through gnome-libs to see what needs fixing or polishing before 1.0. This mail presents our musings. We asked ourselves why a relatively small number of people are writing Gnome applications as compared to, say, plain Gtk or KDE applications. We came up with several ideas which may or may not be wrong: - A lot of people have the impression that Gnome "is not quite ready yet" and want to wait until it is officially 1.0. - Gnome is a very intimidating thing to install if you have never done it before. Precompiled packages certainly help, though. - Even if potential developers manage to get it installed, the complete lack of documentation leads them to a "now what?" stance. We need documentation. Good documentation, and lots of it. Seeing that the Gnome libraries are pretty much settled down in terms of APIs, we think it is a good idea to look for a code freeze rather soon. This would allow us to release a full 1.0 version within a few months. Here are our random musings, and we would appreciate comments on them. This is a long mail, so please read it carefully and think about it. Needed for gnome-libs 1.0 * Documentation. We need docs big time! KDE has a very, very good documentation framework and system. We need documentation that is up to the quality of Java docs: http://java.sun.com/products/jdk/1.2/docs/api/index.html We can do without something that is as fancy, but we need complete, high-quality documentation: - Complete programmer's and reference documentation. The programmer's part is documentation that explains how to use a particular module, explaining the philosophy behind it. Reference docs are just a detailed a description of every API. - Developer tutorials. Programmers should be able to take a tutorial and whip up their first Gnome application in a day. This allows them to get a feeling of accomplishment, and it makes them feel not threatened by all the libraries. Gnome-hello may need some extra looking at to make sure it can be used for a nice and easy tutorial. - Cookbooks. "How to create standard menus". "How to install keybindings". "How to use the printing system". These allow people to cut&paste working code into their applications. We also need a good documentation framework. Right now the DocBook tools are a pain to install. This may be fixed by making sure the binary packages install cleanly, or making sure the tarballs are easy to install -- make them all use autoconf and friends. All the developer's documentation needs to be on the Gnome web page at all times. This means generating parts or all of the developer's section of the web page from the contents of cvs. Developers should be able to go to the Gnome web page and get the answers they are looking for. We need DocBook templates so that people can cut&paste them and write docs easily. DocBook is a very large and complex system, and it is not easy to learn. People should be able to write docs by cut&paste. * Multiple toolbars. This is basically writing a custom container for GnomeApp so that big applications can install multiple toolbars. It would be nice if you could simply drag toolbars to the edge of the window and have them snap to their horizontal/vertical modes. * Stock cursors. X's predefined cursors are butt-ugly. We need nice looking cursors provided by a stock mechanism. The UI Guidelines document should say when to use which cursors. * CORBA: - Name service/Activation service. - Clear policy on event notification. - Policy on Interface Repository. - Good documentation so that people can make their applications CORBA-aware easily. * Gnome-MDI needs to be convenient to use for a large number of applications. Making Gnumeric use Gnome-MDI could be a good test-bed. We need good documentation for this so that making an application use MDI will be easy. Ideally, adding MDI to an application should be as easy as using a GtkNotebook (figuratively speaking). * Printing system/library. This is pretty much Raph's work integrated with the new paper selector. We need: - A decent font handling and installation policy. - A nice low-level, Postscript-like library (Raph is working on this). - A nicer high level library built on top of the previous one. This is the one that takes a block of text and does word-wrapping, hyphenation, ligatures, and other niceties that are a must for high-quality output. Raph is working on this as well. - Policies for priting from applications -- basically define standard "print" and "print setup" dialogs, as well as a "print preview" mechanism. - Very good documentation for all of the above. We want all Gnome applications to be able to do very high-quality printing. Please note that the printing system is an orthogonal problem to gnome-libs. They can be developed completely independently. This is just to remind people what is happening regarding printing. * Canvas Issues: - Widgets in the Canvas -- Federico will work on these when he rewrites the day view in Gnomecal. - TODO from gnome-canvas.c. - Finish the documentation. * MIME interfaces for DnD: - Make into something really useful! MIME should be used all over the place for DnD. - Clipboard mechanism needs to be settled. This is either through X mechanism or through Baboon. Either way, it needs to work with MIME, work well, and work soon. - Figure out standards for DND, etc. Owen is working on the new DnD system in Gtk, so he knows the details better. The following are the different parts of Gnome-libs and comments on them. * gnome-parse: - Maybe make easier wrappers for argument parsing. This may be solved with nice documentation and a tutorial for argp. * gnome-string: - The split function would be nice if it handled quoting. * Sound support: - Finish it (Elliot is working on this). - Have a collection of stock sounds. Does anyone know how to generate funny/cool/unobtrusive sounds? Can they be synthesized from scratch, or do we need help from an audio recording person? * Popup menus: - For entries -- i.e. cut, copy, paste. - Figure a way to have nice balloon help. Windows has it all over the place, as does the Mac. We need something like gnome_add_balloon_help (GtkWidget *widget, char *help_str); This should be built on top of the tooltips-query mechanism. * Serious Icon rehashing. - Fix all the ugly hacks in GnomeStock. - Make them easily themable. * Rethink Dialog API: - It does almost everything you want, but the API is clunky. * Gnome File selector: - We need a decent file selector -- this may go into Gtk. - Integrate with libvfs. - Allow for extensibility for extra widgets, previews, etc. * Look at Session Management: - Make it sure it works well. - Add it to all apps that are missing it. * Rewrite gnome-icon-list: - Do it in terms of the canvas. - Have a nicer API. - Miguel is going to work on this for gmc. * Gnome-icon-selector -- make it use the new icon list when it is ready. * gnome-propertybox: - It should allow for verification of data (i.e. click Ok, and it should say "you entered a bogus value for SomeOption, please try again". - General cleaning up. * gnome-scores.h - Check it is ok. * gnome-uidefs.h - Move some stuff to gnome-app-util.h * gtk-cauldron - Make sure it is easy to generate pretty-looking dialogs. Most automatically generated dialogs look ugly. * gnome-exec - Add a more sophisticated launcher that returns pid. * gnome-history - Take a look. Create something for GnomeAppHelper that creates a list of recently used files and puts it a menu. Make sure it is used all over the place. * Outside gnome-libs, but really darned necessary - help-browser - gtk-xmhtml * libvfs - Integrate everywhere. - This may need abstracting further so that it can work well in a non-blocking fashion for use with the gtk_input functions. The following things need to be dumped: - libgnomeui/Gnome-lamp - not used anywhere, is ugly. - libgnomeui/Less - Is this really useful? - libgnomeui/gnome-net - not used anywhere. - libgnomeui/gnome-entry - Need to rewrite GtkCombo instead. - libgnomeui/gnome-font-selector - Use the one from Gtk instead. - libgnomeui/gnome-gtk-utils - Useless. - libgnomeui/gnome-properties - Deprecated. - libgnomeui/gnome-root - To be updated by the new DnD mechanism in Gtk - libgnomeui/gtk-clock - Useless. - libgnomeui/gtkcalendar - Deprecated, to be replaced with GnomeMonthItem. - libgnomeui/gtk-ted - Make sure it works and does not generate ugly dialogs. It may need to support nested TEDs inside GtkFrames and such. - libgnomeui/gtk-spell - Needs to be hashed out as a separate Baboon component. - libgnome/gnome-dl - Deprecated, use gmodule instead. - libgnome/fileconvert - Useless. - libgnome/gnome-hook - Not used anywhere. - libgnome/lib_date.h - Deprecated, since it is in Gtk now. Gtk even has a newer version that is leaner on the namespace. (n.b. GnomeMonthItem in Gnomecal has a couple of functions to handle dates; maybe it is everything we need for Gnumeric and should be used instead of the slightly bulkier and uglier libdate). - libgnome/lib_defs.h - Same. - libgtktty - already dumped from distribution. The following need to be moved out of gnome-libs and put elsewhere: - gtkxmhtml - Needs to be in its own cvs module; ask Koen about it. ***** This is mostly what we think is needed as far as Gnome-libs-1.0 is concerned. There are separate issues in Gtk and Gnome-core that need to be flushed out before a 1.0 release. We will present these in separate mails. Sorry for the big mail :-) Some random hackers at RHAD