[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
gnue/gnuef/doc user_guide.lyx
From: |
Jason Cater |
Subject: |
gnue/gnuef/doc user_guide.lyx |
Date: |
Wed, 14 Nov 2001 23:43:37 -0500 |
CVSROOT: /home/cvs
Module name: gnue
Changes by: Jason Cater <address@hidden> 01/11/14 23:43:36
Modified files:
gnuef/doc : user_guide.lyx
Log message:
changes to user guide
CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/gnue/gnuef/doc/user_guide.lyx.diff?cvsroot=OldCVS&tr1=1.2&tr2=1.3&r1=text&r2=text
Patches:
Index: gnue/gnuef/doc/user_guide.lyx
diff -u gnue/gnuef/doc/user_guide.lyx:1.2 gnue/gnuef/doc/user_guide.lyx:1.3
--- gnue/gnuef/doc/user_guide.lyx:1.2 Wed Nov 14 20:01:48 2001
+++ gnue/gnuef/doc/user_guide.lyx Wed Nov 14 23:43:36 2001
@@ -38,8 +38,8 @@
Introduction
\layout Standard
-GNUE Forms aims to be the primary user interface to the GNU Enterprise system.
- It is comprised of two systems.
+GNUe Forms aims to be the primary user interface to the GNU Enterprise system.
+ It is comprised of two components: GNUe Forms and GNUe Designer.
GNUe Forms is responsible for displaying output and accepting user input.
GNUe Designer allows a developer to produce the XML based form definition
files (gfd files) utilized by GNUe Forms.
@@ -57,14 +57,14 @@
\layout Enumerate
Download the latest version of the GNUe Forms binary from the download section
- of www.gnue.org.
+ of http://www.gnue.org/.
No additional downloads are required.
\lang english
\layout Enumerate
-Double click and follow the instructions on the screen.
+Double-click and follow the instructions on the screen.
Note: GNUe Forms can be installed on a network drive.
A network install does
\series bold
@@ -78,7 +78,7 @@
\backslash
Program Files
\backslash
-gnue
+GNUe
\backslash
etc
\backslash
@@ -91,18 +91,18 @@
Unix Install
\layout Standard
-The easiest way to install GNUe Forms on a unix system is from the source
+The easiest way to install GNUe Forms on a UNIX system is via the source
code.
RPMs and Debian packages are currently not available.
\layout Enumerate
-Download the latest version of the GNUe Forms binary from the download section
- of www.gnue.org.
+Download the latest version of the GNUe Forms tarball from the download
+ section of http://www.gnue.org.
You will also need to download the gnue-common package as well.
\layout Enumerate
Expand and install the gnue-common package.
- Detailed instructions are included in the tarballs INSTALL file.
+ Detailed instructions are included in the tarball's INSTALL file.
The most basic install of this package is accomplished via the command
\newline
@@ -113,12 +113,13 @@
\newline
\series default
-Note: As part of the gnue-common install be sure and install any required
- python database drivers to meet your sites requirements.
+Note: As part of the gnue-common install, be sure to install any required
+ python database drivers to meet your sites requirements (see the
README.database
+s for a list of necessary drivers).
\layout Enumerate
Next expand and install the gnue-forms package.
- Detailed instructions are included in the tarballs INSTALL file.
+ Detailed instructions are included in the tarball's INSTALL file.
The most basic install of this package is accomplished via the command
\newline
@@ -127,25 +128,39 @@
\layout Enumerate
Edit gnue.conf and connections.conf files to reflect your site's requirements.
- The default installation location of these files is
-\backslash
-usr
-\backslash
-local
-\backslash
-gnue
-\backslash
-etc
-\backslash
-
+ The default installation location of these files is /usr/local/gnue/etc/.
\layout Section
Configuration
\layout Standard
-Configuration of GNUe Forms is the same for all platforms.
- The files gnue.conf and connections.conf may both require customizations
- before you can begin to use GNUe Forms.
+The configuration of GNUe Forms is the same on all platforms.
+ The files
+\begin_inset Quotes eld
+\end_inset
+
+gnue.conf
+\begin_inset Quotes erd
+\end_inset
+
+ and
+\begin_inset Quotes eld
+\end_inset
+
+connections.conf
+\begin_inset Quotes erd
+\end_inset
+
+ may both require customizations before you can begin to use GNUe Forms.
+ The file
+\begin_inset Quotes eld
+\end_inset
+
+gnue.conf
+\begin_inset Quotes erd
+\end_inset
+
+ uses
\layout Subsection
Customizing connections.conf
@@ -191,41 +206,18 @@
Valid Parameters
\layout Description
-connection This parameter specifies a connection string to be used by the
- database provider.
- The format of the connection string is provider dependent and not all
providers
- recoognize this parameter.
-
-\newline
-
-\newline
-In most implementations, a connection string can be used in place of the
- "dbname" and "host" parameters.
-
-\newline
-
-\newline
-Example (for an ODBC connection):
-\newline
-connection = "Driver={mySQL};Server=localhost;Database=gnue;"
-\newline
-
-\newline
-This parameter has no default and is not required unless implemented as
- such by the provider.
-\layout Description
-
comment This parameter is a text field that is seen in a list of available
connections.
The comment should provide more information regarding the connection than
the connection name.
-
+ If supplied, it is also displayed in the Login process as the name of the
+ connect
\newline
Example (for a connection named "acctaud"):
\newline
\newline
-comment = Accounting's Audit Trail Database
+comment = Accounting's Audit Trail
\newline
\newline
@@ -300,6 +292,37 @@
\series default
Replace this with something usefull instead of directing to a new file.
Maybe an appendix?
+\layout Description
+
+service This parameter specifies a connection string to be used by the database
+ provider.
+ The format of the connection string is provider dependent and not all
providers
+ recoognize this parameter.
+
+\newline
+
+\newline
+Usually, a database driver will support either a
+\begin_inset Quotes eld
+\end_inset
+
+service
+\begin_inset Quotes erd
+\end_inset
+
+ parameter or a combination of the "dbname" and "host" parameters.
+
+\newline
+
+\newline
+Example (for an ODBC connection):
+\newline
+connection = "MyDSN"
+\newline
+
+\newline
+This parameter has no default and is not required unless implemented as
+ such by the provider.
\layout Subsection
Customizing gnue.conf
@@ -307,17 +330,134 @@
The options in gnue.conf typically do not require any adjustment.
+\layout Chapter
+
+GNUe Forms Basics
+\layout Subsection
+
+Overview
+\layout Standard
+
+Let's talk about recipes for a minute.
+ Think about a recipe collection in which each recipe is written on a single
+ card.
+ Each recipe card has a certain set of information (ingredients, instructions,
+ baking time) about that (and only that) recipe.
+ If you want to look up a recipe, you retrieve the corresponding recipe
+ card.
+ If you find out you're allergic to that recipe, you would throw out that
+ card (and only that card).
+ If you discover that baking the recipe for 40 minutes burns the dish, you
+ might change the baking time on the card to 30 minutes.
+ Most of the time, you only need to reference a card so you can bake that
+ dish.
+
+\layout Standard
+
+GNUe Forms acts like a window into your recipe collection.
+ To Forms, your recipe collection is the
+\begin_inset Quotes eld
+\end_inset
+
+database
+\begin_inset Quotes erd
+\end_inset
+
+.
+ Each recipe card is a
+\begin_inset Quotes eld
+\end_inset
+
+record
+\begin_inset Quotes erd
+\end_inset
+
+.
+ In the Forms world, searching through your collection for specific recipes
+ is
+\begin_inset Quotes eld
+\end_inset
+
+querying
+\begin_inset Quotes erd
+\end_inset
+
+.
+ Changing the baking time on a card is
+\begin_inset Quotes eld
+\end_inset
+
+updating a record
+\begin_inset Quotes erd
+\end_inset
+
+.
+ Adding a recipe that your mother gave you is
+\begin_inset Quotes eld
+\end_inset
+
+inserting a record
+\begin_inset Quotes erd
+\end_inset
+
+.
+ Finally, throwing away that recipe card is
+\begin_inset Quotes eld
+\end_inset
+
+deleting a record.
+\begin_inset Quotes erd
+\end_inset
+
+
+\layout Standard
+
+However, being in a computer system, there is one nice difference from your
+ boxed recipe collection.
+ Your updated baking time, the trashed recipe card, and your mom's addition
+ to your collection are not permanent changes to your collection until you
+ save, or in Forms lingo,
+\begin_inset Quotes eld
+\end_inset
+
+commit
+\begin_inset Quotes erd
+\end_inset
+
+, your data.
+ If you change your mind
+\emph on
+before
+\emph default
+
+\begin_inset Quotes eld
+\end_inset
+
+committing
+\begin_inset Quotes erd
+\end_inset
+
+ your changes, a simple
+\begin_inset Quotes eld
+\end_inset
+
+rollback
+\begin_inset Quotes erd
+\end_inset
+
+ will undo any changes you've made to your collection.
+
\layout Section
-A GNU Forms session
+A GNUe Forms session
\layout Subsection
Starting GNUe Forms
\layout Standard
Depending upon your platform GNUe Forms can either be ran as a command line
- application called gfclient or it may be an icon or menu pick someone has
- setup for your use.
+ application called gfclient or it may be an icon or menu option someone
+ has setup for your use.
We'll cover the basic command line execution of gfclient here.
\layout Standard
@@ -328,17 +468,16 @@
that it be passed a GNUe Forms Definition file (a gfd file) at startup.
The file could be local or available over the web.
Examples
-\layout Standard
+\layout Itemize
-A gfd file stored on a web server and accessed via a command similar to
-
-\layout Standard
+A gfd file stored on a web server and accessed via a command similar to:
+\layout LyX-Code
gfclient http://www.example.org/sales/customer.gfd
-\layout Standard
+\layout Itemize
-A gfd file stored on the local users hard drive
-\layout Standard
+A gfd file stored on the local hard drive:
+\layout LyX-Code
gfclient C:
\backslash
@@ -350,38 +489,50 @@
Symlinks
\layout Standard
-Unix users have a 3rd method of starting gfclient via symlinks to simplify
- execution of forms.
+Unix users have a 3rd method of starting gfclient via symbolic links (symlinks)
+ to simplify execution of forms.
The easiest way to describe this is by example.
\layout Standard
-If you have a form called contacts.gfd in the default location (specified
+Suppose you have a form, contacts.gfd, in the default location (specified
in gnue.conf).
- Then by placing into your path a symbolic link called contacts
-\emph on
-
-\emph default
-which points to the gfclient executable you will be able to execute the
- file by simply typing contacts.
-\newline
+ By placing a symlink called
+\begin_inset Quotes eld
+\end_inset
-\newline
+contacts
+\begin_inset Quotes erd
+\end_inset
+
+ somewhere in your path that points back to gfclient, you are able to simply
+ run
+\begin_inset Quotes eld
+\end_inset
+
+contacts
+\begin_inset Quotes erd
+\end_inset
+
+ and have it run the contacts.gfd form.
+ Or, put more simply, the following:
+\layout LyX-Code
+
bash-2.03$ ln -s /usr/local/bin/gfclient /usr/local/bin/contacts
-\newline
+\layout LyX-Code
+
bash-2.03$ contacts
-\newline
+\layout Standard
-\emph on
-The form /usr/local/gnue/forms/contacts.gfd will now be displayed
+will display the form /usr/local/gnue/forms/contacts.gfd .
\layout Subsection
Login Dialog
\layout Standard
Databases and application servers tend to require the user to prove their
- idenity, or authenticate themselves, prior to being allowed access to the
- data they contain.
- When a system requires authentication GNUe Forms will present the user
+ identity, or authenticate themselves, prior to being allowed access to
+ the data they contain.
+ When a system requires authentication, GNUe Forms will present the user
with a Login Dialog that looks similar to the following example.
\layout Standard
\added_space_top 0.3cm \added_space_bottom 0.3cm \align center
@@ -399,8 +550,14 @@
site and the system being accessed.
Typically you have up to four attempts to correctly authenticate yourself
with the system.
- After four unsuccessful attempts GNUe Forms will abort and you'll have
+ After four unsuccessful attempts, GNUe Forms will abort and you'll have
to start the process over.
+\layout Standard
+
+If your form connects to more than one backend server, you may be presented
+ with more than one login dialog.
+ This is because each server must authenticate you according to their
standards.
+ In a typical environment, this will not happen.
\layout Subsection
The Main Screen
@@ -409,7 +566,8 @@
Entering Data
\layout Standard
-GNUe Forms treats all data entered into it as what we call records.
+Data is entered into a record.
+ Records are groups of related information that are stored together.
\layout Subsection
@@ -419,6 +577,15 @@
To save any new or altered data contained in the form you must perform what
we call a commit.
Performing a commit also removes any information you have marked as deleted.
+ You are
+\begin_inset Quotes eld
+\end_inset
+
+committing
+\begin_inset Quotes erd
+\end_inset
+
+ any changes you have made.
\layout Subsection
Retrieving Data
@@ -439,6 +606,28 @@
\layout Subsection
Deleting Records
+\layout Standard
+
+To discard a record from the system, you must
+\begin_inset Quotes eld
+\end_inset
+
+delete
+\begin_inset Quotes erd
+\end_inset
+
+ that record.
+ Deleting a record does not
+\begin_inset Quotes eld
+\end_inset
+
+hide
+\begin_inset Quotes erd
+\end_inset
+
+ the data from your screen.
+ Rather, it removes that information from your system permanently.
+
\layout Subsection
Navigating Records
@@ -448,4 +637,234 @@
\layout Subsection
Printing Data
+\layout Chapter
+\start_of_appendix
+Database Support
+\layout Standard
+
+James' summary of databases
+\layout Chapter
+
+Command Line Options
+\layout Standard
+
+GNUe Form's gfclient accepts a variety of command line options.
+ These options can always be viewed by typing:
+\layout LyX-Code
+
+gfclient --help
+\layout Standard
+
+at a command prompt.
+\layout Subsubsection
+
+
+\begin_inset Tabular
+<lyxtabular version="2" rows="9" columns="2">
+<features rotate="false" islongtable="false" endhead="0" endfirsthead="0"
endfoot="0" endlastfoot="0">
+<column alignment="left" valignment="top" leftline="false" rightline="false"
width="" special="">
+<column alignment="left" valignment="top" leftline="false" rightline="false"
width="" special="">
+<row topline="false" bottomline="false" newpage="false">
+<cell multicolumn="0" alignment="center" valignment="top" topline="true"
bottomline="false" leftline="true" rightline="false" rotate="false"
usebox="none" width="" special="">
+\begin_inset Text
+
+\layout Standard
+
+--connections <loc>
+\end_inset
+</cell>
+<cell multicolumn="0" alignment="left" valignment="top" topline="false"
bottomline="false" leftline="false" rightline="false" rotate="false"
usebox="none" width="" special="">
+\begin_inset Text
+
+\layout Standard
+
+Specifies an alternate location of a connection definition file.
+ <loc> may specify a file name (/usr/local/gnue/etc/connections.conf), or
+ a URL location (http://localhost/connections.conf).
+ If thisoption is not specified, the environent variable GNUE_CONNECTIONS
+ is checked.
+\end_inset
+</cell>
+</row>
+<row topline="false" bottomline="false" newpage="false">
+<cell multicolumn="0" alignment="center" valignment="top" topline="true"
bottomline="false" leftline="true" rightline="false" rotate="false"
usebox="none" width="" special="">
+\begin_inset Text
+
+\layout Standard
+
+--debug-file <file>
+\end_inset
+</cell>
+<cell multicolumn="0" alignment="left" valignment="top" topline="false"
bottomline="false" leftline="false" rightline="false" rotate="false"
usebox="none" width="" special="">
+\begin_inset Text
+
+\layout Standard
+
+Sends all debugging messages to a specified file (e.g., "--debug-file
trace.log"
+ sends all output to "trace.log")
+\end_inset
+</cell>
+</row>
+<row topline="false" bottomline="false" newpage="false">
+<cell multicolumn="0" alignment="center" valignment="top" topline="true"
bottomline="false" leftline="true" rightline="false" rotate="false"
usebox="none" width="" special="">
+\begin_inset Text
+
+\layout Standard
+
+--debug-level <level>, -d
+\end_inset
+</cell>
+<cell multicolumn="0" alignment="left" valignment="top" topline="false"
bottomline="false" leftline="false" rightline="false" rotate="false"
usebox="none" width="" special="">
+\begin_inset Text
+
+\layout Standard
+
+Enables debugging messages.
+ Argument specifies the level of messages to display (e.g., "-d5" displays
+ all debugging messages at level 5 or below.)
+\end_inset
+</cell>
+</row>
+<row topline="false" bottomline="false" newpage="false">
+<cell multicolumn="0" alignment="center" valignment="top" topline="true"
bottomline="false" leftline="true" rightline="false" rotate="false"
usebox="none" width="" special="">
+\begin_inset Text
+
+\layout Standard
+
+--help
+\end_inset
+</cell>
+<cell multicolumn="0" alignment="left" valignment="top" topline="false"
bottomline="false" leftline="false" rightline="false" rotate="false"
usebox="none" width="" special="">
+\begin_inset Text
+
+\layout Standard
+
+Displays a help screen.
+\end_inset
+</cell>
+</row>
+<row topline="false" bottomline="false" newpage="false">
+<cell multicolumn="0" alignment="center" valignment="top" topline="true"
bottomline="false" leftline="true" rightline="false" rotate="false"
usebox="none" width="" special="">
+\begin_inset Text
+
+\layout Standard
+
+--no_splash, -s
+\end_inset
+</cell>
+<cell multicolumn="0" alignment="left" valignment="top" topline="false"
bottomline="false" leftline="false" rightline="false" rotate="false"
usebox="none" width="" special="">
+\begin_inset Text
+
+\layout Standard
+
+Disables the splash screen.
+\end_inset
+</cell>
+</row>
+<row topline="false" bottomline="false" newpage="false">
+<cell multicolumn="0" alignment="center" valignment="top" topline="true"
bottomline="false" leftline="true" rightline="false" rotate="false"
usebox="none" width="" special="">
+\begin_inset Text
+
+\layout Standard
+
+--profile
+\end_inset
+</cell>
+<cell multicolumn="0" alignment="left" valignment="top" topline="false"
bottomline="false" leftline="false" rightline="false" rotate="false"
usebox="none" width="" special="">
+\begin_inset Text
+
+\layout Standard
+
+Run Python's built-in profiler and display the resulting run statistics.
+\end_inset
+</cell>
+</row>
+<row topline="false" bottomline="false" newpage="false">
+<cell multicolumn="0" alignment="center" valignment="top" topline="true"
bottomline="false" leftline="true" rightline="false" rotate="false"
usebox="none" width="" special="">
+\begin_inset Text
+
+\layout Standard
+
+--user_interface <type>, -u
+\end_inset
+</cell>
+<cell multicolumn="0" alignment="left" valignment="top" topline="false"
bottomline="false" leftline="false" rightline="false" rotate="false"
usebox="none" width="" special="">
+\begin_inset Text
+
+\layout Standard
+
+The currently supported values for <type> are gui,text (unstable), and pytext
+\end_inset
+</cell>
+</row>
+<row topline="false" bottomline="false" newpage="false">
+<cell multicolumn="0" alignment="center" valignment="top" topline="true"
bottomline="false" leftline="true" rightline="false" rotate="false"
usebox="none" width="" special="">
+\begin_inset Text
+
+\layout Standard
+
+--version
+\end_inset
+</cell>
+<cell multicolumn="0" alignment="left" valignment="top" topline="false"
bottomline="false" leftline="false" rightline="false" rotate="false"
usebox="none" width="" special="">
+\begin_inset Text
+
+\layout Standard
+
+Displays the current version information for this program.
+\end_inset
+</cell>
+</row>
+<row topline="false" bottomline="false" newpage="false">
+<cell multicolumn="0" alignment="center" valignment="top" topline="true"
bottomline="false" leftline="true" rightline="false" rotate="false"
usebox="none" width="" special="">
+\begin_inset Text
+
+\layout Standard
+
+\end_inset
+</cell>
+<cell multicolumn="0" alignment="left" valignment="top" topline="false"
bottomline="false" leftline="false" rightline="false" rotate="false"
usebox="none" width="" special="">
+\begin_inset Text
+
+\layout Standard
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+\SpecialChar ~
+Examples:
+\layout Standard
+
+1.
+ Run the form
+\begin_inset Quotes eld
+\end_inset
+
+samples.gfd
+\begin_inset Quotes erd
+\end_inset
+
+ without the opening splash screen:
+\layout LyX-Code
+
+gfclient --no_spash samples.gfd
+\layout Standard
+
+2.
+ Run the form
+\begin_inset Quotes eld
+\end_inset
+
+test.gfd
+\begin_inset Quotes erd
+\end_inset
+
+ located on the company's web server in debugging level 10:
+\layout LyX-Code
+
+gfclient -d 10 http://my.company.com/forms/samples.gf
\the_end