Applied Chris Browne's documentation patches.

git-svn-id: https://ledger-smb.svn.sourceforge.net/svnroot/ledger-smb/trunk@114 4979c152-3d1c-0410-bac9-87ea11338e46

4 files changed, 66 insertions, 139 deletions

diff --git a/doc/README.DB2 b/doc/README.DB2
index 9d143bef..e69de29b 100755
--- a/doc/README.DB2
+++ b/doc/README.DB2
@@ -1,82 +0,0 @@
-To build and install the DBD::DB2 module, you need the following: 
-
-*Perl 5.004_04 or later 
-*DBI 0.93 or later 
-*DB2 Application Development Client 
-*A supported C compiler as documented under 
- 'Supported Operating Systems' 
- at the DB2 Application Development Web page:
-
-http://www-3.ibm.com/software/data/db2/udb/ad/index.html
-
-Install Notes:
-
-http://www.perl.com/CPAN-local/modules/by-module/DBD/DBD-DB2-0.76.readme
-
-Module:
-
-http://www.perl.com/CPAN-local/modules/by-module/DBD/DBD-DB2-0.76.tar.gz
-
-Notes:
------------------------------
-
-LedgerSMB tested with IBM DB2 v7.2 and v8.1.
-Compiled for use with DBI 1.18 for all testing.
-
-DB2 Application Development Client used was with
-the DB2 Personal Developer's Edition (PDE). All
-databases and application code tested under RedHat
-Linux 7.2 kernel 2.4.7-10.
-
-ADDITIONAL NOTES: DB2 specific
-------------------------------
-
-1. DB2 installed under default owner, and group:
-   db2inst1 and db2grp1.
-   
-2. LedgerSMB app owner (ledger) was added to DB2 group db2grp1
-   thereby given SYSADM authority.
-   
-3. LedgerSMB app owner has same ENV variables as the db2inst1 user.
-   This can be added, or have:
-   . $DB_HOME/sqllib/db2profile  in the LedgerSMB app owner .(bash_)profile.
-   
-4. LedgerSMB app owner must have environment variable
-   DB2INSTANCE set.
-   
-5. LedgerSMB app owner, now with SYSADM authority and PATH
-   containing DB2's bin should run the following:
-   
-   prompt>:  db2set -all    # To view instance and registry variables 
-   prompt>:  db2set DB2DBDFT=your_default_database_name i.e. LEDGER
-   prompt>:  db2set DB2CLIINIPATH=set_to_usually $DB_HOME/sqllib/cfg
-   
-   Now, cd to the DB2CLIINIPATH directory and edit the db2cli.ini
-   file.  Continuing with our use of LEDGER as the database that
-   will be created and used, add:
-   
-   [LEDGER]
-   AUTOCOMMIT=1
-   LONGDATACOMPAT=1
-   DBALIAS=LEDGER
-   DEFERREDPREPARE=1
-   
-   If DEFERREDPREPARE=1 is the last line, add a blank line.  A blank
-   line must be the last line.
-   
-6. Create the database, objects, and initialize by moving to the directory:
-   /where_you_installed_SQL-Ledger/sql , and review the file
-   DB2-sql-ledger.order.  The commands outlined are in the required order,
-   create a database called LEDGER using default SMS tablespaces.  The
-   last command-line creates the "Default" Chart-of-Accounts.  
-   
-   *Modify the files at will to: 
-   	create a different named database (make sure you review the 
-   	step where you -> db2set DB2DBDFT=your_default_database_name) 
-   	
-   	create DMS tablespaces
-   	
-   	different Chart-of-Accounts.  
-   	
-   If a 'gifi' sql script needs to be run, make sure the 
-   "db2 -tvf" is used so the ';' are accepted as command terminators.
diff --git a/doc/coding-standard.tex b/doc/coding-standard.tex
index 424dbe24..23cf445e 100644
--- a/doc/coding-standard.tex
+++ b/doc/coding-standard.tex
@@ -8,7 +8,7 @@
 \tableofcontents
 
 \section{Introduction}
-Consistant coding style contributes to readability of code.  This contributes in
+Consistent coding style contributes to readability of code.  This contributes in
 turn to fewer bugs and easier debugging.
 
 While consultants which implement custom solutions for their customers are not
@@ -19,7 +19,7 @@ accepted in the main source tree.
 \section{File Organization and Whitespace}
 
 Files should be organized according to three principles: atomicity, performance,
-and readibility.  While there is no maximum file size, there is no reason to
+and readability.  While there is no stated maximum file size, there is no reason to
 group large amounts of code together when only a small subset of that code will
 be executed on any given run of the program.  Similarly, core API for a single
 data structure entity may be grouped together even if each run may touch only a
@@ -39,17 +39,19 @@ avoided.
 
 \section{Comments}
 
-In an ideal world, the code should be sufficiently readible to be entirely
-understandable without comments.  Unfortunately such an ideal is rarely
-attained.  Comments should be used to annotate code and add information that is
-not already a part of code or programming logic itself.  
+In an ideal world, the code should be sufficiently readable to be
+entirely understandable without comments.  Unfortunately, this sort of
+ideal is seldom attained.  Comments should be used to annotate code
+and add information that is not already a part of code or programming
+logic itself.
 
