GNOME.org
 

[sapwood] turn the readme into docbook

commit 4b37534b0759a37814ba0391d5381bf2adbc81a0
Author: Sven Herzberg <herzi gnome-de org>
Date:   Sat Jul 31 16:59:51 2010 +0200

    turn the readme into docbook
    
    * README -> readme.xml: turn the readme into docbook

 README => readme.xml |  209 ++++++++++++++++++++++++++++++++++----------------
 1 files changed, 144 insertions(+), 65 deletions(-)
---
diff --git a/README b/readme.xml
similarity index 77%
rename from README
rename to readme.xml
index 558eecc..d6d953c 100644
--- a/README
+++ b/readme.xml
@@ -1,6 +1,12 @@
-sapwood
-=======
-
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+  "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd";>
+<article id="sapwood-readme" lang="en">
+    <title>README for Sapwood</title>
+
+    <section>
+        <title>Sapwood</title>
+    <para>
 Derived from the pixbuf engine in gtk-engines 2.2.0
 
 Uses X pixmaps (pixbuf engine uses pixbufs)
@@ -22,25 +28,29 @@ Instead
 Note that 1bit alpha still allows you to do things like drop shadows in some
 cases. You just need to be careful about the background and fake the effect
 with opaque bitmaps.
+        </para>
+    </section>
 
+    <section>
+        <title>Installation</title>
 
-Installation
-============
-
+        <para>
  ./configure
  make
  [ become root ]
  make install
+        </para>
+    </section>
 
+    <section>
+        <title>Running</title>
 
-Running
-=======
-
+        <para>
 In order to run applications using the sapwood theme engine, the
 sapwood-server needs to be started beforehand. You can do this by running the
 following command:
 
- /usr/lib/sapwood/sapwood-server &
+ /usr/lib/sapwood/sapwood-server &amp;
 
 It is important to use the same TMPDIR and DISPLAY environment variables for
 both the sapwood-server as well as the applications so that the theme engine
@@ -52,18 +62,22 @@ in the console:
 
 When that happens, check the TMPDIR and DISPLAY environment variables and
 check the sapwood-server process is running.
+        </para>
+    </section>
 
+    <section>
+        <title>Bugs</title>
 
-Bugs
-====
-
+        <para>
 Please report bugs to maemo.org bugzilla:
-https://maemo.org/bugzilla/enter_bug.cgi?product=haf&component=sapwood
-
+https://bugs.gnome.org/bugzilla/enter_bug.cgi?product=sapwood
+        </para>
+    </section>
 
-gtkrc
-=====
+    <section>
+        <title>gtkrc</title>
 
+        <para>
 Mostly compatible with the pixbuf engine
  * engine "sapwood" instead of "pixmap"
  * 'recolorable' declaration is not supported
@@ -72,10 +86,13 @@ This document covers only the theme engine specific details. For more generic
 overview see the following links:
  * http://developer.gnome.org/doc/API/2.0/gtk/gtk-Resource-Files.html
  * http://live.gnome.org/GnomeArt/Tutorials/GtkThemes
+        </para>
 
+        <section>
+            <title>Overview</title>
+
+            <para>
 
