Updates

svn path=/trunk/; revision=18429

docs/reference/ChangeLog

@@ -1,3 +1,8 @@
+2007-07-10  Matthias Clasen  <mclasen@redhat.com>
+
+	* gtk/migrating-GtkBuilder.sgml: Add some stuff
+	* gtk/gtk-builder-convert.xml: Updates
+
 2007-07-09  Matthias Clasen  <mclasen@redhat.com>
 
 	* gdk-pixbuf/tmpl/scaling.sgml: Remove uses of deprecated api 

docs/reference/gtk/gtk-builder-convert.1

@@ -1,11 +1,11 @@
 .\"     Title: gtk-builder-convert
 .\"    Author: 
 .\" Generator: DocBook XSL Stylesheets v1.72.0 <http://docbook.sf.net/>
-.\"      Date: 06/26/2007
+.\"      Date: 07/10/2007
 .\"    Manual: 
 .\"    Source: 
 .\"
-.TH "GTK\-BUILDER\-CONVERT" "1" "06/26/2007" "" ""
+.TH "GTK\-BUILDER\-CONVERT" "1" "07/10/2007" "" ""
 .\" disable hyphenation
 .nh
 .\" disable justification (adjust text to left margin only)
@@ -13,20 +13,31 @@
 .SH "NAME"
 gtk\-builder\-convert \- Glade file conversion utility
 .SH "SYNOPSIS"
-.HP 25
+.HP 20
-\fBgtk\-builder\-convert \fR\fB{file}\fR
+\fBgtk\-builder\-convert\fR [\-\-skip\-windows] [\-\-root\ \fIname\fR] {input} {output}
 .SH "DESCRIPTION"
 .PP
 \fBgtk\-builder\-convert\fR
-converts glade files into XML files which can be loaded with GtkBuilder.
+converts glade files into XML files which can be loaded with #GtkBuilder.
 .PP
-It expects the name of a glade file as sole argument, and writes its output to stdout.
+It expects the name of a glade file as the first argument, and writes its output the file specified as the second argument.
+.SH "OPTIONS"
+.PP
+\-\-skip\-windows, \-w
+.RS 4
+Convert everything but GtkWindow subclasses.
+.RE
+.PP
+\-\-root, \-r
+.RS 4
+Convert only the widget named
+\fIname\fR
+and its children.
+.RE
 .SH "BUGS"
 .PP
-GtkComboBox items are not converted into GtkListStore data.
-.PP
-GtkTextView text is not converted into a GtkTextBuffer.
-.PP
 Toolbars are not handled.
 .PP
+Support for accessibility is not yet implemented.
+.PP
 The script requires a python interpreter to run.

docs/reference/gtk/gtk-builder-convert.xml

@@ -12,7 +12,11 @@
 
 <refsynopsisdiv>
 <cmdsynopsis>
-<command>gtk-builder-convert <arg choice="req">input</arg><arg choice="req">output</arg></command>
+<command>gtk-builder-convert</command>
+<arg choice="opt">--skip-windows</arg>
+<arg choice="opt">--root <replaceable>name</replaceable></arg>
+<arg choice="req">input</arg>
+<arg choice="req">output</arg>
 </cmdsynopsis>
 </refsynopsisdiv>
 
@@ -26,6 +30,22 @@ its output the file specified as the second argument.
 </para>
 </refsect1>
 
+<refsect1><title>Options</title>
+<variablelist>
+  <varlistentry>
+    <term>--skip-windows</term>
+    <term>-w</term>
+    <listitem><para>Convert everything but GtkWindow subclasses.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>--root</term>
+    <term>-r</term>
+    <listitem><para>Convert only the widget named <replaceable>name</replaceable> 
+       and its children.</para></listitem>
+  </varlistentry>
+</variablelist>
+</refsect1>
+
 <refsect1><title>Bugs</title>
 <para>
 Toolbars are not handled.

docs/reference/gtk/migrating-GtkBuilder.sgml

@@ -9,7 +9,48 @@
   </para>
 
   <para>
-    More details about migrating from libglade to GtkBiulder will 
+    While GtkBuilder strives to be a complete replacement for
+    libglade, there are a number of areas where it is currently
+    still behind libglade:
+    <itemizedlist>
+
+      <listitem><para>
+        GtkBuilder can not construct partial trees, it lacks
+        the equivalent of the @root parameter of glade_xml_new().
+        Due to the way GtkBuilder parses its input, this is difficult 
+        to implement, see 
+        <ulink url="http://bugzilla.gnome.org/show_bug.cgi?id=447998">bug 
+        447998</ulink>. As a workaround, you can split your glade file 
+        into multiple GtkBuilder input files. The 
+        <application>gtk-builder-convert</application> conversion script 
+        has a <option>--root</option> option that can help with this.
+      </para></listitem>
+
+      <listitem><para>
+        GtkBuilder does not yet implement support for accessibility 
+        properties. It parses the same &lt;accessibility&gt; elements 
+        as libglade, but ignores them. See 
+        <ulink url="http://bugzilla.gnome.org/show_bug.cgi?id=454653">bug 
+        454983</ulink> for the current status of accessibility support 
+        in GtkBuilder.
+      </para></listitem>
+ 
+      <listitem><para>
+        GtkBuilder supports context information in translatable
+        properties in a slightly different way than libglade. 
+        Intltool does not yet support this; see 
+        <ulink url="http://bugzilla.gnome.org/show_bug.cgi?id=454894">bug 
+        454894</ulink> for the current status of intltool support for 
+        GtkBuilder files. Thankfully, context in translations is a 
+        rarely used feature, and if you are not using it, intltools 
+        glade format support works just fine for GtkBuilder files.
+      </para></listitem>
+
+  </itemizedlist>
+  </para>
+
+  <para>
+    More details about migrating from libglade to GtkBuilder will 
     appear here over time...
   </para>