updated to usermanual by Clement Seveillac <clement@nist.gov>, changelog on http://handhelds.org/hypermail/opie/current/7412.html

5 files changed, 77 insertions, 102 deletions

diff --git a/docs/usermanual/gettingaround.sgm b/docs/usermanual/gettingaround.sgm
index 34ef403..68210de 100644
--- a/docs/usermanual/gettingaround.sgm
+++ b/docs/usermanual/gettingaround.sgm
@@ -1,150 +1,148 @@
 <chapter><title>Using &opie;</title>
 
 <section><title>Running &opie; for the first time</title>
 <para>
 If everything was installed as described in the previous section, &opie; should
 now start up and present a screen to calibrate the touchscreen. Using the stylus,
 press firmly in the middle of the cross-hairs as they appear on the screen. This
 usually needs to be done only once, however the screen can be re-calibrated at any
 time, if needed, by choosing the Calibrate application on the Settings tab.
 </para>
 
 <para>
 Once the screen has been calibrated, &opie; will now start up.  If the opie-login
 package is installed (which is installed with the default installation), a screen
 will appear requiring a person to log in before any applications can be accessed.
 The standard &opie; installation currently requires the user to log in as the
-'root' user in order for all functions to work correctly. Refer to the Familiar
-website (http://familiar.handhelds.org) for the default password for the version
-installed.
+'root' user in order for all functions to work correctly. Refer to the <ulink url="http://familiar.handhelds.org/#faqs">Familiar
+FAQ</ulink> for the default password for the version installed.
 </para>
 
 <para>
 Once the correct password has been entered, &opie; should now be running. When
 rebooted however, &opie; will start automatically. To install and remove
 applications, the "Packages" application (located on the Settings tab) or the
 command line ipkg application can be used. There are several task-opie packages
 which allow the installation of whole categories (e.g. games, PIM, settings, etc.)
-of software at once. It also might be helpful to install either opie-embeddedkonsole
-or opie-console first to allow access a command line from within &opie;.
+of software at once.
 </para>
 </section>
 
 <section><title>Getting Around</title>
 <para>
 Now that &opie; is installed and running, it is time to start using it. When &opie;
 is started (after logging in), the following will be visible: the "Launcher" from
 which all of the applications can be started, and the "Taskbar" along the bottom, where
 all running applications can be accessed, select an input method, and interact with the
 installed applets.
 </para>
 
 <para>
 Getting around in &opie; is very easy. Using the stylus, simply click on whatever
 icon, button or control desired. The main difference between using the stylus and using
 a mouse is that there is not an intuitive way to "right click" with the stylus. However in
 &opie;, by pressing and holding the stylus down on the screen for approximately one second
 (i.e. commonly referred to as "click and hold") a right mouse button click is generated.
 This allows the user to perform common actions such as display context sensitive menus.
 </para>
 
 <para>
 Also included in several &opie; applications is context sensitive help. If there is a icon
 with a question mark on the left side of the application's title bar, then this option
 is available. Clicking on this icon will display instructions on using this feature.
 Click and hold the icon, until the window title changes to "What's this..." and then
 click on a part of the application window to display the context sensitive help.
 </para>
 </section>
 
 <section><title>Launcher</title>
 <para>
 The Launcher is where applications can be started, and is similar in concept to the desktop
 found in most computer graphical user interfaces. When no other applications are running,
 it is visible, occupying most of the screen. 
 </para>
 
 <para>
 Along the top of the Launcher is a series of tabs which function as categories for all
 installed applications. By default, there are the following tabs: PIM, Applications and
 Settings. If any games are installed, there will also appear a Games tab. To launch an
 application, click once on the application icon or name. The icon will darken and an
 hour glass will appear on the taskbar at the bottom of the screen to indicate that the
 application is launching.  Most applications take 1 or 2 seconds to start.
 </para>
 
 <para>
 There is also a tab to the far right named Documents. It contains a listing of the
 documents found on the handheld device, allowing easy access. Documents are organized
 by document type and category.  At the bottom of the Document tab are 2 selection boxes
 which allow the list of docuemnts to be filtered by these criteria. For instructions on
 adding and removing documents from this tab, see the <xref linkend="adddoc">.
 </para>
 
 <para>
 The Launcher Settings application on the Settings tab allows each tab's appearance to
 be customized. Items that can be configured include background color/image, font, icon
 size and more. See the Launcher Settings section for more information.
 </para>
 
 </section>
 
 <section><title>Taskbar</title>
 <para>
 The Taskbar is the small, horizontal section which appears at the bottom of the
 screen, below the Launcher. It is almost always visible while applications are
 running.  The Taskbar provides the following functions (from left to right):
 </para>
 
 <para>
 1. "O" menu - provides a listing of all installed applications, allowing them to be
 started if Launcher is not visible. It also provides an options to display Launcher
 if there are applications running, power off the handheld device and log out of &opie;.
 </para>
 
 <para>
 2. Input methods - allows the selection of an input method. Each input method has its
 own, unique icon, and the current one selected is shown on the Taskbar. Click on the icon
 to display or hide the input method. If more than one method is installed, a small upward
 pointing arrow is shown to the right of the icon. Click on this arrow to select a
 different input method.
 </para>
 
 <para>
 3. Running applications - if any applications are running, their icon will appear immediately
 to the right of the input method icon. Clicking on an icon will bring that application to
 the front so it can be viewed. When the application is exited, the icon will disappear from
 this area.
 </para>
 
 <para>
 4. Applets - applets are "mini" applications which appear on the right side of the Taskbar.
 Some applets provide quick access to information (e.g. PC cards installed, wireless nework,
 etc.), while others provide frequently used functions (e.g. notepad, voice memo recorder).
 Clicking on an applet's icon usually provides a menu or window to access its features.
 </para>
 
 <para>
 5. Clock - in reality just another applet, displays the current time. Clicking on the clock
 displays a dialog box which allows the time to be manually updated or syncronized over the
 Internet using the NTP protocol.
 </para>
 </section>
 
 <section><title>Dialogs</title>
 <para>
 In &opie;, dialogs, as well as some applications, have a button labeled "Ok" on
 the right side of the window title bar, in addition to the normal "x".  For 
 dialogs, the "Ok" button will apply your changes and close the window, while
 the "x" will cancel them before closing the window (for people used to most
 desktop GUI's the "Ok" and "x" behave like the "Ok" and "Cancel" buttons
 you would normally see in the bottom right of the dialog window).
 </para>
 <para>
 For applications that have an "Ok" button as well as the "x" button that all
 applications have, the "Ok" button will usually save the current file and then
 close the application, while the "x" button will close the application without
 saving.
 </para>
 </section>
 </chapter>
diff --git a/docs/usermanual/installation.sgm b/docs/usermanual/installation.sgm
index ce1d07b..d636c3c 100644
--- a/docs/usermanual/installation.sgm
+++ b/docs/usermanual/installation.sgm
@@ -1,80 +1,44 @@
-<chapter><title>Installation</title>
-<section><title>&ipaq;</title>
-<para>
-To install &opie; on an &ipaq;, a recent Familiar installation will be needed. Go to
-the Familiar project homepage (http://familiar.handhelds.org) to download the latest
-version of the "bootstrap" image (do not install the bootstrap-opie or bootstrap-gpe
-images). Follow the instructions on the Familiar website to install the image. Do not
-install the task-complete or task-x packages as they are not needed to run &opie; and
-will unnecessarily occupy space on the &ipaq;.
-</para>
+<chapter id="installation">
+  <title id="tinstallation">Installation</title>
+  <section>
+    <title>&ipaq;</title>
+    <para>To have &opie; 1.0 on an &ipaq;, you have to install a Familiar + &opie; <emphasis>image</emphasis> on your &ipaq;. An <emphasis>image</emphasis> is in fact a file, containing the memory image of an &ipaq; with Familiar (the linux distribution) and &opie; (the graphical platform) installed. You can download it from the Internet, then load it in your &ipaq; through a Compact Flash card, serial port or USB.</para>
 
-<para>
-A network connection needs to be configured on the &ipaq; in order to download the
-&opie; packages from the feed. The Familiar site provides instructions for connecting
-to the Internet in a variety of ways. 
-</para>
+    <itemizedlist>
+      <listitem><para>To start with, go to the <ulink url="http://familiar.handhelds.org/familiar/releases/v0.7.1/install/download.html">Familiar download page</ulink>.</para></listitem>
+      <listitem><para>Put the model of you &ipaq; under <quote>Please select your hardware</quote>, choose <parameter>testing, v0.7.1</parameter> as the Familiar version, and <parameter>Opie</parameter> as the set of files, and press <parameter>Download</parameter>.</para></listitem>
+      <listitem><para>Follow the <ulink url="http://familiar.handhelds.org/familiar/releases/v0.7/install/download.html">Familiar installation instructions</ulink> then, to know how to upload this image file on your &ipaq;.</para></listitem>
+    </itemizedlist>
 
-<para>
-&opie; requires the libpng3 package to be installed. Prior to installing &opie;, ensure
-that this package is installed. It is available in the Familiar feed and can be installed
-by running this command:
-<informalexample>
-<literallayout>
-     ipkg install libpng3
-</literallayout>
-</informalexample>
-</para>
+    <para>Configuring a network connection for the &ipaq; is then very useful, in order to install new packages, or upgrade existing ones (to get new features or bugfixes, for example). The Familiar site provides instructions for connecting the &ipaq; to the Internet in a variety of ways. See <ulink url="http://www.handhelds.org/z/wiki/How%20to%20setup%20networking%20between%20a%20desktop%20PC%20and%20an%20&ipaq;%20using%20the%20serial%20or%20USB%20cables">this &ipaq; networking tutorial</ulink> to have information on configuring PPP or USB, and masquerading (giving access to the Internet through your PC), for example. Setting up masquerading is even simpler on Windows, if you can adapt <ulink url="http://www.pocketpcpassion.com/General/LawrenceBates/connectwin2000.htm">this kind of tutorial for Windows</ulink>.</para>
 
-<note>
-<para>
-If you had QPE/QTopia installed previously, <emphasis>completely</emphasis> remove
-it, and then remove the source line for that feed from your /etc/ipkg.conf file before
-attempting to install &opie;.
-</para>
-</note>
-<para>
-Once you have Familiar installed (including libpng3), and the network connection
-between the &ipaq; and the outside world, run the following command:
-<informalexample>
-<literallayout>
-     echo src opie "http://opie.handhelds.org/feed/ipaq/unstable/" \
-          >> /etc/ipkg.conf
-</literallayout>
-</informalexample>
-then, run:
-<informalexample>
-<literallayout>
-     ipkg update && ipkg install task-opie
-</literallayout>
-</informalexample>
-If you have a 3100 or 3800 series &ipaq;, run:
-<informalexample>
-<literallayout>
-     ipkg install libqt2-emb-fonts
-</literallayout>
-</informalexample>
-finally, start &opie; with:
-<informalexample>
-<literallayout>
-     /etc/init.d/opie start
-</literallayout>
-</informalexample>
-</para>
+    <para>When your &ipaq; is connected to Internet, you can and should do several things, in command line, using Familiar, as noted in the <ulink url="http://familiar.handhelds.org/familiar/releases/v0.7/install/post-install.html">Familiar post-install</ulink> page, or using Opie applications.</para>
+    <itemizedlist>
+      <listitem><para>For example you can synchronize the &ipaq; clock with network time servers. There is a graphical way to do that through the <parameter>Settings</parameter> / <parameter>Date/Time</parameter> Opie application, or you can also run as root the following command:
+        <screen>
+          <userinput>ntpdate -b time.handhelds.org</userinput>
+        </screen>
+      </para></listitem>
+      <listitem><para>To teach to your &ipaq; what are the new packages or updated packages it can dowload, run the command (as root again):
+        <screen>
+          <userinput>ipkg update</userinput>
+        </screen>
+        Or use the <parameter>Settings</parameter> / <parameter>Packages</parameter> Opie graphical application.
+      </para></listitem>
+      <listitem><para>To download and install automatically new versions, if they exist, of your installed packages,
+      <screen>
+          <userinput>ipkg upgrade</userinput>
+        </screen>
+        Or use the <parameter>Package</parameter> Opie application again.
+      </para></listitem>
+    </itemizedlist>
 </section>
 
-<section><title>&zaurus;</title>
-<para>
-&opie; applications will install and run on the default &zaurus; ROM with no problems,
-except for Launcher. It is not compatible with the default ROM, and should not be
-installed.
-</para>
+  <section>
+    <title>Zaurus</title>
+    <para>&opie; applications will install and run on the default &zaurus; ROM (Linux-based distribution, as well as Familiar) with no problems,except for Launcher. It is not compatible with the default ROM, and should not be installed. You should be able to find the fine &opie; packages for you &zaurus; default ROM at this feed address: <ulink url="http://opie.handhelds.org/feed/sharprom/">http://opie.handhelds.org/feed/sharprom/</ulink>.</para>
 
-<para>
-Another option is to replace the default &zaurus; ROM with the OpenZaurus
-ROM image. OpenZaurus is a openly developed Linux distribution designed to run on the
-&zaurus;, and uses &opie; as its default user interface. For more information and
-installation instructions, please visit their site, http://www.openzaurus.org/.
-</para>
+    <para>Another option is to replace the default &zaurus; ROM with the OpenZaurus ROM image. OpenZaurus is a openly developed Linux distribution designed to run on the &zaurus;, and uses &opie; as its default user interface. For more information and installation instructions, please visit <ulink url="http://www.openzaurus.org/">OpenZaurus.org web site</ulink>. Notice you will access the Opie 1.0 feeds at the address <ulink url="http://opie.handhelds.org/feed/openzaurus/">http://opie.handhelds.org/feed/openzaurus/</ulink>.</para>
 </section>
+
 </chapter>
diff --git a/docs/usermanual/upgrading.sgm b/docs/usermanual/upgrading.sgm
index 787d4dd..a0667ab 100644
--- a/docs/usermanual/upgrading.sgm
+++ b/docs/usermanual/upgrading.sgm
@@ -1,22 +1,12 @@
 <chapter><title>Upgrading</title>
 <para>
 First, you should shutdown &opie; from the "Shutdown" app in the Settings tab.
 Normally, simply running
 <informalexample>
 <literallayout>
      ipkg update && ipkg upgrade
 </literallayout>
 </informalexample>
-will upgrade &opie;. However, if you currently have a version with the 1.5.0
-version number, you will have to upgrade it differently, because &opie; now uses a
-different version number (the 1.5.0 was Qtopia's version number, we now use our
-own). To upgrade from one of these older versions, run:
-<informalexample>
-<literallayout>
-     ipkg update
-     ipkg install opie-update
-</literallayout>
-</informalexample>
-&opie; should then be upgraded.
+will upgrade &opie;.
 </para>
 </chapter>
\ No newline at end of file
diff --git a/docs/usermanual/usermanual.sgm b/docs/usermanual/usermanual.sgm
index 7c457d7..fb4669f 100644
--- a/docs/usermanual/usermanual.sgm
+++ b/docs/usermanual/usermanual.sgm
@@ -1,103 +1,117 @@
-<!DOCTYPE book PUBLIC "-OASIS//DTD DocBook V4.2//EN" [
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN"
+[
 <!ENTITY arrow "-->">
 <!ENTITY whatis SYSTEM "whatisopie.sgm">
 <!ENTITY installation SYSTEM "installation.sgm">
 <!ENTITY gettingaround SYSTEM "gettingaround.sgm">
 <!ENTITY upgrading SYSTEM "upgrading.sgm">
 <!ENTITY contacts SYSTEM "contacts.sgm">
 <!ENTITY calendar SYSTEM "calendar.sgm">
 <!ENTITY todo SYSTEM "todo.sgm">
 <!ENTITY filemanager SYSTEM "filemanager.sgm">
 <!ENTITY embeddedkonsole SYSTEM "embeddedkonsole.sgm">
 <!ENTITY software SYSTEM "software.sgm">
 <!ENTITY today SYSTEM "today.sgm">
 <!ENTITY irda SYSTEM "irda.sgm">
 <!ENTITY keypebble SYSTEM "keypebble.sgm">
 <!ENTITY i18n SYSTEM "i18n.sgm">
 <!ENTITY kjumpx SYSTEM "kjumpx.sgm">
 <!ENTITY handwriting SYSTEM "handwriting.sgm">
 <!ENTITY multikey SYSTEM "multikey.sgm">
 <!ENTITY pickboard SYSTEM "pickboard.sgm">
 <!ENTITY calibrate SYSTEM "calibrate.sgm">
 <!ENTITY helpbrowser SYSTEM "helpbrowser.sgm">
 <!ENTITY login SYSTEM "login.sgm">
 <!ENTITY citytime SYSTEM "citytime.sgm">
 <!ENTITY textedit SYSTEM "textedit.sgm">
 <!ENTITY lightpower SYSTEM "lightpower.sgm">
 <!ENTITY reader SYSTEM "reader.sgm">
 <!ENTITY sheet SYSTEM "sheet.sgm">
 <!ENTITY write SYSTEM "write.sgm">
 <!ENTITY sysinfo SYSTEM "sysinfo.sgm">
 <!ENTITY tableviewer SYSTEM "tableviewer.sgm">
 <!ENTITY rotation SYSTEM "rotation.sgm">
 <!ENTITY appearance2 SYSTEM "appearance2.sgm">
 <!ENTITY language SYSTEM "language.sgm">
 <!ENTITY sshkeys SYSTEM "sshkeys.sgm">
 <!ENTITY appskey SYSTEM "appskey.sgm">
 <!ENTITY drawpad SYSTEM "drawpad.sgm">
 <!ENTITY qpdf SYSTEM "qpdf.sgm">
 <!ENTITY player2 SYSTEM "player2.sgm">
 <!ENTITY showimg SYSTEM "showimg.sgm">
+	<!ENTITY preface SYSTEM "preface.sgm">
 
 <!--Now the real entities-->
-<!ENTITY opie "OPIE">
+	<!ENTITY opie "Opie">
 <!ENTITY todayapp "Today">
 <!ENTITY qt "Qt">
 <!ENTITY ipaq "iPAQ">
 <!ENTITY zaurus "Zaurus">
 ]>
-<book><title>&opie; User Manual</title>
-<bookinfo><authorgroup><collab>
+<book>
+  <title>&opie; User Manual</title>
+  <bookinfo>
+    <authorgroup>
+      <collab>
 <collabname>The &opie; Team</collabname>
-</collab></authorgroup></bookinfo>
-<part><title>Getting Started</title>
+      </collab>
+    </authorgroup>
+  </bookinfo>
+  &preface;
+  <part>
+    <title>Getting Started</title>
 &whatis;
 &installation;
 &gettingaround;
 &upgrading;
 </part>
-<part><title>Applications</title>
+  <part>
+    <title>Applications</title>
 &contacts;
 &calendar;
 &todo;
 &today;
 &filemanager;
 &embeddedkonsole;
 &keypebble;
 &helpbrowser;
 &login;
 &citytime;
 &textedit;
 &reader;
 &sheet;
 &write;
 &sysinfo;
 &tableviewer;
 &qpdf;
 &drawpad;
 &player2;
 &showimg;
 </part>
-<part><title>Settings</title>
+  <part>
+    <title>Settings</title>
 &software;
 &lightpower;
 &calibrate;
 &rotation;
 &appearance2;
 &language;
 &sshkeys;
 &appskey;
 </part>
-<part><title>Applets</title>
+  <part>
+    <title>Applets</title>
 &irda;
 </part>
-<part><title>Inputmethods</title>
+  <part>
+    <title>Inputmethods</title>
 &kjumpx;
 &handwriting;
 &multikey;
 &pickboard;
 </part>
-<part><title>Technical Details</title>
+    <part>
+  <title>Technical Details</title>
 &i18n;
 </part>
 </book>
diff --git a/docs/usermanual/whatisopie.sgm b/docs/usermanual/whatisopie.sgm
index 583a9f8..ada07c0 100644
--- a/docs/usermanual/whatisopie.sgm
+++ b/docs/usermanual/whatisopie.sgm
@@ -1,17 +1,26 @@
 <chapter><title>What is &opie;?</title>
+
+<figure><title>&opie; logo</title>
+<mediaobject>
+  <imageobject>
+    <imagedata fileref="logo-small.png">
+  </imageobject>
+</mediaobject>
+</figure>
+
 <para>
-&opie; is a GUI (Graphical User Interface) for the Linux operating system (and
+<ulink url="http://opie.handhelds.org">&opie;</ulink> is a GUI (Graphical User Interface) for the Linux operating system (and
 might work on other OSes as well).  It was originally designed for handheld
 computers (such as the Compaq/HP &ipaq; and the Sharp &zaurus;), but could
-probably function well in other environments requiring a light GUI, such as an
-old laptop, or an internet kiosk.  It is based upon &qt;/Embedded from Trolltech,
+function well in other environments requiring a light GUI, such as an
+old laptop, or an internet kiosk.  It is based upon <ulink url="http://www.trolltech.com/products/embedded/index.html">&qt;/Embedded from Trolltech</ulink>,
 which is in turn a graphical environment designed for embedded applications,
 based upon the &qt; toolkit.
 </para>
 <para>
 &opie; has been designed for devices with small screens, and a touchscreen input
 device (ie, only one mouse click, and no constant mouse position), as well as
 designed to fit in a relatively small amount of storage space (about 5 megabytes
 for the base libraries and the launcher).
 </para>
 </chapter>