-Overview
---------
 engine "sapwood" {
   image { ... }
   image { ... }
@@ -99,10 +116,13 @@ Example:
 image {
   function = FOCUS
 }
+            </para>
+        </section>
 
+        <section>
+            <title>Precedence</title>
 
-Precedence
-----------
+            <para>
 The order of image blocks matters. The first image to satisfy the match options
 is used. Put the specific rules first and generic rules last, like this:
 
@@ -120,10 +140,13 @@ engine "sapwood" {
 
 If the two image blocks are reordered, the 'generic image' is always used,
 even for INSENSITIVE widgets.
+            </para>
+        </section>
 
+        <section>
+            <title>match options</title>
 
-match options
--------------
+            <para>
 The widget, widget_class and class declarations supported by gtk+ let you to
 attach style declarations to widgets. The image declarations let you attach
 images to the painting commands used by the widgets.
@@ -145,7 +168,7 @@ C                                   gtkrc
 gtk_paint_box(                                  function = BOX
   state  = GTK_STATE_NORMAL                  state = NORMAL
   shadow = GTK_SHADOW_IN                  shadow = IN
-  widget = <GtkButton>
+  widget = &lt;GtkButton&gt;
   detail = "buttondefault"                  detail = "buttondefault"
 )
                                           [image data]
@@ -194,27 +217,38 @@ STEPPER    | arrow_direction                      shadow |
 TAB        |                                      shadow | gtk_paint_tab
 VLINE      |                          orientation        | gtk_paint_vline
 ----------------------------------------------------------------------------------------------
+            </para>
 
+            <section>
+                <title>function = ARROW</title>
 
-function = ARROW
-~~~~~~~~~~~~~~~~
-gtk_paint_expander uses arrows.
+                <para>
+                    gtk_paint_expander uses arrows.
+                </para>
+            </section>
 
+            <section>
+                <title>function = FOCUS</title>
 
-function = FOCUS
-~~~~~~~~~~~~~~~~
+                <para>
 Focus indicator is always painted on top of all other graphics and the widget
 content. It should be a (hollow) rectangle with transparency. Otherwise it will
 hide the content.
+                </para>
+            </section>
 
+            <section>
+                <title>function = STEPPER</title>
 
-function = STEPPER
-~~~~~~~~~~~~~~~~~~
-Used for scrollbar arrows.
+                <para>
+                    Used for scrollbar arrows.
+                </para>
+            </section>
 
+            <section>
+                <title>position</title>
 
-position
-~~~~~~~~
+                <para>
 You can select different graphics based on the position of the widget inside
 the container. The value for position is a combination of LEFT, RIGHT, TOP, and
 BOTTOM when the widget is leftmost, rightmost, topmost, or bottommost
@@ -224,11 +258,15 @@ You'll need to set the "maemo-position-theming" property of the widgets' parent
 TRUE for this data to be set in sapwood.
 
 See demos/buttonbox.gtkrc
+                </para>
+            </section>
+        </section>
 
+        <section>
+            <title>image data</title>
 
-image data
-----------
 
+            <para>
 file    = (filename, see the example below)
 border  = { left, right, top, bottom }	    (default: { 0, 0, 0, 0 })
 stretch = TRUE | FALSE			    (default: TRUE)
@@ -251,10 +289,12 @@ image {
 
   file = "image.png"
 }
+            </para>
 
+            <section>
+                <title>file</title>
 
-file
-~~~~
+                <para>
 Path to an image file whose format is supported by GdkPixbuf. The path should
 be relative (relative to the directory where the gtkrc file is located, or
 relative to the paths set with 'pixmap_path') 
@@ -290,10 +330,13 @@ style "button" {
   }
 }
 ----
+                </para>
+            </section>
 
+            <section>
+                <title>border</title>
 
-border
-~~~~~~
+                <para>
 Used together with 'stretch = TRUE' See 'Images and borders' below for more
 details.
 
@@ -302,10 +345,13 @@ multiple times with different border values. This is a limitation in the
 implementation. It is unlikely to cause any significant problems as the same
 image is rarely meant to be tiled in different ways. It is more commonly an
 indication of a typo in the gtkrc file.
+                </para>
+            </section>
 
+            <section>
+                <title>shaped</title>
 
-shaped
-~~~~~~
+                <para>
 When set to TRUE the transparent pixels (more than 50% transparency) in the
 bitmap are applied to the underlying window. This allows menus, for example,
 to have rounded corners.
@@ -314,20 +360,26 @@ NOTE: If the bitmap does not have an alpha channel, shaped must NOT be set or
 strange drawing artefacts will appear.
 
 Used only for GtkWindow and GtkMenu widgets (and derivatives)
+                </para>
+            </section>
 
+            <section>
+                <title>stretch</title>
 
-stretch
-~~~~~~~
+                <para>
 When set to TRUE the image is stretched to fill the whole area that is
 requested. See 'Images and borders' below for how the stretching is done.
 
 When set to FALSE the image is centered instead.
 
 Note: stretch = FALSE and border != 0 makes no sense
+                </para>
+            </section>
 
+            <section>
+                <title>overlay</title>
 
-overlay
-~~~~~~~
+                <para>
 overlay_file, overlay_border, overlay_stretch
 
 Overlay image is painted after the background image (as referenced by 'file')
@@ -338,10 +390,13 @@ NOTE: 'overlay_stretch = TRUE' rarely makes sense as it'll paint over the area
 already covered by the background image. 
 
 Not used if function is BOX_GAP, FOCUS, HLINE, SHADOW, SHADOW_GAP, or VLINE.
+                </para>
+            </section>
 
+            <section>
+                <title>gap_start, gap, gap_end</title>
 
-gap_start, gap, gap_end
-~~~~~~~~~~~~~~~~~~~~~~~
+                <para>
 When function is BOX_GAP or SHADOW_GAP more images are needed to paint the gap
 differently from its surroundings. Use the following declarations:
  * gap_start_file, gap_start_border, gap_start_stretch
@@ -349,11 +404,15 @@ differently from its surroundings. Use the following declarations:
  * gap_end_file, gap_end_border, gap_end_stretch
 
 They're similar to file, border and stretch.
+                </para>
+            </section>
+        </section>
+    </section>
 
+    <section>
+        <title>Images and borders</title>
 
-Images and borders
-==================
-
+        <para>
 border = { left, right, top, bottom }
 the number of pixels from left, right, top and bottom edge respectively
 
@@ -406,27 +465,33 @@ both horizontally and vertically.
     2,8 are tiled horizontally
     4,6 are tiled vertically
       5 is tiled both horizontally and vertically
+        </para>
+    </section>
 
+    <section>
+        <title>Special cases</title>
 
-
-Special cases
-=============
-
+        <para>
 The theme engine includes special cases for some widgets which are needed to
 get the Maemo look and feel. They should not interfere when not used.
+        </para>
 
+        <section>
+            <title>GtkButton</title>
 
-GtkButton
----------
+            <para>
 You can use the button position in the button box (solitary, leftmost, middle,
 rightmost) to select different bitmaps for buttons in button boxes. This allows
 painting dialog buttons nicely rounded.
 
 See 'position' above and demos/buttonbox.gtkrc
+            </para>
+        </section>
 
+        <section>
+            <title>GtkCheckButton and GtkRadioButton</title>
 
-GtkCheckButton and GtkRadioButton
----------------------------------
+            <para>
 You can use artificial ACTIVE state to select different bitmaps for check and
 radio button indicators when the widget is focused. This allows painting focus
 indicator style different from the standard dashed rectangle.
@@ -438,25 +503,39 @@ GtkCheckButton:
 GtkRadioButton:
   function = OPTION
   state    = ACTIVE
+            </para>
+        </section>
 
+        <section>
+            <title>GtkMenuItem</title>
 
-GtkMenuItem
------------
+            <para>
 Selected item background:
   function = BOX
   state    = PRELIGHT for active, SELECTED for passive focus
+            </para>
+        </section>
 
+        <section>
+            <title>GtkTreeView</title>
 
-GtkTreeView
------------
+            <para>
 Cursor row background, passive focus:
   function = FLAT_BOX
   state    = SELECTED / NORMAL
   shadow   = OUT
 
 See demos/treeview.gtkrc
+            </para>
+        </section>
+    </section>
 
+    <section>
+        <title>Random details</title>
 
-Random details
-==============
+        <para>
 Changing an image file might require switching themes.
+        </para>
+    </section>
+</article>
+<!-- vim:set sw=4 et: -->
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]