-Comments may include arguments and return values of functions (for easy
-reference), a summary as to why a particular design choice was made, or a note
-to alert future programmers that a particular chunk of code deserves additional
-attention.  Comments should not, however generaly tell what the program is doing
-or how it does that.  If such comments are required, it is a good indication
-that a block of code requires rewriting.
+Comments may include arguments and return values of functions (for
+easy reference), a summary as to why a particular design choice was
+made, or a note to alert future programmers that a particular chunk of
+code deserves additional attention.  Comments should not, however,
+merely indicate what the program is doing or how it does something.
+If such comments are required, that is a good indication that a block
+of code requires rewriting.
 
 Additionally it is a good idea to provide a brief description at the top of each
 file describing, in general terms, what its function is.
@@ -59,8 +61,8 @@ file describing, in general terms, what its function is.
 Functions should be atomic.  While there is no maximum length to functions, long
 functions may be an indication that a function may be non-atomic.
 
-In general, when more than one line of code is being copied and pasted, it 
-should instead be moved  into its own function where it can be called by all 
-entry points.
+In general, when more than one line of code is being copied and
+pasted, it should instead be moved into its own function where it can
+be called by all entry points.
 
 \end{document}
diff --git a/doc/faq.html b/doc/faq.html
index deb1fae9..80e68a2d 100755
--- a/doc/faq.html
+++ b/doc/faq.html
@@ -9,12 +9,15 @@ will fail to balance.  So this is a serious problem with data integrity.
 LedgerSMB prevents this by adding the NOT NULL constraing but this can cause
 prevent people from migrating when they have invalid data in their databases.
 <br/><br/>
-If you get an error like this the first thing to do is seek technical support
-whether or not you wish to continue the migration.  In general the providers of
-support for LedgerSMB and SQL-Ledger will all be able to help.  Unfortunately
-because this problem involves information loss, no solution can be automated
-without invalidating your accounting information.
-</li></p>
+
+If you encounter an error like this, the first thing to do is seek
+technical support, regardless of whether or not you wish to continue
+the migration.  In general the providers of support for LedgerSMB and
+SQL-Ledger should all be able to be of some assistance.
+Unfortunately, since this problem involves information loss, no
+solution can be automated without invalidating your accounting
+information.  </li></p>
+
 <p><li><h4>PostgreSQL 8.x</h4>
 PostgreSQL added a restriction in v8.x that a sequence cannot be dropped
 after if it is referenced by a table. However backups created with
@@ -50,17 +53,20 @@ SELECT SETVAL('jcitemsid', 53);
 </pre>
 
 
-<p><li><h4>PostgreSQL template1</h4>
-template1 is a template to build new databases
-from. Anything you put into template1 will be copied to a new database.
-So when you try to create a new dataset, the tables are already created from
-template1 and when LedgerSMB tries to create them you'll get an error that
-the tables already exist.
+<p><li><h4>PostgreSQL template1</h4> 
+
+<tt>template1</tt> is a template that new databases are built from, by
+default. Anything you put into <tt>template1</tt> will be copied to a
+new database.  Thus, when you try to create a new dataset, the tables
+are already drawn in from <tt>template1</tt> so that when LedgerSMB
+tries to create them, you will receive an error message indicating
+that the tables already exist.
 
 
 <p><li><h4>PostgreSQL 8.0+</h4>
