matchbox/matchbox-documentation
1
0
Fork 0
mirror of https://git.yoctoproject.org/matchbox-documentation synced 2025-11-05 21:45:41 +08:00
Code Issues Packages Projects Releases Wiki Activity

various manual updates

Browse Source 
git-svn-id: https://svn.o-hand.com/repos/matchbox/trunk/matchbox-documentation@709 b067294f-1dea-0310-9683-c47a78595994
This commit is contained in:
mallum
2004-02-09 20:59:20 +00:00
parent 472612f1a2
commit 1601956f74
4 changed files with 446 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
manual/docbook-local.css Normal file
View File

@@ -0,0 +1,40 @@
BODY, body, p, table, td {
font-size: 9pt;
font-family: verdana, sans serif;
font-style: normal;
font-weight: normal;
font-variant: normal;
line-height: normal;
}
h1 {
font-size: 13pt;
font-family: verdana, sns serif;
}
h2 {
font-size: 11pt;
font-family: verdana, sns serif;
}
.BOOK .TITLE { text-align: center }
.BOOK .SUBTITLE { text-align: center }
.BOOK .CORPAUTHOR { text-align: center }
.BOOK .AUTHOR { text-align: center }
.BOOK .AFFILIATION { text-align: center }
.BOOK .EDITEDBY { text-align: center }
.BOOK .EDITOR { text-align: center }
.BOOK .GRAPHIC { text-align: center }
.ARTICLE .TITLE { text-align: center }
.ARTICLE .SUBTITLE { text-align: center }
.ARTICLE .CORPAUTHOR { text-align: center }
.ARTICLE .AUTHOR { text-align: center }
.ARTICLE .AFFILIATION { text-align: center }
.ARTICLE .EDITEDBY { text-align: center }
.ARTICLE .EDITOR { text-align: center }
.ARTICLE .GRAPHIC { text-align: center }
.ARTICLE .ABSTRACT { margin-left: 0.5in;
margin-right: 0.5in;
font-style: italic }

95
manual/matchbox-manual.sgml
View File

