gnue/gnuef/doc user_guide.lyx

[Jason Cater]

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