Add additional documentation from Debian into Qt3 tree

This closes Bug 673

12 files changed, 448 insertions, 0 deletions

diff --git a/doc/man/README b/doc/man/README
new file mode 100644
index 0000000..de4ddcd
--- /dev/null
+++ b/doc/man/README
@@ -0,0 +1,49 @@
+-------
+INSTALL
+-------
+
+Those man pages are not yet installed by 'make install'.
+They have to be installed in $MANPATH/man1 and in $MANPATH/man3.
+(See INSTALL in the top directory).
+
+Example:
+If qt3 has been installed in /usr/local and if MANPATH is
+/usr/local/share/man, they can be installed with the following commands:
+    install -m 644 man1/* /usr/local/share/man/man1
+    install -m 644 man3/* /usr/local/share/man/man3
+Change the commands to suit your needs.
+
+----
+TODO
+----
+
+* installation with qmake.
+* optional man pages compression with qmake
+
+-------
+ORIGINS
+-------
+
+Trolltech-Nokia original sources
+    (http://get.qt.nokia.com/qt/source/qt-x11-free-3.3.8b.tar.gz)
+  man1/lrelease.1
+  man1/lupdate.1
+  man1/moc.1
+  man1/uic.1
+  man3/*
+
+Debian distribution
+    (http://ftp.de.debian.org/debian/pool/main/q/qt-x11-free/)
+        qt-x11-free_3.3.8b-11.*
+        qt-x11-free_3.3.8b.orig.tar.gz
+  man1/createcw.1
+  man1/designer.1
+  man1/findtr.1
+  man1/linguist.1
+  man1/makeqpf.1
+  man1/mergetr.1
+  man1/msg2qm.1
+  man1/qembed.1
+  man1/qt20fix.1
+  man1/qtconfig.1
+  man1/qvfb.1
diff --git a/doc/man/man1/createcw.1 b/doc/man/man1/createcw.1
new file mode 100644
index 0000000..0959a2d
--- /dev/null
+++ b/doc/man/man1/createcw.1
@@ -0,0 +1,57 @@
+.TH "createcw" "1" "3.0.3" "Troll Tech AS, Norway." ""
+.SH "NAME"
+.LP 
+createcw \- custom widget description creater for Qt Designer
+.SH "SYNTAX"
+.LP 
+createcw <\fIfilename.cw\fP>
+.SH "DESCRIPTION"
+.LP 
+This small application makes it much easier to create
+custom widget descriptions for the Qt Designer. Using
+them you can use custom widgets in the Qt Designer
+including their signals, slots and properties.
+ 
+To do that normally you would have to enter all that
+information in the custom widget dialog in the Qt
+Designer for each widget. But this small tool can create
+for you these description files for your custom widgets
+which you then can simply import into the Qt Designer. So
+you can use your custom widgets without any additional
+work in your forms in the Qt Designer then.
+
+To do that you have to modify the sourcecode (main.cpp) a
+bit and recompile it afterwards. 
+
+STEP1: Include header files of the widgets for which a
+description should be created here. If you have a widget
+which is defined in the file mycustomwidget.h in
+/home/joedeveloper/src, write here 
+
+#include "/home/joedeveloper/src/mycustomwidget.h"
+
+STEP2: Instantiate all widgets for which a description
+should be created here and add them to the list wl. If
+your custom widget is e.g. called MyCustomWidget you
+would write here
+
+ Widget w;
+ w.w = new MyCustomWidget( 0, 0 );
+ w.include = "mycustomwidget.h";
+ w.location = "global";
+ wl.append( w );
+
+After that compile the program, link it with your custom
+widget (library or object file) and run it like this:
+
+ (unix): ./createcw mywidgets.cw
+ (win32): createcw mywidgets.cw
+
+After that you can import this description file into the
+Qt Designer using the Custom\-Widget Dialog (See
+Tools\->Custom\->Edit Custom Widgets... in the Qt Designer)
+and use these custom widget there in your forms.
+
+.SH "AUTHORS"
+.LP 
+Troll Tech <http://www.trolltech.com/>
diff --git a/doc/man/man1/designer.1 b/doc/man/man1/designer.1
new file mode 100644
index 0000000..4151e94
--- /dev/null
+++ b/doc/man/man1/designer.1
@@ -0,0 +1,54 @@
+.TH "qt-designer" "1" "3.0.3" "Troll Tech AS, Norway." ""
+.SH "NAME"
+.LP 
+qt\-designer \- Visual user interface designer for Qt.
+.SH "DESCRIPTION"
+.LP 
+Qt Designer simplifies the process of designing and
+creating graphical user interfaces (GUI) using the
+award\-winning Qt toolkit. Qt Designer is easy to learn.
+There are tutorials, walkthrough examples and the
+reference documentation accelerating you through the
+learning phase. After that, Qt Designer greatly reduces
+the time and effort needed to develop even the most
+complex dialogs with an easy\-to\-use GUI and an integrated
+help system.
+
+ Qt Designer provides a rich set of features aimed at
+making the creation of dialogs as easy and smooth as
+possible without reducing the power of Qt. It offers all
+the strength of the Qt layout system with a well\-designed
+user interface. This, combined with the Qt Designer's
+undo/redo system makes it simple to try different
+arrangements of the widgets until the result satisfies
+you.
+
+ Using Qt Designer's convenient property editor along
+with the dynamic Qt property system it is easy to set the
+initial state of your widgets. Special editors for some
+widgets (like listboxes, comboboxes, etc.) allow you to
+fill these widgets with content without writing any code.
+Using the object hierarchy view, the parent\-child
+relationship between the widgets of a dialog can be
+understood at a glance.
+
+ Integrating dialogs into a Qt project is straightforward
+thanks to the User Interface Compiler (UIC), which
+generates C++ code from the XML dialog description on the
+fly. The programmer can easily extend the functionality
+of the generated classes by subclassing without touching
+generated code at all or running the risk of loosing
+their changes.
+.SH "FILES"
+.LP 
+\fI/usr/share/qt/tools/designer/*\fP 
+.SH "ENVIRONMENT VARIABLES"
+.LP 
+.TP 
+\fBQTDIR\fP
+Specifies the Qt base directory.  On Debian systems this
+should be set to /usr/share/qt.  The /usr/bin/designer
+wrapper script takes care of this.
+.SH "AUTHORS"
+.LP 
+TrollTech <http://www.trolltech.com/>
diff --git a/doc/man/man1/findtr.1 b/doc/man/man1/findtr.1
new file mode 100644
index 0000000..f1d3a87
--- /dev/null
+++ b/doc/man/man1/findtr.1
@@ -0,0 +1,25 @@
+.TH "findtr" "1" "3.0.3" "Troll Tech AS, Norway." ""
+.SH "NAME"
+.LP 
+findtr \- Extracts information about text to be translated
+.SH "SYNTAX"
+.LP 
+findtr *.cpp *.h >myapp.po
+.SH "DESCRIPTION"
+.LP 
+
+Extracts information about text to be translated. It
+recognizes the tr() constructs described above and
+produces a file in ".po" format, a simple text format
+that your translation team will copy and edit. For
+example, the base .po file might be myapp.po and
+translated versions of the file would then be
+myapp_de.po, myapp_fr.po, and myapp_ja.po for
+translations in German, French and Japanese respectively.
+
+  findtr *.cpp *.h >myapp.po
+  copy myapp.po myapp_de.po
+  edit myapp_de.po
+.SH "AUTHORS"
+.LP 
+TrollTech <http://www.trolltech.com/>
diff --git a/doc/man/man1/linguist.1 b/doc/man/man1/linguist.1
new file mode 100644
index 0000000..a0f9913
--- /dev/null
+++ b/doc/man/man1/linguist.1
@@ -0,0 +1,37 @@
+.TH LINGUIST 1 "28 August 2004"
+.SH "NAME"
+linguist \- Translation tool for Qt.
+
+.SH "SYNPOSIS"
+.B linguist
+[
+.I TRANSLATION
+]
+
+.SH "DESCRIPTION"
+.B Qt Linguist
+is a tool for adding translations to Qt applications. It
+introduces the concept of a translation "context" which
+means a group of phrases that appear together on the
+screen e.g. in the same menu or dialog.
+
+The only parameter accepted on the command line is 
+.I TRANSLATION
+wich is the name of the translation file you wish to open.
+
+.SH FILES
+.I ~/.qt/qt_designerrc
+.RS
+Per user configuration file.
+
+.SH SEE ALSO
+.B Qt Linguist
+is too complex to be described completely in the "man" page
+format. If your system is properly configured, you can access
+the full documentation within
+.B Qt Linguist
+under the Help menu.
+
+.SH AUTHOR
+This manual page was written by Jeremy Laine <[email protected]>,
+for the Debian GNU/Linux system (but may be used by others).
diff --git a/doc/man/man1/makeqpf.1 b/doc/man/man1/makeqpf.1
new file mode 100644
index 0000000..37ddcfd
--- /dev/null
+++ b/doc/man/man1/makeqpf.1
@@ -0,0 +1,26 @@
+.TH "makeqpf" "1" "3.0.3" "Troll Tech AS, Norway." ""
+.SH "NAME"
+.LP 
+makeqpf \- Create qpf files from TTF and BDF files.
+.SH "DESCRIPTION"
+.LP 
+Qt Prerendered Font (QPF) is a light\-weight non\-scalable
+font format specific to Qt/Embedded.  makeqpf is a tool
+that assists producing QPF files from TTF and BDF files.
+
+
+.SH "SYNTAX"
+qembed [ \fIgeneral\-files\fP ] <[ \fI\-\-images image\-files \fP]>
+.br 
+
+general\-files 
+  These files can be any type of file. 
+\-\-images image\-files 
+  These files must be in image formats supported by Qt. 
+
+.SH "FILES"
+.LP 
+\fI$(QTDIR)/etc/fonts/fontdir\fP 
+.SH "AUTHORS"
+.LP 
+TrollTech <http://www.trolltech.com/>
diff --git a/doc/man/man1/mergetr.1 b/doc/man/man1/mergetr.1
new file mode 100644
index 0000000..9ed2a9f
--- /dev/null
+++ b/doc/man/man1/mergetr.1
@@ -0,0 +1,27 @@
+.TH "mergetr" "1" "3.0.3" "Troll Tech AS, Norway." ""
+.SH "NAME"
+.LP 
+mergetr \- Merge changes in translations
+.SH "SYNTAX"
+.LP 
+mergetr myapp_de.po myapp.po
+
+.SH "DESCRIPTION"
+.LP 
+When the texts in your program change as it is developed,
+a the base .po file can be regenerated using findtr,
+then mergetr can be used to merge the changes into the
+other .po files: 
+
+                mergetr myapp_de.po myapp.po
+                mergetr myapp_fr.po myapp.po
+                mergetr myapp_ja.po myapp.po
+
+
+The translation team then edits the new .po files to
+translate the new or changed texts. When texts change,
+the old text is included in the .po file as a comment to
+guide the new translation (no "fuzzy" matching is done).
+.SH "AUTHORS"
+.LP 
+TrollTech <http://www.trolltech.com/>
diff --git a/doc/man/man1/msg2qm.1 b/doc/man/man1/msg2qm.1
new file mode 100644
index 0000000..7d22bbb
--- /dev/null
+++ b/doc/man/man1/msg2qm.1
@@ -0,0 +1,26 @@
+.TH "msg2qm" "1" "3.0.3" "Troll Tech AS, Norway." ""
+.SH "NAME"
+.LP 
+msg2qm \- Converts translated .po files to a Qt\-specific binary format.
+.SH "SYNTAX"
+.LP 
+msg2qm myapp_de.po myapp_de.qm
+.SH "DESCRIPTION"
+.LP 
+
+Converts translated .po files to a Qt\-specific binary
+format (".qm" Qt message files). The Qt message files
+are platform and locale independent, containing
+translations in Unicode and various hash tables to
+provide fast look\-up. 
+
+                msg2qm myapp_de.po myapp_de.qm
+                msg2qm myapp_fr.po myapp_fr.qm
+                msg2qm myapp_ja.po myapp_ja.qm
+
+
+In your application, use QTranslator::load() to load
+translation files appropriate for the user's language.
+.SH "AUTHORS"
+.LP 
+TrollTech <http://www.trolltech.com/>
diff --git a/doc/man/man1/qembed.1 b/doc/man/man1/qembed.1
new file mode 100644
index 0000000..a9b262f
--- /dev/null
+++ b/doc/man/man1/qembed.1
@@ -0,0 +1,32 @@
+.TH "qembed" "1" "3.0.3" "Troll Tech AS, Norway." ""
+.SH "NAME"
+.LP 
+qembed \- Converts arbitrary files into C++ code.
+.SH "DESCRIPTION"
+.LP 
+The QEmbed tool, found in qt/tools/qembed, converts
+arbitrary files into C++ code. This is useful for
+including image files and other resources directly into
+your application rather than loading the data from
+external files. 
+
+QEmbed can also generate uncompressed versions of images
+that can be included directly into your application,
+thus avoiding both the external file and the need to
+parse the image file format. This is useful for small
+images such as icons for which compression is not a
+great gain. 
+
+
+.SH "SYNTAX"
+qembed [ \fIgeneral\-files\fP ] <[ \fI\-\-images image\-files \fP]>
+.br 
+
+general\-files 
+  These files can be any type of file. 
+\-\-images image\-files 
+  These files must be in image formats supported by Qt. 
+
+.SH "AUTHORS"
+.LP 
+TrollTech <http://www.trolltech.com/>
diff --git a/doc/man/man1/qt20fix.1 b/doc/man/man1/qt20fix.1
new file mode 100644
index 0000000..352921b
--- /dev/null
+++ b/doc/man/man1/qt20fix.1
@@ -0,0 +1,32 @@
+.TH "qt20fix" "1" "3.0.3" "Troll Tech AS, Norway." ""
+.SH "NAME"
+.LP 
+qt20fix \- Helps clean namespace when porting an app from Qt1 to Qt2
+.SH "SYNTAX"
+.LP 
+qt20fix myapp.cpp
+
+.SH "DESCRIPTION"
+.LP 
+Qt 2.x is namespace\-clean, unlike 1.x. Qt now uses very
+few global identifiers. Identifiers like red, blue,
+LeftButton, AlignRight, Key_Up, Key_Down, NoBrush etc.
+are now part of a special class Qt (defined in
+qnamespace.h), which is inherited by most Qt classes.
+Member functions of classes that inherit from QWidget,
+etc. are totally unaffected, but code that is not in
+functions of classes inherited from Qt, you must qualify
+these identifiers like this: Qt::red, Qt::LeftButton,
+Qt::AlignRight, etc. 
+
+The qt/bin/qt20fix script helps to fix the code that
+needs adaption, though most code does not need changing.
+
+Compiling with \-DQT1COMPATIBILITY will help you get going
+with Qt 2.x \- it allows all the old "dirty namespace"
+identifiers from Qt 1.x to continue working. Without it,
+you'll get compile errors that can easily be fixed by
+searching this page for the clean identifiers. 
+.SH "AUTHORS"
+.LP 
+TrollTech <http://www.trolltech.com/>
diff --git a/doc/man/man1/qtconfig.1 b/doc/man/man1/qtconfig.1
new file mode 100644
index 0000000..7e03bf4
--- /dev/null
+++ b/doc/man/man1/qtconfig.1
@@ -0,0 +1,17 @@
+.TH "qtconfig" "1" "3.0.3" "Troll Tech AS, Norway." ""
+.SH "NAME"
+.LP 
+qtconfig \- Configuration tool for Qt
+.SH "DESCRIPTION"
+.LP 
+QConfig allows for GUI based configuration of Qt and
+ other Qt based sources.
+
+.SH "ENVIRONMENT VARIABLES"
+.LP 
+.TP 
+\fBQTDIR\fP
+Specifies the base Qt dir
+.SH "AUTHORS"
+.LP 
+TrollTech <http://www.trolltech.com/>
diff --git a/doc/man/man1/qvfb.1 b/doc/man/man1/qvfb.1
new file mode 100644
index 0000000..0ae800d
--- /dev/null
+++ b/doc/man/man1/qvfb.1
@@ -0,0 +1,66 @@
+.TH "qvfb" "1" "3.0.3" "Troll Tech AS, Norway." ""
+.SH "NAME"
+.LP 
+qvfb \- Virtual framebuffer for Qt
+.SH "DESCRIPTION"
+.LP 
+The virtual framebuffer allows Qt/Embedded programs to be
+developed on your desktop machine, without switching
+between consoles and X11. 
+
+Start a Qt/Embedded master application (i.e., construct
+QApplication with QApplication::GuiServer flag or use the
+\-qws command line parameter). You will need to specify to
+the server that you wish to use the virtual framebuffer
+driver, e.g.: 
+
+    widgets \-qws \-display QVFb:0
+    
+You may prefer to set the QWS_DISPLAY environment
+variable to be QVFb:0. 
+
+qvfb supports the following command line options: 
+
+ \-width width: the width of the virtual framebuffer
+  (default: 240). 
+ \-height height: the height of the virtual framebuffer
+  (default: 320). 
+ \-depth depth: the depth of the virtual framebuffer (1, 8
+  or 32; default: 8). 
+ \-nocursor: do not display the X11 cursor in the
+  framebuffer window. 
+ \-qwsdisplay :id the Qt/Embedded display id to provide
+  (default: 0). 
+
+ Virtual Framebuffer Design 
+
+The virtual framebuffer emulates a framebuffer using a
+shared memory region (the virtual frame buffer) and a
+utility to display the framebuffer in a window (qvfb).
+The regions of the display that have changed are updated
+periodically, so you will see discrete snapshots of the
+framebuffer rather than each individual drawing
+operation. For this reason drawing problems such as
+flickering may not be apparent until the program is run
+using a real framebuffer. 
+
+The target refresh rate can be set via the "View|Refresh
+Rate" menu item. This will cause qvfb to check for
+updated regions more quickly. The rate is a target only.
+If little drawing is being done, the framebuffer will not
+show any updates between drawing events. If an
+application is displaying an animation the updates will
+be frequent, and the application and qvfb will compete
+for processor time. 
+
+Mouse and keyboard events are passed to the Qt/Embedded
+master process via named pipes. 
+
+The virtual framebuffer is a development tool only. No
+security issues have been considered in the virtual
+framebuffer design. It should be avoided in a production
+environment; QT_NO_QWS_VFB should always be defined in
+production libraries. 
+.SH "AUTHORS"
+.LP 
+TrollTech <http://www.trolltech.com/>