-To use LedgerSMB with 8.0+ you have to modify Pg-tables.sql The file
-is in the sql directory.
+
+To use LedgerSMB with PostgreSQL 8.0+ you have to modify
+<tt>Pg-tables.sql</tt>. This file is in the sql directory.
 
 <pre>
 CREATE TABLE orderitems (
@@ -101,11 +107,11 @@ This change is only required for LedgerSMB versions 2.6.3 and below.
 
 <p>If you already built a dataset without this change you will get
 an error when you try to save a PO or assembly.
+
 <p>"ERROR: column "oid" does not exist"
 
 <p>Drop the tables and rebuild WITH OIDS.
 
-
 <p><li><h4>Japanese characters</h4>
 modify apache so that EUC_JP is the main additional language.
 <br>comment out all unrelated languages except, UTF_8 shift jis, EUC_JP
@@ -141,10 +147,10 @@ AR and AP account. Then edit all your transactions and repost.
 <p><li><h4>SELinux</h4>
 <a href=http://fedora.redhat.com/docs/selinux-faq-fc3/index.html>http://fedora.redhat.com/docs/selinux-faq-fc3/index.html</a>
 
-<p>modify /etc/selinux/conf and set SELINUX=permissive
+<p>modify <tt>/etc/selinux/conf</tt> and set <tt>SELINUX=permissive</tt>
 
-<p>use audit2allow and add the following to policy.conf,
-then run "make reload"
+<p>use <tt>audit2allow</tt>, add the following to
+<tt>policy.conf</tt>, then run <tt>make reload</tt>
 
 <p>#line 83
 <br>allow httpd_sys_script_t port_type:{ tcp_socket udp_socket } { send_msg
@@ -158,8 +164,8 @@ recv_msg };
 
 
 <p><li><h4>session timeouts</h4>
-If you get frequent timeouts or can't even log in synchronize
-the clocks from the server and workstation.
+If you get frequent timeouts or can't even log in, synchronize
+the clocks between the server and workstation.
 
 
 <p><li><h4>lineitems not printing</h4>
@@ -180,26 +186,27 @@ encoding when you set up a new dataset.
 <p><li><h4>characterset problems</h4>
 If you have problems displaying the correct characterset try adding
 <pre>
-  AddDefaultCharset On</pre>
-in your httpd.conf file.
+AddDefaultCharset On</pre>
+in your <tt>httpd.conf</tt> file.
 
 <p><li><h4>About installation</h4>
 The easiest is to use the setup.pl script as root.
 You don't need to know very much about your system, just login as root,
 run 'perl setup.pl' and follow the prompts.
 <p>setup.pl does not check for missing software packages and it is your
-responsibilite to make sure you have the required software
+responsibility to make sure you have the required software
 installed either from source or from a package.
 
-<p>Requirements are clearly indicated in the README file and on the
-download page.
+<p>Requirements are clearly indicated in the <tt>README</tt> file and
+on the download page.
 
 
 <p><li><h4>cannot create function</h4>
 <ol>
-<li>either run createlang and install the plpgsql language handler or
-install yourself. For more information how to do that, visit
-<a href=http://www.postgresql.org/docs/>PostgreSQL</a> and
+
+<li>either run <tt>createlang plpgsql</tt> to install the plpgsql
+language handler or install yourself. For more information how to do
+that, visit <a href=http://www.postgresql.org/docs/>PostgreSQL</a> and
 read the interactive documentation for procedural languages.
 
 <li>load admin.pl
@@ -210,9 +217,9 @@ read the interactive documentation for procedural languages.
 
 <p><li><h4>The requested URL /ledger-smb/admin.pl was not found</h4>
 Your webserver doesn't know where to find the script. Most commonly this
-is from distributions hiding webserver configuration files in different
-locations or files and setup.pl wasn't able to configure the location for
-you. Find out which file (httpd.conf, httpdcommon.conf, ...)
+results when distributions hide webserver configuration files in unexpected
+locations so that <tt>setup.pl</tt> wasn't able to configure the location for
+you. Find out which file (<tt>httpd.conf</tt>, <tt>httpdcommon.conf</tt>, ...)
 controls your webserver configuration and add
 <pre>
   # LedgerSMB
@@ -282,15 +289,16 @@ This is different with every distribution so look for it.
 fancy word for a local machine.
 'localhost' is a host like any other host on a network.
 A 'local' entry in pg_hba.conf will allow socket connections ONLY and
-not allow a host connection. If you then try to connect to 'localhost'
-postgres will come back with an authentication error.
+not allow a host connection. If you then try to connect to 'localhost',
+PostgreSQL will come back with an authentication error.
 
-<p>So, forget you ever heard there is such a thing as 'localhost' and leave
+<p>So, if the database resides on the same server as the web server,
+forget you ever heard there is such a thing as 'localhost' and leave
 the Host portion blank.
 
-<p><b>WARNING!</b> DO NOT just put a 'host  all all trust' in pg_hba.conf
-unless you know what you are doing.
-
+<p><b>WARNING!</b> DO NOT just put a 'host all all trust' in
+pg_hba.conf unless you know what you are doing; that can introduce a
+pretty huge security hole.
 
 <p><li><h4>DBD-Pg for Mandrake 9.0</h4>
 Mandrake did not package a compiled DBD-Pg package again, so install DBD-Pg
@@ -315,10 +323,9 @@ pagebreak block which must be commented out.
 When you are done with the changes
 replace << and >> with <% and %> and uncomment the pagebreak block.
 
-<p>LaTeX is difficult but it also offers a much superior environment
-to produce professionally looking forms in postscript and PDF format.
-Unfortunately with all that power there is also a steep learning curve.
-
+<p>LaTeX is somewhat complex to learn, initially, but offers a much
+superior environment to produce professional-looking forms in
+postscript and PDF format.
 
 <p><li><h4>W3M</h4>
 pass terminal=mozilla when you start w3m
diff --git a/doc/release_notes b/doc/release_notes
index 88371732..ca803b33 100644
--- a/doc/release_notes
+++ b/doc/release_notes
@@ -37,7 +37,7 @@ field of the transaction.
 
 Also, the transaction amount has been changed from FLOAT to NUMERIC so that
 arbitrary precision mathematics can be used in third party reports.  This ought
-to also allow SQL-Ledger to properly scale up better as SUM operations on
+to also allow LedgerSMB to properly scale up better as SUM operations on
 floating points are unsafe for large numbers of records where accounting data is
 involved.