@@ -8,7 +8,7 @@
<article id="index"> <!-- please do not change the id --> <article id="index"> <!-- please do not change the id -->
<artheader> <artheader>
<title>Matchbox Project</title> <title>Matchbox Project Manual</title>
<copyright> <copyright>
<year>2004</year> <year>2004</year>
<holder>Matthew Allum</holder> <holder>Matthew Allum</holder>
@@ -64,11 +64,6 @@
</para> </para>
<para>
XXX compile time features
</para>
</section> </section>
<section id="wm"> <section id="wm">
@@ -1251,13 +1246,93 @@ The fill desktop entry spec can be found at <ulink url="http://www.freedesktop.o
</section> </section>
<section id="building"> <section id="building">
<title>Appendix I: Compiling Matchbox</title> <title>Appendix I: Building Matchbox from source.</title>
<para> <para>
Firstly its recommended if your not used to building software from
source, you should check your distrobution for pre built binary
matchbox packages.
</para> </para>
<para>
All Matchbox packages use GNU autotools and are configured and build
by the usual;
</para>
<para>
<programlisting>
% ./configure
% make
% sudo make install
</programlisting>
</para>
<para>
You can see the various compile time options for enabling extra
features and dependencies by running.
</para>
<para>
<programlisting>
% ./configure --help
</programlisting> </para>
<para>
<ulink type="http"
url="http://matchbox.handhelds.org/whatis.shtml">What is matchbox</ulink> gives more infomation on each optional dependency.
</para>
<section><title>Inter Dependencies</title>
<para>
Virtually all packages are dependant on libmatchbox. You should build
and install libmatchbox first. All font and image operations
are provided to other matchbx packages via libmatchbox. Therefore the
configure options you choose here ( such as Pango, JPEG support ) will
affect dependant packages.
</para>
<para>
Matchbox-window-manager can be built <emphasis>without</emphasis> libmatchbox using the
--enable-standalone options. It is highly recommeded you only do this
is you intend to run <emphasis>only</emphasis> the window manager with no bells and
whistles such as themeing. This build option is intended mainly for
platforms where resources are very low or you want a quick and
depencie free window manager for testing on a new platform
</para>
<para>
If you decide to install the matchbox-panel or matchbox-desktop
packages you should install the matchbox-common package first. It
contains icons and launcher configuration data shared by both the
desktop and the panel menu launcher.
</para>
<para>
If you encounter problems building, please report to the <ulink type="http" url="http://matchbox.handhelds.org/mailinglist.shtml">mailing list</ulink>
for help.
</para>
</section> <section><title>Automated building</title>
<para>
An
automated build script is available to ease the build process. This
will build a fully featured matchbox enviroment including the window
manager, desktop, panel and panel applications.
</para>
<para>
Downlaod <ulink type="http" url="http://matchbox.handhelds.org/sources/utils/matchbox-autobuild.sh">matchbox-autobuild.sh</ulink> script. Open in your favourite text editor, edit the
varibles at the top of the top and then run.
</para>
</section>
<section><title>Building from CVS</title>
<para>
If you plan on building from CVS, then before you build;
</para>
<para>
<itemizedList>
<listitem><para>autoconf --version must report 2.5 or later</para></listitem>
<listitem><para> automake --version must report 1.7.x</para></listitem>
<listitem><para> libtool --version must report 1.5 (available from <ulink type="http" url="http://ftp.club.cc.cmu.edu/\pub/gnu/libtool/libtool-1.5.tar.gz">http://ftp.club.cc.cmu.edu/\pub/gnu/libtool/libtool-1.5.tar.gz</ulink> if your distribution doesn't have it)
</para></listitem>
<listitem><para>pkg-config --version must report 0.9.0 or later</para></listitem> </itemizedList>
</para>
<para>
If you plan on submitting patches please diff them against CVS.
</para>
</section> </section>
</section>
</article> </article>

318
testing/testing.docbook Normal file
View File

@@ -0,0 +1,318 @@
<?xml version="1.0"?>
<article>
<artheader>
<title>Matchbox Testing HOWTO. (V 0.1)</title>
<author><firstname>Matthew</firstname>
<surname>Allum</surname>
<email>matthew@openedhand.com</email>
</author>
<copyright>
<year>2003</year>
<holder>Openedhand Ltd</holder>
</copyright>
</artheader>
<section><title>Introduction</title>
<para>
Testing is important. Matchbox is likely to be a key part of the
system - even a minor bug can cause serious user problems. The async
nature of X11, interdependencies of code mechanisms and the
complexities of window management all can lead to the introduction of
bugs when even minor code is added or modified. Therefore thorough
testing is important to avoid such problems.
</para>
<para>
The best way to test Matchbox is 'in the wild' from real user usage
and feedback, however this is not always practical - it's extremely
useful to perform a stardard set of tests after changes to to the
source code and before making a release. This document discusses; how
to run Matchbox in a testing enviroment, how to use the test scripts
included in the distribution and what to do if tests fail.
</para>
</section>
<section><title>Running Matchbox for testing.</title>
<para>
Xnest basically provides a X server in an X window - it being both an
X Server and an X Client at the same time. This makes it useful for
both testing Matchbox on a desktop machine and 'emulating' PDA sized
displays. The procedure for running Matchbox in an Xnest follows;
</para>
<programlisting>
% Xnest :1 -ac -geometry 240x320
% export DISPLAY=:1
% matchbox
</programlisting>
<para>
A similar technique can be used to run Matchbox locally on a
development machine but have it manage windows on another display (
such as a handheld ). On the remote machine, make sure there is no
window manager already running and then give access for the X Server
from the development machine ( e.g. with xhost +&lt;dev machine ip&gt; or by
using Xnest with -ac argument ). On the development machine set the
DISPLAY env variable to the remote machines IP and then launch Matchbox.
</para>
<para>
Matchbox can be run under Valgrind on x86 platforms to
debug memory allocations and management.
</para>
<para>
Its recommended, though not essential, that the Matchbox build is
configured with the '--enable-debug' switch. Apart from compiling with
-g switch ( for gdb ) , the resulting binaries will spew verbose
messages to stdout which contain information that's useful for fixing any
failed tests.
</para>
</section>
<section><title>The Tests</title>
All tests are in the Matchbox distro's tests/ directory. You should
run tests from within that directory.
<section><title>test-windows.sh</title>
Tests Matchbox's handling of various window types by means of the winspew application.
</section>
<section><title>test-interaction.sh</title>
<para>
Creates some various window types and then replays some Xnee data (
test-interaction.xnee ) automating common window operations on these
created windows. A Screenshot is then taken at completion and compared
with a reference one ( test-interaction.xwd ) to indicate success or
failure. If installed, <ulink url="http://www.imagemagick.org/">Image
Magick's</ulink> 'display' program will be used to visually present
failed screenshots.
<para>
The currently assumes a
240x320 Xnest window and the blondie theme, it will refuse to run if
this not set up.
</para>
</para>
<para>
Its highly recommended you avoid any system interaction
while this test is running as this can lead to false results.
</para>
</section>
<section><title>test-pings.sh</title>
<para>
Tests Matchbox's default handling of a hung app.
Launches an app, 'hangs' it and checks 30 seconds later to see if the
process still exists.
</para>
<para>
By defualt the app tested is 'gtk-demo'. This is included in the GTK2 source distobution and is in the 'gtk2-examples' package on Debian.
</para>
</section>
<section><title>test-dock.sh</title>
<para>
Tests mbdock by running it under Valgrind in different orientations,
adding and removing panel applets.
</para>
</section>
<section><title>test-gconf.sh</title>
<para>
test-gconf.sh currently just edits the 'cycle_window' shortcut and
then 'tests' it via sendkey.
</para>
</section>
</section>
<section><title>Running All Tests</title>
<para>
The 'testrun.sh' script aims to run all tests automated in a
standardised enviroment before producing a report summary.
It performs the following;
</para>
<para>
<para>Starts Xnest and sets $DISPLAY to this server.</para>
<para>Starts Matchbox optionally running under Valgrind.</para>
<para>Sets the Matchbox theme via mbcontrol</para>
<para>Runs each test, non-interactively</para>
<para>Finally produces a simple report, commenting on how each test went.</para>
</para>
<para>
The script reads parameters set in test.conf and runs all listed
tests. You can specify particular tests to run and and specify an
alternate config file to use. Run testrun.sh with '-h' to see how to
set this.
</para>
<para>
To add a new test to be run, just name the new script test-XXXX.sh (
where XXXX is anything you like ) and add to tests directory.
</para>
</section>
<section><title>Reporting a failed Test</title>
<para>
Please report failed tests to <ulink
url="http://bugs.openedhand.com/index.cgi/Matchbox/index">bugs.openedhand.com</ulink>, giving as much infomation as possible.
</para>
</section>
<section><title>Appendix A - Tools</title>
<section><title>Valgrind</title>
<para>
An open-source memory debugger for x86-GNU/Linux.
<ulink url="http://developer.kde.org/~sewardj/">http://developer.kde.org/~sewardj/</ulink>
</para>
<para>
By default the tests run Valgrind with the following arguments.
<programlisting>
valgrind --error-limit=no --num-callers=32 --leak-check=yes
</programlisting>
</para>
</section>
<section><title>Xnee</title>
<para>
Xnee allows the recording and replaying of X protocol data.
<ulink url="http://www.gnu.org/software/xnee/">http://www.gnu.org/software/xnee/</ulink>
</para>
<para>
To record data for Xnee, Im currently using something like;
<programlisting>
xnee -ae -o test-interaction.xnee -l -1
</programlisting>
Which basically translates to capture all events ( -ae ) , output ( -o
) to test-interaction.xnee and keep capturing for ever ( -l -1 ). I
stop capture with ctrl-c.
To then replay the data ( as in test-interaction.sh ), use;
<programlisting>
xnee -rep -f test-interaction.xnee
</programlisting>
I'm using xnee 1.07.
</para>
</section>
<section><title>Xnest</title>
<para>
Xnest is an X server that is itself an X client. This allows you to run
a server within a server - useful for testing new window managers and
other X clients.
</para>
<para>
Included in XFree86 distribution from <ulink url="http://www.xfree86.org">http://www.xfree86.org</ulink>.
</para>
</section>
<section><title>winspew</title>
<para>
Creates dummy windows of arbitrary types and properties.
Included with Matchbox in tests/, pass '-help' to get usage info.
</para>
</section>
<section><title>sendkey</title>
<para>
Uses XTest extension to send arbitrary keycodes and modifiers to the X
Server from the command line.
Included with Matchbox in tests/, pass '-help' to get usage info.
</para>
</section>
<section><title>mbcontrol</title>
<para>
Simple remote control of Matchbox, such as changing the theme.
Included with Matchbox in utils/.
</para>
</section>
</section>
<section><title>Appendix B - Useful X debugging tools</title>
<para>
Please refer the the man pages for useful tools such
xprop, xclientlist, xwd
</para>
<para>
Also see <ulink
url="http://www.xfree86.org/~mvojkovi/restest.c">http://www.xfree86.org/~mvojkovi/restest.c</ulink>
for an example of X-Resource extension usage. 'XRes' is a new XFree86
server extension ( > 4.2 ) which can used to monitor client resource
usage and detect server side pixmap leaks.
</para>
</section>
</section>
</article>

4
theme-howto/theme.howto.docbook
View File

@@ -1008,7 +1008,7 @@ Use the top level 'appicon' tag. eg;
</programlisting> </programlisting>
</para> </para>
</section>
<section><title>How do I set the lowlight color ?</title> <section><title>How do I set the lowlight color ?</title>
<para> <para>
@@ -1025,6 +1025,7 @@ to take effect.
</para> </para>
</section>
<section><title>How do I set window shadows ?</title> <section><title>How do I set window shadows ?</title>
<para> <para>
@@ -1085,6 +1086,7 @@ defined area.
</para> </para>
</section>
<section><title>Where can I find more infomation ?</title> <section><title>Where can I find more infomation ?</title>
<para> <para>
See the various themes included with the matchbox distrubution ( in data/themes ) and the matchbox-themes package. See the various themes included with the matchbox distrubution ( in data/themes ) and the matchbox-themes package.